Getting Started

To get started with Komandan, you first need to install it on your system. Komandan is written in Rust, so you will need to have the Rust toolchain installed.

Installation

Pre-built binaries for Komandan are available for Linux on the GitHub Releases page.

An installation script is provided for easy installation:

curl -fsSL https://raw.githubusercontent.com/hahnavi/komandan/main/install.sh | sh

This script will download the latest Komandan release for your system and install Komandan to $HOME/.local/bin. Please make sure that $HOME/.local/bin is in your $PATH environment variable.

After the installation is complete, you can verify it by running:

komandan --version

This command should print the version of Komandan that you have installed.

Basic Usage

Once Komandan is installed, you can start using it to manage your remote servers. Here’s a basic example:

1. Create a Lua Script: Create a new file named main.lua (or any other name with a .lua extension) with the following content:

   local host = {
     address = "your_server_ip",
     user = "your_username",
     private_key_file = os.getenv("HOME") .. "/.ssh/id_rsa", -- Replace with your private key path
   }
   
   local task = {
       name = "Execute a simple command",
       komandan.modules.cmd({
           cmd = "hostname"
       })
   }
   
   komandan.komando(host, task)
   

   Replace "your_server_ip", "your_username", and the private_key_file with your server’s IP address, your username, and the path to your SSH private key, respectively.

2. Run the Script: Execute the script using the following command:

   komandan main.lua
   

   This command will connect to the specified server, execute the hostname command, and print the output.

This is a very basic example, but it demonstrates the fundamental principles of using Komandan. You can explore the Modules and Built-in Functions sections to learn more about the available features and how to use them.

komandan.komando function

The komando function is a function to execute a task on a host. It takes two arguments:

• host: a table that contains the following fields:
  • address: the IP address or hostname of the target server.
  • port: the SSH port to use for the connection (default is 22).
  • user: the username to connect to the server.
  • private_key_file: the path to the private key file for authentication.
  • private_key_pass: the passphrase for the private key file (optional).
  • password: the password to use for authentication if no private key is provided.
  • known_hosts_file: the path to the known_hosts file (optional).
  • host_key_check: a boolean that indicates whether to check the host key (default is true).
• task: a table that contains the following fields:
  • name: a string that describes the task. It is used for logging purposes. (optional)
  • module: a table that contains the module to be executed and its arguments. This field is defined without a key.
  • elevate: a boolean that indicates whether to run the task with elevated privileges. (default is false)
  • as_user: a string that contains the username to run the task as. (optional)
  • ignore_exit_code: a boolean that indicates whether to ignore the exit code of the task. If true, the script will continue even if the task returns a non-zero exit code. (default is false)

This function will execute the module on the target server and return the results:

• stdout: a string that contains the standard output of the module.
• stderr: a string that contains the standard error output of the module.
• exit_code: an integer that contains the exit code of the module.