Custom Module

• 1: Create a Custom Module
• 2: Module Helper Functions

1 - Create a Custom Module

To create a custom module, you can create a function that returns a komandan.KomandanModule object. The argument should contain the name field of the module.

The main function of the module is the run function. This function should contain the code that will be executed. To send a command or another action to the target server, you can use the helper functions provided by Komando. (see Module Helper Functions)

To create a cleanup function, you can use the cleanup function. This function will be executed after the run function.

Example of a Custom Module

function my_module(params)
  let module = komandan.KomandanModule:new({ name = "My Module", params = params })

  module.run = function(self)
    self.ssh:cmd("mkdir /tmp/" .. self.params.dirname)
  end

  module.cleanup = function(self)
    -- Cleanup code
  end

  return module
end

In the example above, the my_module function returns a komandan.KomandanModule object. The name field of the module is set to “My Module”. The run function of the module creates a directory on the target server with name from the dirname argument.

Usage Example of a Custom Module

local host = {
  address = "10.20.30.41",
  user = "user1",
}

local task = {
  name = "Run custom module",
  my_module({
    dirname = "test"
  })
}

komandan.komando(host, task)

2 - Module Helper Functions

Komandan provides several helper functions that can be used to send commands or other actions to the target server from a custom module. (see Create a Custom Module)

module.ssh:cmd

This function sends a command to the target server using SSH. The function takes one arguments:

• cmd: a string that contains the shell command to be executed.

The function returns a table with the following fields:

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

module.ssh:write_remote_file

This function writes a file to the target server using SSH. The function takes two arguments:

• remote path: a string that contains the path to the destination file on the target server.
• content: a string that contains the content to be written to the file.

The function does not return any value.

module.ssh:upload

This function uploads a file to the target server using SSH. The function takes two arguments:

• local path: a string that contains the path to the local file to be uploaded.
• remote path: a string that contains the path to the destination file on the target server.

The function does not return any value.

module.ssh:download

This function downloads a file from the target server using SSH. The function takes two arguments:

• remote path: a string that contains the path to the remote file to be downloaded.
• local path: a string that contains the path to the destination file on the local machine.

The function does not return any value.

module.ssh:get_remote_env

This function gets the environment variables from the target server using SSH. The function takes one argument:

• var: a string that contains the name of the environment variable to be retrieved.

The function returns a string that contains the value of the environment variable.

module.ssh:get_tmpdir

This function returns the path to the temporary directory for Komandan on the target server. The function does not take any arguments. The function returns a string that contains the path to the temporary directory. The default tmpdir is $HOME/.komandan/tmp, otherwise it will be /tmp/komandan.

module.ssh:chmod

This function changes the permissions of a file on the target server using SSH. The function takes two arguments:

• remote_path: a string that contains the path to the file to be changed.
• mode: a string that contains the permissions to be set.