tyler.durden/icingaweb2
1
0
Fork 0
mirror of https://github.com/Icinga/icingaweb2.git synced 2025-04-08 17:15:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

Document how to use the Icinga 2 API for transmitting external commands

Browse Source
This commit is contained in:
Eric Lippmann 2016-09-08 16:10:01 +02:00
parent 33506b2965
commit fc086adf21
1 changed files with 53 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
modules/monitoring/doc/commandtransports.md
View File

@ -1,24 +1,56 @@
# <a id="commandtransports"></a> The commandtransports.ini configuration file
# <a id="commandtransports"></a> External Command Transport Configuration
## Abstract
## Introduction
The commandtransports.ini defines how Icinga Web 2 accesses the command pipe of
your Icinga instance in order to submit external commands. Depending on the
config path (default: /etc/icingaweb2) of your Icinga Web 2 installation you can
find it under ./modules/monitoring/commandtransports.ini.
The `commandtransports.ini` 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`.
## Syntax
You can define multiple command transports in the `commandtransports.ini`. Every transport starts with a section header
containing its name, followed by the config directives for this transport in the standard INI-format.
You can define multiple command transports in the commandtransports.ini. 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](#commandtransports-multiple-instances), 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`.
Icinga Web 2 will try one transport after another to send a command, depending
on the respective Icinga instance, until the command is successfully sent. The
order in which Icinga Web 2 processes the configured transports is defined by
the order of sections in the commandtransports.ini.
## Use the Icinga 2 API
## Using a local command pipe
If you're running Icinga 2 it's best to use the Icinga 2 API for transmitting external commands.
First, you have to enable the `api` feature on the Icinga 2 host where you want to send the commands to:
```
icinga2 feature enable api
```
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 "web2" {
password = "bea11beb7b810ea9ce6ea" // Change this!
permissions = [ "actions/*", "objects/modify/hosts", "objects/modify/services", "objects/modify/icingaapplications" ]
}
```
The permissions `actions/*`, `objects/modify/hosts`, `objects/modify/services`, `objects/modify/icingaapplications` are
mandatory in order to submit all external commands from within Icinga Web 2.
**Restart Icinga 2** for the changes to take effect.
After that, you have to set up Icinga Web 2's `commandtransport.ini` to use the Icinga 2 API:
```
[icinga2]
transport = "api"
host = "127.0.0.1" // Icinga 2 host
port = "5665"
username = "web2"
password = "bea11beb7b810ea9ce6ea" // Change that!
```
## Use a Local Command Pipe
A local Icinga instance requires the following directives:
@ -31,7 +63,7 @@ path = /var/run/icinga2/cmd/icinga2.cmd
When sending commands to the Icinga instance, Icinga Web 2 opens the file found
on the local filesystem underneath 'path' and writes the external command to it.
## Using SSH for accessing a remote command pipe
## Use SSH For a Remote Command Pipe
A command pipe on a remote host's filesystem can be accessed by configuring a
SSH based command transport and requires the following directives:
@ -74,11 +106,10 @@ user = icinga
private_key = /etc/icingaweb2/ssh/icinga
```
## Configuring transports for different Icinga instances
## <a id="commandtransports-multiple-instances"></a> Configure Transports for Different Icinga Instances
If there are multiple but different Icinga instances writing to your IDO you can
define which transport belongs to which Icinga instance by providing the
directive 'instance'. This directive should contain the name of the Icinga
If there are multiple but different Icinga instances writing to your IDO, you can define which transport belongs to
which Icinga instance by providing the directive `instance`. This directive should contain the name of the Icinga
instance you want to assign to the transport:
```
@ -91,6 +122,5 @@ instance = icinga1
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 utilized to send commands to all instances.
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.