From: Jean-Marcel Flach Date: Fri, 25 Sep 2015 08:11:49 +0000 (+0200) Subject: Update docs X-Git-Tag: v2.4.0~280 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=20180930f723b430ad215a31feba11eace817413;p=icinga2 Update docs refs #10210 --- diff --git a/doc/8-cli-commands.md b/doc/8-cli-commands.md index 13f68c127..dc0b261dc 100644 --- a/doc/8-cli-commands.md +++ b/doc/8-cli-commands.md @@ -13,10 +13,10 @@ options. # icinga2 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - + Usage: icinga2 [] - + Supported commands: * console (Icinga console) * daemon (starts Icinga 2) @@ -60,7 +60,7 @@ options. * troubleshoot (collect information for troubleshooting) * variable get (gets a variable) * variable list (lists all variables) - + Global options: -h [ --help ] show this help message -V [ --version ] show version information @@ -71,10 +71,10 @@ options. -l [ --library ] arg load a library -I [ --include ] arg add include search directory -x [ --log-level ] arg specify the log level for the console log - + Command options: - - Report bugs at + + Report bugs at Icinga home page: @@ -408,11 +408,11 @@ cleared after review. Collects basic information like version, paths, log files and crash reports for troubleshooting purposes and prints them to a file or the console. See [troubleshooting](17-troubleshooting.md#troubleshooting-information-required). -Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files. +Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files. -> **Note** +> **Note** > Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on -> each of one of you instances. +> each of one of you instances. > This is only a tool to collect information to help others help you, it will not attempt to fix anything. @@ -565,13 +565,13 @@ Find more on troubleshooting with `object list` in [this chapter](17-troubleshoo Example filtered by `Service` objects with the name `ping*`: # icinga2 object list --type Service --name *ping* - Object 'nbmif.int.netways.de!ping4' of type 'Service': - * __name = 'nbmif.int.netways.de!ping4' + Object 'icinga.org!ping4' of type 'Service': + * __name = 'icinga.org!ping4' * check_command = 'ping4' % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25 * check_interval = 60 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21 - * host_name = 'nbmif.int.netways.de' + * host_name = 'icinga.org' % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 * max_check_attempts = 3 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24 diff --git a/doc/9-icinga2-api.md b/doc/9-icinga2-api.md index 4f6edbdb0..afe883a59 100644 --- a/doc/9-icinga2-api.md +++ b/doc/9-icinga2-api.md @@ -123,7 +123,7 @@ Once the API user is configured make sure to restart Icinga 2: Now pass the basic auth information to curl and send a GET request to the API: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1' + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1' In case you will get an `Unauthorized` error message make sure to check the API user credentials. @@ -160,11 +160,11 @@ for filtering specific objects. Example for all services in NOT-OK state: - https://localhost:5665/v1/services?filter=service.state!=0 + https://icinga.org:5665/v1/services?filter=service.state!=0 Example for matching all hosts by name (**Note**: `"` are url-encoded as `%22`): - https://localhost:5665/v1/hosts?filter=match(%22nbmif*%22,host.name) + https://icinga.org:5665/v1/hosts?filter=match(%22nbmif*%22,host.name) **TODO** @@ -272,20 +272,20 @@ Examples: Reschedule a service check for all services in NOT-OK state: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/actions/reschedule-check?filter=service.state!=0&type=Service' -X POST | python -m json.tool + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/actions/reschedule-check?filter=service.state!=0&type=Service' -X POST | python -m json.tool { "results": [ { "code": 200.0, - "status": "Successfully rescheduled check for nbmif.int.netways.de!http." + "status": "Successfully rescheduled check for icinga.org!http." }, { "code": 200.0, - "status": "Successfully rescheduled check for nbmif.int.netways.de!disk." + "status": "Successfully rescheduled check for icinga.org!disk." }, { "code": 200.0, - "status": "Successfully rescheduled check for nbmif.int.netways.de!disk /." + "status": "Successfully rescheduled check for icinga.org!disk /." } ] } @@ -304,26 +304,30 @@ of available and enabled features. Any filters are ignored. Example for the main url endpoint `/v1/status`: - $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status' | python -m json.tool + $ curl -k -s -u root:icinga 'https://icinga.org:5665/v1/status' | python -m json.tool { "results": [ { - "name": "ApiListener" + "name": "ApiListener", + "perfdata": [ ... ], + "status": [ ... ] }, ... { - "name": "Collection" + "name": "IcingaAplication", + "perfdata": [ ... ], + "status": [ ... ] }, ... ] } -`/v1/status/Collection` is always available as virtual status url endpoint. +`/v1/status` is always available as virtual status url endpoint. It provides all feature status information into a collected overview. Example for the icinga application url endpoint `/v1/status/IcingaApplication`: - $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication' | python -m json.tool + $ curl -k -s -u root:icinga 'https://icinga.org:5665/v1/status/IcingaApplication' | python -m json.tool { "results": [ { @@ -337,7 +341,7 @@ Example for the icinga application url endpoint `/v1/status/IcingaApplication`: "enable_notifications": true, "enable_perfdata": true, "enable_service_checks": true, - "node_name": "mbmif.int.netways.de", + "node_name": "icinga.org", "pid": 59819.0, "program_start": 1443019345.093372, "version": "v2.3.0-573-g380a131" @@ -382,7 +386,7 @@ Output listing and url parameters use the same syntax. Send a `GET` request to `/v1/hosts` to list all host objects and their attributes. - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts' + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts' #### Create New Host Object @@ -403,7 +407,7 @@ If attributes are of the Dictionary type, you can also use the indexer format: Example: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \ + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com' \ -X PUT \ -d '{ "templates": [ "generic-host" ], "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \ | python -m json.tool @@ -422,7 +426,7 @@ template already provides such. If the configuration validation fails, the new object will not be created and the response body contains a detailed error message. The following example omits the required `check_command` attribute. - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \ + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com' \ -X PUT \ -d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \ | python -m json.tool @@ -442,12 +446,12 @@ contains a detailed error message. The following example omits the required `che Send a `GET` request including the host name inside the url: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com' You can select specific attributes by adding them as url parameters using `?attrs=...`. Multiple attributes must be added one by one, e.g. `?attrs=host.address&attrs=host.name`. - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?attrs=host.name&attrs=host.address' | python -m json.tool + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com?attrs=host.name&attrs=host.address' | python -m json.tool { "results": [ { @@ -478,7 +482,7 @@ If attributes are of the Dictionary type, you can also use the indexer format: Example for existing object `google.com`: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \ + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com' \ -X POST \ -d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \ | python -m json.tool @@ -504,7 +508,7 @@ request. Specify the object name inside the url. Example: - $ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?cascade=1' -X DELETE | python -m json.tool + $ curl -u root:icinga -k -s 'https://icinga.org:5665/v1/hosts/google.com?cascade=1' -X DELETE | python -m json.tool { "results": [ { @@ -537,7 +541,7 @@ can be fetched in a separated request. Send a `POST` request to a new config package called `puppet` in this example. This will create a new empty configuration package. - $ curl -k -s -u root:icinga -X POST https://localhost:5665/v1/config/packages/puppet | python -m json.tool + $ curl -k -s -u root:icinga -X POST https://icinga.org:5665/v1/config/packages/puppet | python -m json.tool { "results": [ { @@ -562,7 +566,7 @@ generates a unique name for the `package` attribute you'll need for later reques Note: This example contains an error (`chec_command`), do not blindly copy paste it. - $ curl -k -s -u root:icinga -X POST -d '{ "files": { "conf.d/test.conf": "object Host \"cfg-mgmt\" { chec_command = \"dummy\" }" } }' https://localhost:5665/v1/config/stages/puppet | python -m json.tool + $ curl -k -s -u root:icinga -X POST -d '{ "files": { "conf.d/test.conf": "object Host \"cfg-mgmt\" { chec_command = \"dummy\" }" } }' https://icinga.org:5665/v1/config/stages/puppet | python -m json.tool { "results": [ { @@ -599,7 +603,7 @@ older revisions and their requests. The following example contains one configuration package `puppet`. The latter already has a stage created, but it is not active. - $ curl -k -s -u root:icinga https://localhost:5665/v1/config/packages | python -m json.tool + $ curl -k -s -u root:icinga https://icinga.org:5665/v1/config/packages | python -m json.tool { "results": [ { @@ -617,7 +621,7 @@ The latter already has a stage created, but it is not active. Sent a `GET` request to the url endpoint `/v1/config/stages` including the package (`puppet`) and stage (`nbmif-1441625839-0`) name. - $ curl -k -s -u root:icinga https://localhost:5665/v1/config/stages/puppet/nbmif-1441625839-0 | python -m json.tool + $ curl -k -s -u root:icinga https://icinga.org:5665/v1/config/stages/puppet/nbmif-1441625839-0 | python -m json.tool { "results": [ ... @@ -657,7 +661,7 @@ in a configuration stage and then specifically request their content. The following example fetches the faulty configuration inside `conf.d/test.conf` for further analysis. - $ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/nbmif-1441625839-0/conf.d/test.conf + $ curl -k -s -u root:icinga https://icinga.org:5665/v1/config/files/puppet/nbmif-1441625839-0/conf.d/test.conf object Host "cfg-mgmt" { chec_command = "dummy" } Note: The returned files are plain-text instead of JSON-encoded. @@ -669,7 +673,7 @@ there must have been an error. Fetch the `startup.log` file and check the config validation errors: - $ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/imagine-1441133065-1/startup.log + $ curl -k -s -u root:icinga https://icinga.org:5665/v1/config/files/puppet/imagine-1441133065-1/startup.log ... critical/config: Error: Attribute 'chec_command' does not exist.