tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation 

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
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:
$ 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)
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)
<1> =>
Example using [object accessor functions](19-library-reference.md#object-accessor-functions)
to fetch the host object for the local node and print its `last_check_result` attribute:
Once connected you can inspect variables and execute other expressions by entering them at the prompt:
<1> => NodeName
"icinga2-node1.localdomain"
<2> => get_host(NodeName).last_check_result
<1> => var h = get_host("mbmif.int.netways.de")
null
<2> => h.last_check_result
{
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%" ]
execution_end = 1446716536.250887
execution_start = 1446716532.222686
execution_end = 1446653527.174983
execution_start = 1446653523.152673
exit_status = 0.000000
output = "PING OK - Packet loss = 0%, RTA = 0.08 ms"
performance_data = [ "rta=0.076000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
schedule_end = 1446716536.250992
schedule_start = 1446716592.210000
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 = {
@ -202,11 +213,12 @@ to fetch the host object for the local node and print its `last_check_result` at
}
<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",
"-H",
@ -217,25 +229,6 @@ the local node's last check result:
"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
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
You can run the CLI command `icinga2 api setup` to set up certificates
and a new API user `root` with an auto-generated password in the
You can run the CLI command `icinga2 api setup` to enable 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:
# 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:
* [curl](http://curl.haxx.se)
* [console CLI command](9-icinga2-api.md#icinga2-api-clients-cli-console)
* [curl](http://curl.haxx.se) or any other HTTP client really
* [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 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
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.
> **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-Python"></a> Example API Client using Python