IT Operations (Command Orchestrator)¶

Concepts¶

Executing predefined commands (also remotely) on hosts without having access to them can be very useful in many situations. For example, a first level support agent using NetEye may need to restart a Windows service on a Windows host without access to it.

The Command Orchestrator module lets the NetEye admin define Commands and Groups of Commands which can be assigned to other non-admin NetEye users, who will then be able to execute them through the Command Orchestrator module itself.

Note

The configuration of the Command Orchestrator can be currently carried out from the command line only.

Architecture of the Command Orchestrator Module¶

The Command Orchestrator Manager module is based on three main objects: the Command, the Command Group, Command Parameter. Each Command must belong to a Command Group, and Command Groups can be sub-groups of other Command Groups.

A Command defines the execution of a command and is composed of:
- a name for the command
- a command type, which defines if the Command is to be executed remotely, locally on NetEye, or if it is a web link.
- a command, which is the actual executable to be executed on the host
- some command parameters that define with which parameters the Command must be launched. A parameter of the Command can also be a macro, whose value will be chosen by the user who executes the command. The possible values for each macro have to be declared in the Command Parameter objects.
- a monitoring object filter that defines on which hosts the command can be executed
- the Command Group which the Command is part of
A Command Group permits to create groups of Commands, for an easier management. It can either be at the top of the hierarchy of the Command Groups, or can be a child of another Command Group.
A Command Parameter defines which are the possible values that a macro (a dynamic Command parameter) can take when a user executes a Command. The administrator defines in the Command Parameter object if the macro can take either any numeric value, or any string value coming from a predefined list of strings.

Authorization in the Command Orchestrator Module¶

The NetEye administrator can create Command Groups and assign them to Roles. If the Role is configured with execute permission, Users with that Role can execute the Commands in the Groups.

A user having access to a Command Group has access to all the Commands in that Group, and to all its descendants.

Note

The execute permission is module-wide; this implies that the User can execute commands in all Commands Groups he has access to. In case multiple roles are associated to a user, command execution is enabled if in at least one of the roles this permission is enabled.

Each NetEye user can only execute Commands on the hosts which he has access to in the Monitoring module. In addition to this restriction, each Command defines on which hosts the Command itself can be executed.

Configuration¶

Command Orchestrator Configuration CLI Commands¶

You can configure the Command Orchestrator directly from the shell with the icingacli command.

By using the Command Orchestrator’s CLI commands, you can perform create, edit, delete and list actions on the following cmdorchestrator objects:

Command: A Command which contains all the information for the execution of a command.
Command Group: A group representing a set of Commands. A Command Group can be child of another Command Group. Each Command Group can then contain some other Command Groups and some Commands.
Command Parameter: A Command Parameter which contains all the information for the possible value of the parameter (macro) i.e., $param$.

Note

Once you finish configuring the Command Orchestrator objects, you need to deploy the Director configuration in order to execute the Commands.

Below you can find detailed descriptions of the available commands and their parameters.

Command Orchestrator User¶

Command orchestrator use a specific user called cmdorchestrator to access icinga2 APIs. The configuration is automatically generated during neteye install with a random password and must not be modified by the user.

Credentials can be found in the file /neteye/shared/icinga2/conf/icinga2/conf.d/cmdorchestrator-users.conf e.g.:

object ApiUser "cmdorchestrator" {
  password = "sBNLspMn59m6vViO"
  permissions = [ "objects/query/host","objects/query/service","actions/execute-command" ]
}

cmdorchestrator user has only permissions to query host and services and execute commands.

CLI configuration of Command¶

Create

The create command lets you construct a new Command. It requires a name, a type for the command, the command to be executed, the parameters with which the command must be executed, a monitoring object filter (only in case of remote command) and a Command Group ID.

Usage:

# icingacli cmdorchestrator command create [parameters]

Available Parameters:

--name:

(mandatory) The name of the Command to be created.

--command-type:

(mandatory) The type of the Command, which can take one of the following values:

