Getting Started

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).
  • 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)
  • env: a table that contains environment variables to be set for the task. (optional)
• 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)
  • env: a table that contains environment variables to be set for the task. (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.