tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-26 07:04:37 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source 
refs #9105
This commit is contained in:
Gunnar Beutner 2015-11-07 13:49:14 +01:00
parent ced341286c
commit d975e47c2c
2 changed files with 37 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
doc/8-cli-commands.md
View File

@ -153,7 +153,7 @@ The CLI command `console` can be used to evaluate Icinga config expressions, e.g
On operating systems without the `libedit` library installed there is no On operating systems without the `libedit` library installed there is no
support line-editing or a command history. However you can support for line-editing or a command history. However you can
use the `rlwrap` program if you require those features: use the `rlwrap` program if you require those features:
$ rlwrap icinga2 console $ rlwrap icinga2 console
@ -162,29 +162,40 @@ The `console` can be used to connect to a running Icinga 2 instance using
the [REST API](9-icinga2-api.md#icinga2-api). [API permissions](9-icinga2-api.md#icinga2-api-permissions) the [REST API](9-icinga2-api.md#icinga2-api). [API permissions](9-icinga2-api.md#icinga2-api-permissions)
are required for executing config expressions and auto-completion. are required for executing config expressions and auto-completion.
The `--connect` parameter expects the API URL as string, optionally with basic auth credentials: > **Note**
> The console does not currently support SSL certificate verification.
$ icinga2 console --connect 'https://root:icinga@localhost:5665/' You can specify the API URL using the `--connect` parameter.
Although the password can be specified there process arguments on UNIX platforms are usually visible to other users (e.g. through `ps`). In order to securely specify the user credentials the console supports two environment variables:
Environment variable | Description
---------------------|-------------
ICINGA2_API_USERNAME | The API username.
ICINGA2_API_PASSWORD | The API password.
Here's an example:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.4.0) Icinga 2 (version: v2.4.0)
<1> => <1> =>
Example using [object accessor functions](19-library-reference.md#object-accessor-functions) Once connected you can inspect variables and execute other expressions by entering them at the prompt:
to fetch the host object for the local node and print its `last_check_result` attribute:
<1> => NodeName <1> => var h = get_host("mbmif.int.netways.de")
"icinga2-node1.localdomain" null
<2> => get_host(NodeName).last_check_result <2> => h.last_check_result
{ {
active = true active = true
check_source = "icinga2-node1.localdomain" check_source = "mbmif.int.netways.de"
command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ] command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
execution_end = 1446716536.250887 execution_end = 1446653527.174983
execution_start = 1446716532.222686 execution_start = 1446653523.152673
exit_status = 0.000000 exit_status = 0.000000
output = "PING OK - Packet loss = 0%, RTA = 0.08 ms" output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
performance_data = [ "rta=0.076000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ] performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
schedule_end = 1446716536.250992 schedule_end = 1446653527.175133
schedule_start = 1446716592.210000 schedule_start = 1446653583.150000
state = 0.000000 state = 0.000000
type = "CheckResult" type = "CheckResult"
vars_after = { vars_after = {
@ -202,11 +213,12 @@ to fetch the host object for the local node and print its `last_check_result` at
} }
<3> => <3> =>
In order to evaluate a single config expression use the `--eval`
parameter. The following example prints the command line from
the local node's last check result:
$ icinga2 console --connect 'https://root:icinga@localhost:5665/' --eval "get_host(NodeName).last_check_result.command" | python -m json.tool You can use the `--eval` parameter to evaluate a single expression in batch mode. The output format for batch mode is JSON.
Here's an example that retrieves the command that was used by Icinga to check the `example-host` host:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("example-host").last_check_result.command' | python -m json.tool
[ [
"/usr/local/sbin/check_ping", "/usr/local/sbin/check_ping",
"-H", "-H",
@ -217,25 +229,6 @@ the local node's last check result:
"3000,80%" "3000,80%"
] ]
The following environment variables can be exported to the
user's environment instead of adding them to the `--connect` parameter:
Environment Variable | Description
----------------------|--------------------------
ICINGA2_API_USERNAME | Basic auth username.
ICINGA2_API_PASSWORD | Basic auth password.
ICINGA2_API_URL | URL with or without basic auth credentials.
Example:
$ export ICINGA2_API_USERNAME=root
$ export ICINGA2_API_PASSWORD=icinga
$ icinga2 console --connect 'https://localhost:5665/'
Icinga 2 (version: v2.4.0)
<1> =>
## <a id="cli-command-daemon"></a> CLI command: Daemon ## <a id="cli-command-daemon"></a> CLI command: Daemon
The CLI command `daemon` provides the functionality to start/stop Icinga 2. The CLI command `daemon` provides the functionality to start/stop Icinga 2.

77
doc/9-icinga2-api.md
View File

@ -2,8 +2,9 @@
## <a id="icinga2-api-setup"></a> Setting up the API ## <a id="icinga2-api-setup"></a> Setting up the API
You can run the CLI command `icinga2 api setup` to set up certificates You can run the CLI command `icinga2 api setup` to enable the
and a new API user `root` with an auto-generated password in the `api` [feature](8-cli-commands.md#enable-features) and set up
certificates as well as a new API user `root` with an auto-generated password in the
`/etc/icinga2/conf.d/api-users.conf` configuration file: `/etc/icinga2/conf.d/api-users.conf` configuration file:
# icinga2 api setup # icinga2 api setup
@ -1335,8 +1336,8 @@ The output is similar to the manual [configuration validation](8-cli-commands.md
There are a couple of existing clients which can be used with the Icinga 2 API: There are a couple of existing clients which can be used with the Icinga 2 API:
* [curl](http://curl.haxx.se) * [curl](http://curl.haxx.se) or any other HTTP client really
* [console CLI command](9-icinga2-api.md#icinga2-api-clients-cli-console) * [Icinga 2 console (CLI command)](9-icinga2-api.md#icinga2-api-clients-cli-console)
* [Icinga Studio](9-icinga2-api.md#icinga2-api-clients-icinga-studio) * [Icinga Studio](9-icinga2-api.md#icinga2-api-clients-icinga-studio)
* [Icinga Web 2 Director](https://dev.icinga.org/projects/icingaweb2-modules) * [Icinga Web 2 Director](https://dev.icinga.org/projects/icingaweb2-modules)
@ -1365,76 +1366,10 @@ packages.
The Windows installer includes Icinga Studio already. You must additionally The Windows installer includes Icinga Studio already. You must additionally
install the [wxWidgets library](https://github.com/wxWidgets/wxWidgets/releases/download/v3.0.2/wxMSW-3.0.2-Setup.exe). install the [wxWidgets library](https://github.com/wxWidgets/wxWidgets/releases/download/v3.0.2/wxMSW-3.0.2-Setup.exe).
### <a id="icinga2-api-clients-cli-console"></a> Console Command using the API ### <a id="icinga2-api-clients-cli-console"></a> Icinga 2 Console
By default the [console CLI command](8-cli-commands.md#cli-command-console) evaluates expressions in a local interpreter, i.e. independently from your Icinga 2 daemon. Using the `--connect` parameter you can use the Icinga 2 console to evaluate expressions via the API. By default the [console CLI command](8-cli-commands.md#cli-command-console) evaluates expressions in a local interpreter, i.e. independently from your Icinga 2 daemon. Using the `--connect` parameter you can use the Icinga 2 console to evaluate expressions via the API.
> **Note**
> The console does not currently support SSL certificate verification.
Although the password can be specified in the URL process arguments on UNIX platforms are usually visible to other users (e.g. through `ps`). In order to securely specify the user credentials the console supports two environment variables:
Environment variable | Description
---------------------|-------------
ICINGA2_API_USERNAME | The API username.
ICINGA2_API_PASSWORD | The API password.
Here's an example:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.3.11-762-g1d327ac)
<1> =>
Once connected you can inspect variables and execute other expressions by entering them at the prompt:
<1> => var h = get_host("mbmif.int.netways.de")
null
<2> => h.last_check_result
{
active = true
check_source = "mbmif.int.netways.de"
command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
execution_end = 1446653527.174983
execution_start = 1446653523.152673
exit_status = 0.000000
output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
schedule_end = 1446653527.175133
schedule_start = 1446653583.150000
state = 0.000000
type = "CheckResult"
vars_after = {
attempt = 1.000000
reachable = true
state = 0.000000
state_type = 1.000000
}
vars_before = {
attempt = 1.000000
reachable = true
state = 0.000000
state_type = 1.000000
}
}
<3> =>
You can use the `--eval` parameter to evaluate a single expression in batch mode. The output format for batch mode is JSON.
Here's an example that retrieves the command that was used by Icinga to check the `example-host` host:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("example-host").last_check_result.command' | python -m json.tool
[
"/usr/local/sbin/check_ping",
"-H",
"127.0.0.1",
"-c",
"5000,100%",
"-w",
"3000,80%"
]
### <a id="icinga2-api-clients-programmatic-examples"></a> API Clients Programmatic Examples ### <a id="icinga2-api-clients-programmatic-examples"></a> API Clients Programmatic Examples
#### <a id="icinga2-api-clients-programmatic-examples-Python"></a> Example API Client using Python #### <a id="icinga2-api-clients-programmatic-examples-Python"></a> Example API Client using Python