This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Functions

Komandan provides several built-in functions that can be used to help write scripts.

1 - komando

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

Usage Example

local host = {
  address = "10.20.30.41",
  user = "user1",
  private_key_file = "/path/to/private/key",
}

local task = {
  name = "install neovim package",
  komandan.modules.apt({
    package = "neovim",
    update_cache = true
  }),
  elevate = true,
}

komandan.komando(host, task)

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.

2 - komando_parallel_hosts

The komando_parallel_hosts function is a function to execute a task on multiple hosts in parallel. It takes two arguments:

  • hosts: a table that contains the hosts to execute the task on. Each host is represented by 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.
  • 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)
    • env: a table that contains environment variables to be set for the task. (optional)

Usage Example

local hosts = {
  {
    address = "10.20.30.41",
    user = "user1",
    private_key_file = "/path/to/private/key",
  },
  {
    address = "10.20.30.42",
    user = "user2",
    private_key_file = "/path/to/private/key",
  },
  {
    address = "10.20.30.43",
    user = "user3",
    private_key_file = "/path/to/private/key",
  }
}

local task = {
  name = "install neovim package",
  komandan.modules.apt({
    package = "neovim",
    update_cache = true
  }),
  elevate = true,
}

komandan.komando_parallel_hosts(hosts, task)

This function will execute the module on the target server and return a table with the following 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.

3 - komando_parallel_tasks

The komando_parallel_hosts function is a function to execute multiple task on a host in parallel. 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.
  • tasks: a table that contains the tasks to be executed on the target host. Each task is represented by 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)
    • env: a table that contains environment variables to be set for the task. (optional)

Usage Example

local host = {
  address = "10.20.30.41",
  user = "user1",
  private_key_file = "/path/to/private/key",
}

local tasks = {
  {
    name = "install neovim package",
    komandan.modules.apt({
      package = "neovim",
      update_cache = true
    }),
    elevate = true,
  },
  {
    name = "mkdir",
    komandan.modules.cmd({
      cmd = "mkdir /tmp/new_dir"
    })
  },
  {
    name = "ls",
    komandan.modules.cmd({
      cmd = "ls -hal"
    })
  }
}

komandan.komando_parallel_tasks(host, tasks)

This function will execute the module on the target server and return a table with the following 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.

4 - filter_hosts

The filter_hosts function takes two arguments:

  • hosts: a table that contains the hosts to filter.
  • pattern: a string that contains the name or tag to filter the hosts. It can be a regular expression by adding ~ at the beginning of the pattern.

The function returns a table that contains the filtered hosts.

Usage Example

local hosts = {
  {
    name = "server1",
    address = "10.20.30.41",
    tags = { "webserver", "database" },
  },
  {
    name = "server2",
    address = "10.20.30.42",
    tags = { "webserver" },
  },
  {
    name = "server3",
    address = "10.20.30.43",
    tags = { "database" },
  },
}

local filtered_hosts = komandan.filter_hosts(hosts, "webserver")

This will return the table filtered_hosts that contains only the hosts that have the name or tag webserver.

5 - parse_hosts_json_file

The parse_hosts_json_file function takes one argument:

  • src: a string that contains the path to the JSON file.

The function returns a table that contains the parsed hosts.

Usage Example

hosts.json:

[
  {
    "name": "server1",
    "user": "user1",
    "address": "10.20.30.41",
    "tags": ["webserver", "database"]
  },
  {
    "name": "server2",
    "user": "user2",
    "address": "10.20.30.42",
    "tags": ["webserver"]
  },
  {
    "name": "server3",
    "user": "user3",
    "address": "10.20.30.43",
    "tags": ["database"]
  }
]

main.lua:

local hosts = komandan.parse_hosts_json_file("/path/to/hosts.json")

This will return the table hosts that contains the parsed hosts.

6 - parse_hosts_json_url

The parse_hosts_json_url function takes one argument:

  • src: a http/https URL that contains the path to the JSON file.

The function returns a table that contains the parsed hosts.

Usage Example

main.lua:

local hosts = komandan.parse_hosts_json_url("https://example.com/hosts.json")

This will return the table hosts that contains the parsed hosts.

7 - Default Values

Komandan provides default values for various parameters, such as the user, private key file path, and SSH port. These values can be set using the komandan.defaults userdata using setters.

-- set default values
komandan.defaults:set_port(22)
komandan.defaults:set_user("user1")
komandan.defaults:set_private_key_file(os.getenv("HOME") .. "/.ssh/id_ed25519")
komandan.defaults:set_private_key_pass("passphrase")
komandan.defaults:set_host_key_check(false)
komandan.defaults:set_env("ENV_VAR", "value")

-- get default values
local port = komandan.defaults:get_port()
local user = komandan.defaults:get_user()
local private_key_file = komandan.defaults:get_private_key_file()
local private_key_pass = komandan.defaults:get_private_key_pass()
local host_key_check = komandan.defaults:get_host_key_check()
local env = komandan.defaults:get_env("ENV_VAR")
local env_all = komandan.defaults:get_all_env()