remotethe Command will be executed remotely on the host/s
specified upon execution.
local : the Command will be executed from the NetEye host.
weblinkthe execution of the Command will open a link in a new tab
of the user’s browser. The link will point to the url specified in the command field

--command:

(mandatory) The command (the executable) to be executed.

--command-parameters:

(optional) A JSON array defining the parameters with which command will be executed. Parameters can include macros in the form $myparam$ , which will be substituted upon execution.

--monitoring-object-filter:

(mandatory only if command-type is remote ) A Monitoring Object Filter which restricts the execution of the command to the set of hosts defined by the filter.

--command-group-id:

(mandatory) The ID of the Command Group to which this Command belongs to.

--description:

(optional) A text description of what the Command Parameter represents.

--timeout:

(optional) The maximum time the command is allowed to run before it is killed. The value should be a number, followed by a unit (s)econds, (m)inutes, (h)ours or (d)ays, e.g. 60s, 1.5m, 0.25h, etc. The timeout defaults to the standard icinga2 timeout duration of 60 seconds.

Example:

# icingacli cmdorchestrator command create \
            --name 'touch_file' \
            --command-type 'remote' \
            --command '/usr/bin/touch' \
            --command-parameters '["/tmp/myfile"]' \
            --monitoring-object-filter 'host_name=neteye*' \
            --command-group-id '1' \
            --description 'This command will create the selected file on the system'
            --timeout '1s'

Edit

By using the edit command, you change one or more of the values for the fields in an existing Command using the same parameters as the command create command above.

Usage:

# icingacli cmdorchestrator command edit [parameters]

List

With list command you can see a list of all existing Commands in JSON format.

Usage:

# icingacli cmdorchestrator command list

Delete

The delete command allows you to remove an existing Command given its ID, which you can obtain from the list command.

Usage:

# icingacli cmdorchestrator command delete [parameters]

Available Parameters:

--id:: (mandatory) The ID of the Command to delete

CLI configuration of Command Group¶

Create

You can use the create command to construct a new Command Group. It requires a name and, optionally, a description and a parent Command Group ID.

Usage:

# icingacli cmdorchestrator commandgroup create [parameters]

Available Parameters:

--name:: (mandatory) The name of the Command Group to be created. All alphanumeric characters are allowed in the name, plus the characters - and _.
--description:: (optional) A text description of what the Command Group represents.
--parent-command-group-id:: (optional) The ID of the Command Group which is the parent of this Command Group. If not specified, the newly created Command Group will have no parent and will then be at the top of the hierarchy.

Example:

# icingacli cmdorchestrator commandgroup create \
            --name 'linux' \
            --description 'commands to be run on linux systems' \
            --parent-command-group-id '1'

Edit

With the edit command it is possible to change one or more of the values for the fields in an existing Command Group using the same parameters as the commandgroup create command above.

Usage:

# icingacli cmdorchestrator commandgroup edit [parameters]

List

With the list command you can see a list of all existing Command Groups in JSON format.

Usage:

# icingacli cmdorchestrator commandgroup list

Delete

The delete command allows you to remove an existing Command Group given its ID, which you can obtain from the list command.

Usage:

# icingacli cmdorchestrator commandgroup delete [parameters]

Available Parameters:

--id:: (mandatory) The ID of the Command Group to delete

CLI configuration of Command Parameter¶

Create

By using the create command you construct a new Command Parameter i.e., Macro. It requires a command ID, a parameter name (macro), a type for the parameter and, optionally, a possible values for the command parameter.

Usage:

# icingacli cmdorchestrator commandparameter create [parameters]

Available Parameters:

--command-id:: (mandatory) The ID of the Command to which this macro (a dynamic Command parameter) belongs to.
--parameter:: (mandatory) The name of the macro for the Command.
--parameter-type:: (mandatory) The type of the macro i.e, string or number.
--description:: (optional) A text description of what the Command Parameter represents.
--label:: (optional) A text that is shown instead of the parameters name in the UI.
--possible-values:: (optional) The possible values that a macro can take when a user executes a Command. The possible value is only required with parameter-type as string and must be valid JSON array which contains only string values.

