1 # Icinga 2 CLI Commands <a id="cli-commands"></a>
3 Icinga 2 comes with a number of CLI commands which support bash autocompletion.
5 These CLI commands will allow you to use certain functionality
6 provided by and around Icinga 2.
8 Each CLI command provides its own help and usage information, so please
9 make sure to always run them with the `--help` parameter.
11 Run `icinga2` without any arguments to get a list of all available global
16 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
19 icinga2 <command> [<arguments>]
22 * api setup (setup for api)
23 * ca list (lists all certificate signing requests)
24 * ca sign (signs an outstanding certificate request)
25 * console (Icinga console)
26 * daemon (starts Icinga 2)
27 * feature disable (disables specified feature)
28 * feature enable (enables specified feature)
29 * feature list (lists all available features)
30 * node setup (set up node)
31 * node wizard (wizard for node setup)
32 * object list (lists all objects)
33 * pki new-ca (sets up a new CA)
34 * pki new-cert (creates a new CSR)
35 * pki request (requests a certificate)
36 * pki save-cert (saves another Icinga 2 instance's certificate)
37 * pki sign-csr (signs a CSR)
38 * pki ticket (generates a ticket)
39 * troubleshoot (collect information for troubleshooting)
40 * variable get (gets a variable)
41 * variable list (lists all variables)
44 -h [ --help ] show this help message
45 -V [ --version ] show version information
46 --color use VT100 color codes even when stdout is not a
48 -D [ --define ] arg define a constant
49 -a [ --app ] arg application library name (default: icinga)
50 -l [ --library ] arg load a library
51 -I [ --include ] arg add include search directory
52 -x [ --log-level ] arg specify the log level for the console log.
53 The valid value is either debug, notice,
54 information (default), warning, or critical
55 -X [ --script-debugger ] whether to enable the script debugger
57 Report bugs at <https://github.com/Icinga/icinga2>
58 Icinga home page: <https://www.icinga.com/>
62 ## Icinga 2 CLI Bash Autocompletion <a id="cli-commands-autocompletion"></a>
64 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
66 While `--config` suggests and auto-completes files and directories on disk,
67 `feature enable` only suggests disabled features.
69 RPM and Debian packages install the bash completion files into
70 `/etc/bash_completion.d/icinga2`.
72 You need to install the `bash-completion` package if not already installed.
77 # yum install bash-completion
83 # zypper install bash-completion
89 # apt-get install bash-completion
92 Ensure that the `bash-completion.d` directory is added to your shell
93 environment. You can manually source the icinga2 bash-completion file
94 into your current session and test it:
97 # source /etc/bash-completion.d/icinga2
101 ## Icinga 2 CLI Global Options <a id="cli-commands-global-options"></a>
105 By default the `icinga2` binary loads the `icinga` library. A different application type
106 can be specified with the `--app` command-line option.
107 Note: This is not needed by the average Icinga user, only developers.
111 Instead of loading libraries using the [`library` config directive](17-language-reference.md#library)
112 you can also use the `--library` command-line option.
113 Note: This is not needed by the average Icinga user, only developers.
117 [Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option.
119 ### Config Include Path <a id="config-include-path"></a>
121 When including files you can specify that the include search path should be
122 checked. You can do this by putting your configuration file name in angle
129 This causes Icinga 2 to search its include path for the configuration file
130 `test.conf`. By default the installation path for the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
131 is the only search directory.
133 Using the `--include` command-line option additional search directories can be
136 ## CLI command: Api <a id="cli-command-api"></a>
138 Provides the setup CLI command to enable the REST API. More details
139 in the [Icinga 2 API](#icinga2-api-setup) chapter.
143 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
146 icinga2 <command> [<arguments>]
149 * api setup (setup for api)
152 -h [ --help ] show this help message
153 -V [ --version ] show version information
154 --color use VT100 color codes even when stdout is not a
156 -D [ --define ] arg define a constant
157 -a [ --app ] arg application library name (default: icinga)
158 -l [ --library ] arg load a library
159 -I [ --include ] arg add include search directory
160 -x [ --log-level ] arg specify the log level for the console log.
161 The valid value is either debug, notice,
162 information (default), warning, or critical
163 -X [ --script-debugger ] whether to enable the script debugger
165 Report bugs at <https://github.com/Icinga/icinga2>
166 Icinga home page: <https://www.icinga.com/>
169 ## CLI command: Ca <a id="cli-command-ca"></a>
171 List and manage incoming certificate signing requests. More details
172 can be found in the [signing methods](#distributed-monitoring-setup-sign-certificates-master)
173 chapter. This CLI command is available since v2.8.
177 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
180 icinga2 <command> [<arguments>]
183 * ca list (lists all certificate signing requests)
184 * ca sign (signs an outstanding certificate request)
187 -h [ --help ] show this help message
188 -V [ --version ] show version information
189 --color use VT100 color codes even when stdout is not a
191 -D [ --define ] arg define a constant
192 -a [ --app ] arg application library name (default: icinga)
193 -l [ --library ] arg load a library
194 -I [ --include ] arg add include search directory
195 -x [ --log-level ] arg specify the log level for the console log.
196 The valid value is either debug, notice,
197 information (default), warning, or critical
198 -X [ --script-debugger ] whether to enable the script debugger
200 Report bugs at <https://github.com/Icinga/icinga2>
201 Icinga home page: <https://www.icinga.com/>
204 ## CLI command: Console <a id="cli-command-console"></a>
206 The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
207 e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
211 Icinga 2 (version: v2.8.0)
212 <1> => function test(name) {
213 <1> .. log("Hello " + name)
217 information/config: Hello World
222 Further usage examples can be found in the [library reference](18-library-reference.md#library-reference) chapter.
225 # icinga2 console --help
226 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
229 icinga2 console [<arguments>]
231 Interprets Icinga script expressions.
234 -h [ --help ] show this help message
235 -V [ --version ] show version information
236 --color use VT100 color codes even when stdout is not a
238 -D [ --define ] arg define a constant
239 -a [ --app ] arg application library name (default: icinga)
240 -l [ --library ] arg load a library
241 -I [ --include ] arg add include search directory
242 -x [ --log-level ] arg specify the log level for the console log.
243 The valid value is either debug, notice,
244 information (default), warning, or critical
245 -X [ --script-debugger ] whether to enable the script debugger
248 -c [ --connect ] arg connect to an Icinga 2 instance
249 -e [ --eval ] arg evaluate expression and terminate
250 -r [ --file ] arg evaluate a file and terminate
251 --syntax-only only validate syntax (requires --eval or --file)
252 --sandbox enable sandbox mode
254 Report bugs at <https://github.com/Icinga/icinga2>
255 Icinga home page: <https://www.icinga.com/>
259 On operating systems without the `libedit` library installed there is no
260 support for line-editing or a command history. However you can
261 use the `rlwrap` program if you require those features:
264 $ rlwrap icinga2 console
267 The debug console can be used to connect to a running Icinga 2 instance using
268 the [REST API](12-icinga2-api.md#icinga2-api). [API permissions](12-icinga2-api.md#icinga2-api-permissions)
269 are required for executing config expressions and auto-completion.
273 > The debug console does not currently support SSL certificate verification.
275 > Runtime modifications are not validated and might cause the Icinga 2
276 > daemon to crash or behave in an unexpected way. Use these runtime changes
277 > at your own risk and rather *inspect and debug objects read-only*.
279 You can specify the API URL using the `--connect` parameter.
281 Although the password can be specified there process arguments on UNIX platforms are
282 usually visible to other users (e.g. through `ps`). In order to securely specify the
283 user credentials the debug console supports two environment variables:
285 Environment variable | Description
286 ---------------------|-------------
287 ICINGA2_API_USERNAME | The API username.
288 ICINGA2_API_PASSWORD | The API password.
293 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
294 Icinga 2 (version: v2.8.0)
298 Once connected you can inspect variables and execute other expressions by entering them at the prompt:
301 <1> => var h = get_host("icinga2-client1.localdomain")
303 <2> => h.last_check_result
306 check_source = "icinga2-client1.localdomain"
307 command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
308 execution_end = 1446653527.174983
309 execution_start = 1446653523.152673
310 exit_status = 0.000000
311 output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
312 performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
313 schedule_end = 1446653527.175133
314 schedule_start = 1446653583.150000
321 state_type = 1.000000
327 state_type = 1.000000
333 You can use the `--eval` parameter to evaluate a single expression in batch mode.
334 Using the `--file` option you can specify a file which should be evaluated.
335 The output format for batch mode is JSON.
337 The `--syntax-only` option can be used in combination with `--eval` or `--file`
338 to check a script for syntax errors. In this mode the script is parsed to identify
339 syntax errors but not evaluated.
341 Here's an example that retrieves the command that was used by Icinga to check the `icinga2-client1.localdomain` host:
344 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("icinga2-client1.localdomain").last_check_result.command' | python -m json.tool
346 "/usr/local/sbin/check_ping",
356 ## CLI command: Daemon <a id="cli-command-daemon"></a>
358 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
359 Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
362 # icinga2 daemon --help
363 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
366 icinga2 daemon [<arguments>]
371 -h [ --help ] show this help message
372 -V [ --version ] show version information
373 --color use VT100 color codes even when stdout is not a
375 -D [ --define ] arg define a constant
376 -a [ --app ] arg application library name (default: icinga)
377 -l [ --library ] arg load a library
378 -I [ --include ] arg add include search directory
379 -x [ --log-level ] arg specify the log level for the console log.
380 The valid value is either debug, notice,
381 information (default), warning, or critical
382 -X [ --script-debugger ] whether to enable the script debugger
385 -c [ --config ] arg parse a configuration file
386 -z [ --no-config ] start without a configuration file
387 -C [ --validate ] exit after validating the configuration
388 -e [ --errorlog ] arg log fatal errors to the specified log file (only
389 works in combination with --daemonize)
390 -d [ --daemonize ] detach from the controlling terminal
392 Report bugs at <https://github.com/Icinga/icinga2>
393 Icinga home page: <https://www.icinga.com/>
398 You can specify one or more configuration files with the `--config` option.
399 Configuration files are processed in the order they're specified on the command-line.
401 When no configuration file is specified and the `--no-config` is not used
402 Icinga 2 automatically falls back to using the configuration file
403 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
405 ### Config Validation
407 The `--validate` option can be used to check if configuration files
408 contain errors. If any errors are found, the exit status is 1, otherwise 0
409 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
411 ## CLI command: Feature <a id="cli-command-feature"></a>
413 The `feature enable` and `feature disable` commands can be used to enable and disable features:
416 # icinga2 feature disable <tab>
417 --app --define --include --log-level --version checker graphite mainlog
418 --color --help --library --script-debugger api command ido-mysql notification
422 # icinga2 feature enable <tab>
423 --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog
424 --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata
427 The `feature list` command shows which features are currently enabled:
430 # icinga2 feature list
431 Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
432 Enabled features: api checker command graphite ido-mysql mainlog notification
435 ## CLI command: Node <a id="cli-command-node"></a>
437 Provides the functionality to setup master and client
438 nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) scenario.
441 # icinga2 node --help
442 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
445 icinga2 <command> [<arguments>]
448 * node setup (set up node)
449 * node wizard (wizard for node setup)
452 -h [ --help ] show this help message
453 -V [ --version ] show version information
454 --color use VT100 color codes even when stdout is not a
456 -D [ --define ] arg define a constant
457 -a [ --app ] arg application library name (default: icinga)
458 -l [ --library ] arg load a library
459 -I [ --include ] arg add include search directory
460 -x [ --log-level ] arg specify the log level for the console log.
461 The valid value is either debug, notice,
462 information (default), warning, or critical
463 -X [ --script-debugger ] whether to enable the script debugger
465 Report bugs at <https://github.com/Icinga/icinga2>
466 Icinga home page: <https://www.icinga.com/>
469 ## CLI command: Object <a id="cli-command-object"></a>
471 The `object` CLI command can be used to list all configuration objects and their
472 attributes. The command also shows where each of the attributes was modified and as such
473 provides debug information for further configuration problem analysis.
474 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
476 Runtime modifications via the [REST API](12-icinga2-api.md#icinga2-api-config-objects)
477 are not immediately updated. Furthermore there is a known issue with
478 [group assign expressions](17-language-reference.md#group-assign) which are not reflected in the host object output.
479 You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
481 More information can be found in the [troubleshooting](15-troubleshooting.md#troubleshooting-list-configuration-objects) section.
484 # icinga2 object --help
485 icinga2 - The Icinga 2 network monitoring daemon (version: v2.7.1-196-g23e8a6253; debug)
488 icinga2 <command> [<arguments>]
491 * object list (lists all objects)
494 -h [ --help ] show this help message
495 -V [ --version ] show version information
496 --color use VT100 color codes even when stdout is not a
498 -D [ --define ] arg define a constant
499 -a [ --app ] arg application library name (default: icinga)
500 -l [ --library ] arg load a library
501 -I [ --include ] arg add include search directory
502 -x [ --log-level ] arg specify the log level for the console log.
503 The valid value is either debug, notice,
504 information (default), warning, or critical
505 -X [ --script-debugger ] whether to enable the script debugger
507 Report bugs at <https://github.com/Icinga/icinga2>
508 Icinga home page: <https://www.icinga.com/>
511 ## CLI command: Pki <a id="cli-command-pki"></a>
513 Provides the CLI commands to
515 * generate a new certificate authority (CA)
516 * generate a new CSR or self-signed certificate
517 * sign a CSR and return a certificate
518 * save a master certificate manually
519 * request a signed certificate from the master
520 * generate a new ticket for the client setup
522 This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
523 You will need them in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
527 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
530 icinga2 <command> [<arguments>]
533 * pki new-ca (sets up a new CA)
534 * pki new-cert (creates a new CSR)
535 * pki request (requests a certificate)
536 * pki save-cert (saves another Icinga 2 instance's certificate)
537 * pki sign-csr (signs a CSR)
538 * pki ticket (generates a ticket)
541 -h [ --help ] show this help message
542 -V [ --version ] show version information
543 --color use VT100 color codes even when stdout is not a
545 -D [ --define ] arg define a constant
546 -a [ --app ] arg application library name (default: icinga)
547 -l [ --library ] arg load a library
548 -I [ --include ] arg add include search directory
549 -x [ --log-level ] arg specify the log level for the console log.
550 The valid value is either debug, notice,
551 information (default), warning, or critical
552 -X [ --script-debugger ] whether to enable the script debugger
554 Report bugs at <https://github.com/Icinga/icinga2>
555 Icinga home page: <https://www.icinga.com/>
558 ## CLI command: Troubleshoot <a id="cli-command-troubleshoot"></a>
560 Collects basic information like version, paths, log files and crash reports for troubleshooting
561 purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
563 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
565 Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
566 each of one of you instances.
567 This is only a tool to collect information to help others help you, it will not attempt to fix anything.
570 # icinga2 troubleshoot --help
571 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
574 icinga2 troubleshoot [<arguments>]
576 Collect logs and other relevant information for troubleshooting purposes.
579 -h [ --help ] show this help message
580 -V [ --version ] show version information
581 --color use VT100 color codes even when stdout is not a
583 -D [ --define ] arg define a constant
584 -a [ --app ] arg application library name (default: icinga)
585 -l [ --library ] arg load a library
586 -I [ --include ] arg add include search directory
587 -x [ --log-level ] arg specify the log level for the console log.
588 The valid value is either debug, notice,
589 information (default), warning, or critical
590 -X [ --script-debugger ] whether to enable the script debugger
593 -c [ --console ] print to console instead of file
594 -o [ --output ] arg path to output file
595 --include-objects Print the whole objectfile (like `object list`)
596 --include-vars Print all Variables (like `variable list`)
598 Report bugs at <https://github.com/Icinga/icinga2>
599 Icinga home page: <https://www.icinga.com/>
602 ## CLI command: Variable <a id="cli-command-variable"></a>
604 Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
607 # icinga2 variable --help
608 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0; debug)
611 icinga2 <command> [<arguments>]
614 * variable get (gets a variable)
615 * variable list (lists all variables)
618 -h [ --help ] show this help message
619 -V [ --version ] show version information
620 --color use VT100 color codes even when stdout is not a
622 -D [ --define ] arg define a constant
623 -a [ --app ] arg application library name (default: icinga)
624 -l [ --library ] arg load a library
625 -I [ --include ] arg add include search directory
626 -x [ --log-level ] arg specify the log level for the console log.
627 The valid value is either debug, notice,
628 information (default), warning, or critical
629 -X [ --script-debugger ] whether to enable the script debugger
631 Report bugs at <https://github.com/Icinga/icinga2>
632 Icinga home page: <https://www.icinga.com/>
635 ## Enabling/Disabling Features <a id="enable-features"></a>
637 Icinga 2 provides configuration files for some commonly used features. These
638 are installed in the `/etc/icinga2/features-available` directory and can be
639 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
640 [CLI commands](11-cli-commands.md#cli-command-feature), respectively.
642 The `icinga2 feature enable` CLI command creates symlinks in the
643 `/etc/icinga2/features-enabled` directory which is included by default
644 in the example configuration file.
646 You can view a list of enabled and disabled features:
649 # icinga2 feature list
650 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
651 Enabled features: checker mainlog notification
654 Using the `icinga2 feature enable` command you can enable features:
657 # icinga2 feature enable graphite
658 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
661 You can disable features using the `icinga2 feature disable` command:
664 # icinga2 feature disable ido-mysql livestatus
665 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
666 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
669 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
670 restart Icinga 2. You will need to restart Icinga 2 using the init script
671 after enabling or disabling features.
675 ## Configuration Validation <a id="config-validation"></a>
677 Once you've edited the configuration files make sure to tell Icinga 2 to validate
678 the configuration changes. Icinga 2 will log any configuration error including
679 a hint on the file, the line number and the affected configuration line itself.
681 The following example creates an apply rule without any `assign` condition.
684 apply Service "my-ping4" {
685 import "generic-service"
686 check_command = "ping4"
687 //assign where host.address
691 Validate the configuration:
696 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
697 /etc/icinga2/conf.d/tests/my.conf(5): }
698 /etc/icinga2/conf.d/tests/my.conf(6):
699 /etc/icinga2/conf.d/tests/my.conf(7): apply Service "my-ping4" {
701 /etc/icinga2/conf.d/tests/my.conf(8): import "test-generic-service"
702 /etc/icinga2/conf.d/tests/my.conf(9): check_command = "ping4"
704 Config error: 'apply' is missing 'assign'
705 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
706 Icinga 2 detected configuration errors.
709 If you encounter errors during configuration validation, please make sure
710 to read the [troubleshooting](15-troubleshooting.md#troubleshooting) chapter.
712 You can also use the [CLI command](11-cli-commands.md#cli-command-object) `icinga2 object list`
713 after validation passes to analyze object attributes, inheritance or created
714 objects by apply rules.
715 Find more on troubleshooting with `object list` in [this chapter](15-troubleshooting.md#troubleshooting-list-configuration-objects).
718 ## Reload on Configuration Changes <a id="config-change-reload"></a>
720 Every time you have changed your configuration you should first tell Icinga 2
721 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
722 safely reload the Icinga 2 daemon.
725 # systemctl reload icinga2
728 The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
729 which will validate the configuration in a separate process and not stop
730 the other events like check execution, notifications, etc.