Navigate into Configuration
-> Modules
-> Monitoring
-> Backends
. You can
create/edit command transports here.
The commandtransports.ini
configuration file defines how
Icinga Web 2 transports commands to your Icinga instance in order to
submit external commands. By default, this file is located at
/etc/icingaweb2/modules/monitoring/commandtransports.ini
.
You can define multiple command transports in the
commandtransports.ini
file. Every transport starts with a
section header containing its name, followed by the config directives
for this transport in the standard INI-format.
Icinga Web 2 will try one transport after another to send a command
until the command is successfully sent. If configured,
Icinga Web 2 will take different instances into account. The order in
which Icinga Web 2 processes the configured transports is defined by the
order of sections in commandtransports.ini
.
If you're running Icinga 2 it's best to use the Icinga 2 API for transmitting external commands.
You have to run the api
setup on the Icinga 2 host where
you want to send the commands to:
icinga2 api setup
Next, you have to create an ApiUser object for authenticating against
the Icinga 2 API. This configuration also applies to the host where you
want to send the commands to. We recommend to create/edit the file
/etc/icinga2/conf.d/api-users.conf
:
object ApiUser "icingaweb2" {
password = "bea11beb7b810ea9ce6ea" // Change this!
permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}
The permissions are mandatory in order to submit all external commands from within Icinga Web 2.
Restart Icinga 2 for the changes to take effect.
systemctl restart icinga2
Note
Please make sure that your server running Icinga Web 2 has the
PHP cURL
extension installed and enabled.
The Icinga 2 API requires the following settings:
Option | Description |
---|---|
transport | Required. The transport type. Must be set to
api . |
host | Required. The host address where the Icinga 2 API is listening on. |
port | Required. The port where the Icinga 2 API is
listening on. Defaults to 5665 . |
username | Required. Basic auth username. |
password | Required. Basic auth password. |
Example:
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
[icinga2]
transport = "api"
host = "127.0.0.1" ; Icinga 2 host
port = "5665"
username = "icingaweb2"
password = "bea11beb7b810ea9ce6ea" ; Change this!
A local Icinga instance requires the following settings:
Option | Description |
---|---|
transport | Required. The transport type. Must be set to
local . |
path | Required. The absolute path to the local command pipe. |
Example:
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
[icinga2]
transport = local
path = /var/run/icinga2/cmd/icinga2.cmd
When commands are being sent to the Icinga instance, Icinga Web 2
opens the file found on the local filesystem underneath
path
and writes the external command to it.
Please note that errors are not returned using this method. The Icinga 2 API sends error feedback.
A command pipe on a remote host's filesystem can be accessed by configuring a SSH based command transport and requires the following settings:
Option | Description |
---|---|
transport | Required. The transport type. Must be set to
remote . |
path | Required. The path on the remote server to its local command pipe. |
host | Required. The SSH host. |
port | Optional. The SSH port. Defaults to
22 . |
user | Required. The SSH auth user. |
resource | Optional. The SSH resource |
instance | Optional. The Icinga instance name. Only required for multiple instances. |
Example:
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
[icinga2]
transport = remote
path = /var/run/icinga2/cmd/icinga2.cmd
host = example.tld
user = icinga
;port = 22 ; Optional. The default is 22
To make this example work, you'll need to permit your web-server's user public-key based access to the defined remote host so that Icinga Web 2 can connect to it and login as the defined user.
You can also make use of a dedicated SSH resource to permit access for a different user than the web-server's one. This way, you can provide a private key file on the local filesystem that is used to access the remote host.
To accomplish this, a new resource is required that is defined in your transport's configuration instead of a user:
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
[icinga2]
transport = remote
path = /var/run/icinga2/cmd/icinga2.cmd
host = example.tld
resource = example.tld-icinga2
;port = 22 ; Optional. The default is 22
The resource's configuration needs to be put into the resources.ini file:
# vim /etc/icingaweb2/resources.ini
[example.tld-icinga2]
type = ssh
user = icinga
private_key = /etc/icingaweb2/ssh/icinga
If there are multiple but different Icinga instances writing to your
IDO database, you can define which transport belongs to which Icinga
instance by providing the instance
setting. This setting
must specify the name of the Icinga instance you want to assign to the
transport:
[icinga1]
...
instance = icinga1
[icinga2]
...
instance = icinga2
Associating a transport to a specific Icinga instance causes this transport to be used to send commands to the linked instance only. Transports without a linked Icinga instance are used to send commands to all instances.