Example:

# icingacli cmdorchestrator commandparameter create \
            --command-id '1' \
            --parameter '$touch_file$' \
            --parameter-type 'string' \
            --possible-values '["/tmp/testfile1", "/tmp/testfile2"]' \
            --description 'The file on the system you want to touch' \
            --label 'File path'

Edit

The edit command allows to change one or more of the values for the fields in an existing Command Parameter using the same parameters as the commandparameter create command above.

Usage:

# icingacli cmdorchestrator commandparameter edit [parameters]

List

With the list command you can see a list of all existing Command Parameter in JSON format.

Usage:

# icingacli cmdorchestrator commandparameter list

Delete

The delete command lets you remove an existing Command Parameter given its ID, which you can obtain from the list command.

Usage:

# icingacli cmdorchestrator commandparameter delete [parameters]

Available Parameters:

--id:: (mandatory) The ID of the Command Parameter to delete

Command Execution¶

Once all Commands, Command Groups and Command Parameters have been configured (and the Director deploy has been triggered), it is then possible to launch the execution of the defined Commands.

GUI command execution¶

The execution of the Commands can be perfomed by authorized users from the NetEye GUI. Under the menu entry CMDO, you will find the tabs Command Group, Command and Last Execution Result.

In the Command Group tab you find the list of all the Command Groups present in the Command Orchestrator. Clicking on one Command Group lets you see the list children Commands of that Group. From the Commands list, selecting one Command lets you configure the execution of the Command, and execute it.

The Command tab shows the list of all the Commands defined in the Command Orchestrator.

In the Last Execution Result tab you can find instead the result of the last Command that you executed.

Note

The Last Execution Result will be available only until the Icinga2 execution TTL expires (this is set in /neteye/shared/icingaweb2/conf/modules/cmdorchestrator/config.ini and defaults to 20 minutes).

The Last Execution Result tab only works within the web session in which you executed the Command. This means that after a logout from NetEye, the Execution Result will not be available anymore.

CLI Command Execution¶

From CLI it is possible to execute the Commands via REST API.

The endpoint for the command execution is https://<neteye_host>/neteye/cmdorchestrator/executecommand and the request must be authenticated with the user’s NetEye credentials.

The JSON payload of the request must contain:

command_id: the ID of the Command that we want to execute
host: the hostname of the host on which the Command must be executed. This field is only required if the command type of the associated command_id is remote.
parameter_values: a (possibly empty) map "$parameter_name$": "parameter_value" that defines the value of the Command Parameters. The parameter value must be compliant with what was configured in the Command Parameter objects related to the Command.

Below you can find an example of a valid curl call to the executecommand REST API:

curl -u '<neteye_username>:<neteye_password>' -XPOST \
        -H 'Accept: application/json' \
        -H "Content-Type: application/json" \
        'https://<neteye_host>/neteye/cmdorchestrator/executecommand'
        -d '{
              "command_id": 1,
              "host": "myhost",
              "parameter_values": {
                "$path_to_file$": "/tmp/myfile"
              }
            }'

In case of the command execution is accepted, the response of the REST API will be similar to the following:

"{\"results\":[{\"checkable\":\"9b6ce3354241\",\"code\":202.0,\"execution\":\"793ad112-1edc-46bd-86de-7f885421a199\",\"status\":\"Accepted\"}]}"

The executecommand API aforementioned does not return the result of the command because it will be executed asynchronously. To monitor the command execution you can use the icingacli cmdorchestrator execution command to retrieve the execution status.

The --token parameter is mandatory, token value is returned in the response of executecommand REST API

Below you can find an example of a valid CLI command with the token provided by the example above:

icingacli cmdorchestrator execution show --token 793ad112-1edc-46bd-86de-7f885421a199