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 * api user (API user creation helper)
24 * ca list (lists all certificate signing requests)
25 * ca sign (signs an outstanding certificate request)
26 * console (Icinga console)
27 * daemon (starts Icinga 2)
28 * feature disable (disables specified feature)
29 * feature enable (enables specified feature)
30 * feature list (lists all available features)
31 * node setup (set up node)
32 * node wizard (wizard for node setup)
33 * object list (lists all objects)
34 * pki new-ca (sets up a new CA)
35 * pki new-cert (creates a new CSR)
36 * pki request (requests a certificate)
37 * pki save-cert (saves another Icinga 2 instance's certificate)
38 * pki sign-csr (signs a CSR)
39 * pki ticket (generates a ticket)
40 * troubleshoot (collect information for troubleshooting)
41 * variable get (gets a variable)
42 * variable list (lists all variables)
45 -h [ --help ] show this help message
46 -V [ --version ] show version information
47 --color use VT100 color codes even when stdout is not a
49 -D [ --define ] arg define a constant
50 -a [ --app ] arg application library name (default: icinga)
51 -l [ --library ] arg load a library
52 -I [ --include ] arg add include search directory
53 -x [ --log-level ] arg specify the log level for the console log.
54 The valid value is either debug, notice,
55 information (default), warning, or critical
56 -X [ --script-debugger ] whether to enable the script debugger
58 Report bugs at <https://github.com/Icinga/icinga2>
59 Icinga home page: <https://www.icinga.com/>
63 ## Icinga 2 CLI Bash Autocompletion <a id="cli-commands-autocompletion"></a>
65 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
67 While `--config` suggests and auto-completes files and directories on disk,
68 `feature enable` only suggests disabled features.
70 RPM and Debian packages install the bash completion files into
71 `/etc/bash_completion.d/icinga2`.
73 You need to install the `bash-completion` package if not already installed.
78 # yum install bash-completion
84 # zypper install bash-completion
90 # apt-get install bash-completion
93 Ensure that the `bash-completion.d` directory is added to your shell
94 environment. You can manually source the icinga2 bash-completion file
95 into your current session and test it:
98 # source /etc/bash-completion.d/icinga2
102 ## Icinga 2 CLI Global Options <a id="cli-commands-global-options"></a>
106 By default the `icinga2` binary loads the `icinga` library. A different application type
107 can be specified with the `--app` command-line option.
108 Note: This is not needed by the average Icinga user, only developers.
112 Instead of loading libraries using the [`library` config directive](17-language-reference.md#library)
113 you can also use the `--library` command-line option.
114 Note: This is not needed by the average Icinga user, only developers.
118 [Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option.
120 ### Config Include Path <a id="config-include-path"></a>
122 When including files you can specify that the include search path should be
123 checked. You can do this by putting your configuration file name in angle
130 This causes Icinga 2 to search its include path for the configuration file
131 `test.conf`. By default the installation path for the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
132 is the only search directory.
134 Using the `--include` command-line option additional search directories can be
137 ## CLI command: Api <a id="cli-command-api"></a>
139 Provides the helper functions `api setup` and `api user`. The first to enable the REST API, the second to create
140 ApiUser objects with hashed password strings.
141 More details in the [Icinga 2 API](12-icinga2-api.md#icinga2-api-setup) chapter.
145 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
148 icinga2 <command> [<arguments>]
151 * api setup (setup for API)
152 * api user (API user creation helper)
155 -h [ --help ] show this help message
156 -V [ --version ] show version information
157 --color use VT100 color codes even when stdout is not a
159 -D [ --define ] arg define a constant
160 -a [ --app ] arg application library name (default: icinga)
161 -l [ --library ] arg load a library
162 -I [ --include ] arg add include search directory
163 -x [ --log-level ] arg specify the log level for the console log.
164 The valid value is either debug, notice,
165 information (default), warning, or critical
166 -X [ --script-debugger ] whether to enable the script debugger
168 Report bugs at <https://github.com/Icinga/icinga2>
169 Icinga home page: <https://www.icinga.com/>
172 ## CLI command: Ca <a id="cli-command-ca"></a>
174 List and manage incoming certificate signing requests. More details
175 can be found in the [signing methods](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master)
176 chapter. This CLI command is available since v2.8.
180 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
183 icinga2 <command> [<arguments>]
186 * ca list (lists all certificate signing requests)
187 * ca sign (signs an outstanding certificate request)
190 -h [ --help ] show this help message
191 -V [ --version ] show version information
192 --color use VT100 color codes even when stdout is not a
194 -D [ --define ] arg define a constant
195 -a [ --app ] arg application library name (default: icinga)
196 -l [ --library ] arg load a library
197 -I [ --include ] arg add include search directory
198 -x [ --log-level ] arg specify the log level for the console log.
199 The valid value is either debug, notice,
200 information (default), warning, or critical
201 -X [ --script-debugger ] whether to enable the script debugger
203 Report bugs at <https://github.com/Icinga/icinga2>
204 Icinga home page: <https://www.icinga.com/>
207 ## CLI command: Console <a id="cli-command-console"></a>
209 The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
210 e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
214 Icinga 2 (version: v2.8.0)
215 <1> => function test(name) {
216 <1> .. log("Hello " + name)
220 information/config: Hello World
225 Further usage examples can be found in the [library reference](18-library-reference.md#library-reference) chapter.
228 # icinga2 console --help
229 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
232 icinga2 console [<arguments>]
234 Interprets Icinga script expressions.
237 -h [ --help ] show this help message
238 -V [ --version ] show version information
239 --color use VT100 color codes even when stdout is not a
241 -D [ --define ] arg define a constant
242 -a [ --app ] arg application library name (default: icinga)
243 -l [ --library ] arg load a library
244 -I [ --include ] arg add include search directory
245 -x [ --log-level ] arg specify the log level for the console log.
246 The valid value is either debug, notice,
247 information (default), warning, or critical
248 -X [ --script-debugger ] whether to enable the script debugger
251 -c [ --connect ] arg connect to an Icinga 2 instance
252 -e [ --eval ] arg evaluate expression and terminate
253 -r [ --file ] arg evaluate a file and terminate
254 --syntax-only only validate syntax (requires --eval or --file)
255 --sandbox enable sandbox mode
257 Report bugs at <https://github.com/Icinga/icinga2>
258 Icinga home page: <https://www.icinga.com/>
262 On operating systems without the `libedit` library installed there is no
263 support for line-editing or a command history. However you can
264 use the `rlwrap` program if you require those features:
267 $ rlwrap icinga2 console
270 The debug console can be used to connect to a running Icinga 2 instance using
271 the [REST API](12-icinga2-api.md#icinga2-api). [API permissions](12-icinga2-api.md#icinga2-api-permissions)
272 are required for executing config expressions and auto-completion.
276 > The debug console does not currently support SSL certificate verification.
278 > Runtime modifications are not validated and might cause the Icinga 2
279 > daemon to crash or behave in an unexpected way. Use these runtime changes
280 > at your own risk and rather *inspect and debug objects read-only*.
282 You can specify the API URL using the `--connect` parameter.
284 Although the password can be specified there process arguments on UNIX platforms are
285 usually visible to other users (e.g. through `ps`). In order to securely specify the
286 user credentials the debug console supports two environment variables:
288 Environment variable | Description
289 ---------------------|-------------
290 ICINGA2_API_USERNAME | The API username.
291 ICINGA2_API_PASSWORD | The API password.
296 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
297 Icinga 2 (version: v2.8.0)
301 Once connected you can inspect variables and execute other expressions by entering them at the prompt:
304 <1> => var h = get_host("icinga2-client1.localdomain")
306 <2> => h.last_check_result
309 check_source = "icinga2-client1.localdomain"
310 command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
311 execution_end = 1446653527.174983
312 execution_start = 1446653523.152673
313 exit_status = 0.000000
314 output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
315 performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
316 schedule_end = 1446653527.175133
317 schedule_start = 1446653583.150000
324 state_type = 1.000000
330 state_type = 1.000000
336 You can use the `--eval` parameter to evaluate a single expression in batch mode.
337 Using the `--file` option you can specify a file which should be evaluated.
338 The output format for batch mode is JSON.
340 The `--syntax-only` option can be used in combination with `--eval` or `--file`
341 to check a script for syntax errors. In this mode the script is parsed to identify
342 syntax errors but not evaluated.
344 Here's an example that retrieves the command that was used by Icinga to check the `icinga2-client1.localdomain` host:
347 $ 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
349 "/usr/local/sbin/check_ping",
359 ## CLI command: Daemon <a id="cli-command-daemon"></a>
361 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
362 Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
365 # icinga2 daemon --help
366 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
369 icinga2 daemon [<arguments>]
374 -h [ --help ] show this help message
375 -V [ --version ] show version information
376 --color use VT100 color codes even when stdout is not a
378 -D [ --define ] arg define a constant
379 -a [ --app ] arg application library name (default: icinga)
380 -l [ --library ] arg load a library
381 -I [ --include ] arg add include search directory
382 -x [ --log-level ] arg specify the log level for the console log.
383 The valid value is either debug, notice,
384 information (default), warning, or critical
385 -X [ --script-debugger ] whether to enable the script debugger
388 -c [ --config ] arg parse a configuration file
389 -z [ --no-config ] start without a configuration file
390 -C [ --validate ] exit after validating the configuration
391 -e [ --errorlog ] arg log fatal errors to the specified log file (only
392 works in combination with --daemonize)
393 -d [ --daemonize ] detach from the controlling terminal
395 Report bugs at <https://github.com/Icinga/icinga2>
396 Icinga home page: <https://www.icinga.com/>
399 ### Config Files <a id="cli-command-daemon-config-files"></a>
401 You can specify one or more configuration files with the `--config` option.
402 Configuration files are processed in the order they're specified on the command-line.
404 When no configuration file is specified and the `--no-config` is not used
405 Icinga 2 automatically falls back to using the configuration file
406 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
408 ### Validation <a id="cli-command-daemon-validation"></a>
410 The `--validate` option can be used to check if configuration files
411 contain errors. If any errors are found, the exit status is 1, otherwise 0
412 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
414 ## CLI command: Feature <a id="cli-command-feature"></a>
416 The `feature enable` and `feature disable` commands can be used to enable and disable features:
419 # icinga2 feature disable <tab>
420 --app --define --include --log-level --version checker graphite mainlog
421 --color --help --library --script-debugger api command ido-mysql notification
425 # icinga2 feature enable <tab>
426 --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog
427 --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata
430 The `feature list` command shows which features are currently enabled:
433 # icinga2 feature list
434 Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
435 Enabled features: api checker command graphite ido-mysql mainlog notification
438 ## CLI command: Node <a id="cli-command-node"></a>
440 Provides the functionality to setup master and client
441 nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) scenario.
444 # icinga2 node --help
445 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
448 icinga2 <command> [<arguments>]
451 * node setup (set up node)
452 * node wizard (wizard for node setup)
455 -h [ --help ] show this help message
456 -V [ --version ] show version information
457 --color use VT100 color codes even when stdout is not a
459 -D [ --define ] arg define a constant
460 -a [ --app ] arg application library name (default: icinga)
461 -l [ --library ] arg load a library
462 -I [ --include ] arg add include search directory
463 -x [ --log-level ] arg specify the log level for the console log.
464 The valid value is either debug, notice,
465 information (default), warning, or critical
466 -X [ --script-debugger ] whether to enable the script debugger
468 Report bugs at <https://github.com/Icinga/icinga2>
469 Icinga home page: <https://www.icinga.com/>
472 ## CLI command: Object <a id="cli-command-object"></a>
474 The `object` CLI command can be used to list all configuration objects and their
475 attributes. The command also shows where each of the attributes was modified and as such
476 provides debug information for further configuration problem analysis.
477 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
479 Runtime modifications via the [REST API](12-icinga2-api.md#icinga2-api-config-objects)
480 are not immediately updated. Furthermore there is a known issue with
481 [group assign expressions](17-language-reference.md#group-assign) which are not reflected in the host object output.
482 You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
484 More information can be found in the [troubleshooting](15-troubleshooting.md#troubleshooting-list-configuration-objects) section.
487 # icinga2 object --help
488 icinga2 - The Icinga 2 network monitoring daemon (version: v2.7.1-196-g23e8a6253; debug)
491 icinga2 <command> [<arguments>]
494 * object list (lists all objects)
497 -h [ --help ] show this help message
498 -V [ --version ] show version information
499 --color use VT100 color codes even when stdout is not a
501 -D [ --define ] arg define a constant
502 -a [ --app ] arg application library name (default: icinga)
503 -l [ --library ] arg load a library
504 -I [ --include ] arg add include search directory
505 -x [ --log-level ] arg specify the log level for the console log.
506 The valid value is either debug, notice,
507 information (default), warning, or critical
508 -X [ --script-debugger ] whether to enable the script debugger
510 Report bugs at <https://github.com/Icinga/icinga2>
511 Icinga home page: <https://www.icinga.com/>
514 ## CLI command: Pki <a id="cli-command-pki"></a>
516 Provides the CLI commands to
518 * generate a new certificate authority (CA)
519 * generate a new CSR or self-signed certificate
520 * sign a CSR and return a certificate
521 * save a master certificate manually
522 * request a signed certificate from the master
523 * generate a new ticket for the client setup
525 This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
526 You will need them in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
530 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
533 icinga2 <command> [<arguments>]
536 * pki new-ca (sets up a new CA)
537 * pki new-cert (creates a new CSR)
538 * pki request (requests a certificate)
539 * pki save-cert (saves another Icinga 2 instance's certificate)
540 * pki sign-csr (signs a CSR)
541 * pki ticket (generates a ticket)
544 -h [ --help ] show this help message
545 -V [ --version ] show version information
546 --color use VT100 color codes even when stdout is not a
548 -D [ --define ] arg define a constant
549 -a [ --app ] arg application library name (default: icinga)
550 -l [ --library ] arg load a library
551 -I [ --include ] arg add include search directory
552 -x [ --log-level ] arg specify the log level for the console log.
553 The valid value is either debug, notice,
554 information (default), warning, or critical
555 -X [ --script-debugger ] whether to enable the script debugger
557 Report bugs at <https://github.com/Icinga/icinga2>
558 Icinga home page: <https://www.icinga.com/>
561 ## CLI command: Troubleshoot <a id="cli-command-troubleshoot"></a>
563 Collects basic information like version, paths, log files and crash reports for troubleshooting
564 purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
566 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
568 Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
569 each of one of you instances.
570 This is only a tool to collect information to help others help you, it will not attempt to fix anything.
573 # icinga2 troubleshoot --help
574 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
577 icinga2 troubleshoot [<arguments>]
579 Collect logs and other relevant information for troubleshooting purposes.
582 -h [ --help ] show this help message
583 -V [ --version ] show version information
584 --color use VT100 color codes even when stdout is not a
586 -D [ --define ] arg define a constant
587 -a [ --app ] arg application library name (default: icinga)
588 -l [ --library ] arg load a library
589 -I [ --include ] arg add include search directory
590 -x [ --log-level ] arg specify the log level for the console log.
591 The valid value is either debug, notice,
592 information (default), warning, or critical
593 -X [ --script-debugger ] whether to enable the script debugger
596 -c [ --console ] print to console instead of file
597 -o [ --output ] arg path to output file
598 --include-objects Print the whole objectfile (like `object list`)
599 --include-vars Print all Variables (like `variable list`)
601 Report bugs at <https://github.com/Icinga/icinga2>
602 Icinga home page: <https://www.icinga.com/>
605 ## CLI command: Variable <a id="cli-command-variable"></a>
607 Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
610 # icinga2 variable --help
611 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0; debug)
614 icinga2 <command> [<arguments>]
617 * variable get (gets a variable)
618 * variable list (lists all variables)
621 -h [ --help ] show this help message
622 -V [ --version ] show version information
623 --color use VT100 color codes even when stdout is not a
625 -D [ --define ] arg define a constant
626 -a [ --app ] arg application library name (default: icinga)
627 -l [ --library ] arg load a library
628 -I [ --include ] arg add include search directory
629 -x [ --log-level ] arg specify the log level for the console log.
630 The valid value is either debug, notice,
631 information (default), warning, or critical
632 -X [ --script-debugger ] whether to enable the script debugger
634 Report bugs at <https://github.com/Icinga/icinga2>
635 Icinga home page: <https://www.icinga.com/>
638 ## Enabling/Disabling Features <a id="enable-features"></a>
640 Icinga 2 provides configuration files for some commonly used features. These
641 are installed in the `/etc/icinga2/features-available` directory and can be
642 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
643 [CLI commands](11-cli-commands.md#cli-command-feature), respectively.
645 The `icinga2 feature enable` CLI command creates symlinks in the
646 `/etc/icinga2/features-enabled` directory which is included by default
647 in the example configuration file.
649 You can view a list of enabled and disabled features:
652 # icinga2 feature list
653 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
654 Enabled features: checker mainlog notification
657 Using the `icinga2 feature enable` command you can enable features:
660 # icinga2 feature enable graphite
661 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
664 You can disable features using the `icinga2 feature disable` command:
667 # icinga2 feature disable ido-mysql livestatus
668 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
669 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
672 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
673 restart Icinga 2. You will need to restart Icinga 2 using the init script
674 after enabling or disabling features.
678 ## Configuration Validation <a id="config-validation"></a>
680 Once you've edited the configuration files make sure to tell Icinga 2 to validate
681 the configuration changes. Icinga 2 will log any configuration error including
682 a hint on the file, the line number and the affected configuration line itself.
684 The following example creates an apply rule without any `assign` condition.
687 apply Service "my-ping4" {
688 import "generic-service"
689 check_command = "ping4"
690 //assign where host.address
694 Validate the configuration:
699 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
700 /etc/icinga2/conf.d/tests/my.conf(5): }
701 /etc/icinga2/conf.d/tests/my.conf(6):
702 /etc/icinga2/conf.d/tests/my.conf(7): apply Service "my-ping4" {
704 /etc/icinga2/conf.d/tests/my.conf(8): import "test-generic-service"
705 /etc/icinga2/conf.d/tests/my.conf(9): check_command = "ping4"
707 Config error: 'apply' is missing 'assign'
708 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
709 Icinga 2 detected configuration errors.
712 If you encounter errors during configuration validation, please make sure
713 to read the [troubleshooting](15-troubleshooting.md#troubleshooting) chapter.
715 You can also use the [CLI command](11-cli-commands.md#cli-command-object) `icinga2 object list`
716 after validation passes to analyze object attributes, inheritance or created
717 objects by apply rules.
718 Find more on troubleshooting with `object list` in [this chapter](15-troubleshooting.md#troubleshooting-list-configuration-objects).
721 ## Reload on Configuration Changes <a id="config-change-reload"></a>
723 Every time you have changed your configuration you should first tell Icinga 2
724 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
725 safely reload the Icinga 2 daemon.
728 # systemctl reload icinga2
731 The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
732 which will validate the configuration in a separate process and not stop
733 the other events like check execution, notifications, etc.