Configure Tool Runner

Tool Runner allows an administrator to set up custom scripts to run on a server. It uses ssh to run tools and integrations. You must edit the servlets configuration file in Moogsoft Enterprise in order to use Tool Runner in the UI.

Warning

The Tool Runner user can run any command on the operating system. Only implement Tool Runner if absolutely necessary and follow the security-related recommendations closely.

Before you begin

Before you begin to configure Tool Runner, ensure you have met the following requirements:

  • You have created or identified an operating system user that you will use to run tools:

    • Do not run Tool Runner as root.

    • Run Tool Runner in a user-restricted shell, for example, bash --restricted. See also https://www.gnu.org/software/bash/manual/html_node/.

    • Run Tool Runner as a non-privileged user.

    • Allow specific permissions to Tool Runner so that it only accesses the tools it needs.

  • You have identified a separate host or a sandboxed environment. Moogsoft recommends that you do not run Tool Runner locally.

  • You have the permissions to modify Moogsoft Enterprise configuration files.

  • You have set the PasswordAuthentication property to yes in the /etc/ssh/sshd_config file on the Moogsoft Enterprise server and restarted the sshd service.

Configure Tool Runner

To manually configure Tool Runner, edit the servlets configuration file located at $MOOGSOFT_HOME/config/servlets.conf:

  1. You can configure these properties in the toolrunner section of the file:

    • toolrunnerhost: The host on which Tool Runner runs commands. This should not be the host on which Moogsoft Enterprise is installed.

    • toolrunneruser: The Tool Runner username. The user must exist on the toolrunnerhost system and have the appropriate permissions to run the required tools.

    • toolrunnerport: SSH port on which to run Tool Runner. Default is 22.

    • toolrunnerpassword: The Tool Runner user password on the toolrunnerhost system.

      If the password is not defined, Tool Runner uses the public key defined in ssh_key_file, or if that is not set, $MOOGSOFT_HOME/etc/keys/id_rsa.

      For ssh_key_file, if the path is a relative path, it is assumed to be relative to $MOOGSOFT_HOME/etc. Your SSH key should have a passphrase set. You can specify this in the configuration file in encrypted form under encrypted_ssh_passphrase or in plaintext (not recommended) in ssh_passphrase.

      If neither is set, the assumed password is keyPwd.

    • encrypted_toolrunnerpassword: An encrypted Tool Runner password. Use either the password or encrypted password property. See Moog Encryptor for more information.

    • execute_locally: If set to true, Tool Runner executes commands on the server where the Tool Runner servlet is hosted and ignores toolrunnerhost. Otherwise, commands are run on toolrunnerhost. Default is false.

    • webhost: Not used.

    • sshtimeout: SSH timeout period in milliseconds. If set to 0, timeout will never occur. Default is 0.

  2. Restart Apache Tomcat.

  3. Restart Moogfarmd.

Once you have completed the configuration, Tool Runner is available in the Moogsoft Enterprise UI.

An example toolrunner section in the servlets configuration file:

toolrunner:
{
    toolrunnerhost                  : "localhost",
    toolrunneruser                  : "moogtoolrunner",
    toolrunnerport                  : 22,
    toolrunnerpassword              : "moogtoolrunner",
    #encrypted_toolrunnerpassword   : "rmW2daCwMyI8JGZygfEJj0MZdbIkUqX3tT/OIVfMGyI=",
    #execute_locally                : false,
    #webhost                        : "https://localhost",
    sshtimeout                      : 900000
}