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.11.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 debug 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://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 helper functions to enable and setup the
139 [Icinga 2 API](12-icinga2-api.md#icinga2-api-setup).
141 ### CLI command: Api Setup <a id="cli-command-api-setup "></a>
144 # icinga2 api setup --help
145 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
148 icinga2 api setup [<arguments>]
150 Setup for Icinga 2 API.
153 -h [ --help ] show this help message
154 -V [ --version ] show version information
155 --color use VT100 color codes even when stdout is not a
157 -D [ --define ] arg define a constant
158 -I [ --include ] arg add include search directory
159 -x [ --log-level ] arg specify the log level for the console log.
160 The valid value is either debug, notice,
161 information (default), warning, or critical
162 -X [ --script-debugger ] whether to enable the script debugger
165 --cn arg The certificate's common name
167 Report bugs at <https://github.com/Icinga/icinga2>
168 Get support: <https://icinga.com/support/>
169 Documentation: <https://icinga.com/docs/>
170 Icinga home page: <https://icinga.com/>
173 ## CLI command: Ca <a id="cli-command-ca"></a>
175 List and manage incoming certificate signing requests. More details
176 can be found in the [signing methods](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master)
177 chapter. This CLI command is available since v2.8.
181 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
184 icinga2 <command> [<arguments>]
187 * ca list (lists all certificate signing requests)
188 * ca sign (signs an outstanding certificate request)
191 -h [ --help ] show this help message
192 -V [ --version ] show version information
193 --color use VT100 color codes even when stdout is not a
195 -D [ --define ] arg define a constant
196 -a [ --app ] arg application library name (default: icinga)
197 -l [ --library ] arg load a library
198 -I [ --include ] arg add include search directory
199 -x [ --log-level ] arg specify the log level for the console log.
200 The valid value is either debug, notice,
201 information (default), warning, or critical
202 -X [ --script-debugger ] whether to enable the script debugger
204 Report bugs at <https://github.com/Icinga/icinga2>
205 Icinga home page: <https://icinga.com/>
208 ## CLI command: Console <a id="cli-command-console"></a>
210 The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
211 e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
215 Icinga 2 (version: v2.11.0)
216 <1> => function test(name) {
217 <1> .. log("Hello " + name)
221 information/config: Hello World
226 Further usage examples can be found in the [library reference](18-library-reference.md#library-reference) chapter.
229 # icinga2 console --help
230 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
233 icinga2 console [<arguments>]
235 Interprets Icinga script expressions.
238 -h [ --help ] show this help message
239 -V [ --version ] show version information
240 --color use VT100 color codes even when stdout is not a
242 -D [ --define ] arg define a constant
243 -a [ --app ] arg application library name (default: icinga)
244 -l [ --library ] arg load a library
245 -I [ --include ] arg add include search directory
246 -x [ --log-level ] arg specify the log level for the console log.
247 The valid value is either debug, notice,
248 information (default), warning, or critical
249 -X [ --script-debugger ] whether to enable the script debugger
252 -c [ --connect ] arg connect to an Icinga 2 instance
253 -e [ --eval ] arg evaluate expression and terminate
254 -r [ --file ] arg evaluate a file and terminate
255 --syntax-only only validate syntax (requires --eval or --file)
256 --sandbox enable sandbox mode
258 Report bugs at <https://github.com/Icinga/icinga2>
259 Icinga home page: <https://icinga.com/>
263 On operating systems without the `libedit` library installed there is no
264 support for line-editing or a command history. However you can
265 use the `rlwrap` program if you require those features:
268 $ rlwrap icinga2 console
271 The debug console can be used to connect to a running Icinga 2 instance using
272 the [REST API](12-icinga2-api.md#icinga2-api). [API permissions](12-icinga2-api.md#icinga2-api-permissions)
273 are required for executing config expressions and auto-completion.
277 > The debug console does not currently support TLS certificate verification.
279 > Runtime modifications are not validated and might cause the Icinga 2
280 > daemon to crash or behave in an unexpected way. Use these runtime changes
281 > at your own risk and rather *inspect and debug objects read-only*.
283 You can specify the API URL using the `--connect` parameter.
285 Although the password can be specified there process arguments on UNIX platforms are
286 usually visible to other users (e.g. through `ps`). In order to securely specify the
287 user credentials the debug console supports two environment variables:
289 Environment variable | Description
290 ---------------------|-------------
291 ICINGA2_API_USERNAME | The API username.
292 ICINGA2_API_PASSWORD | The API password.
297 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
298 Icinga 2 (version: v2.11.0)
302 Once connected you can inspect variables and execute other expressions by entering them at the prompt:
305 <1> => var h = get_host("icinga2-client1.localdomain")
307 <2> => h.last_check_result
310 check_source = "icinga2-client1.localdomain"
311 command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
312 execution_end = 1446653527.174983
313 execution_start = 1446653523.152673
314 exit_status = 0.000000
315 output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
316 performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
317 schedule_end = 1446653527.175133
318 schedule_start = 1446653583.150000
325 state_type = 1.000000
331 state_type = 1.000000
337 You can use the `--eval` parameter to evaluate a single expression in batch mode.
338 Using the `--file` option you can specify a file which should be evaluated.
339 The output format for batch mode is JSON.
341 The `--syntax-only` option can be used in combination with `--eval` or `--file`
342 to check a script for syntax errors. In this mode the script is parsed to identify
343 syntax errors but not evaluated.
345 Here's an example that retrieves the command that was used by Icinga to check the `icinga2-client1.localdomain` host:
348 $ 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
350 "/usr/local/sbin/check_ping",
360 ## CLI command: Daemon <a id="cli-command-daemon"></a>
362 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
363 Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
366 # icinga2 daemon --help
367 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
370 icinga2 daemon [<arguments>]
375 -h [ --help ] show this help message
376 -V [ --version ] show version information
377 --color use VT100 color codes even when stdout is not a
379 -D [ --define ] arg define a constant
380 -a [ --app ] arg application library name (default: icinga)
381 -l [ --library ] arg load a library
382 -I [ --include ] arg add include search directory
383 -x [ --log-level ] arg specify the log level for the console log.
384 The valid value is either debug, notice,
385 information (default), warning, or critical
386 -X [ --script-debugger ] whether to enable the script debugger
389 -c [ --config ] arg parse a configuration file
390 -z [ --no-config ] start without a configuration file
391 -C [ --validate ] exit after validating the configuration
392 -e [ --errorlog ] arg log fatal errors to the specified log file (only
393 works in combination with --daemonize or
395 -d [ --daemonize ] detach from the controlling terminal
396 --close-stdio do not log to stdout (or stderr) after startup
398 Report bugs at <https://github.com/Icinga/icinga2>
399 Icinga home page: <https://icinga.com/>
402 ### Config Files <a id="cli-command-daemon-config-files"></a>
404 You can specify one or more configuration files with the `--config` option.
405 Configuration files are processed in the order they're specified on the command-line.
407 When no configuration file is specified and the `--no-config` is not used
408 Icinga 2 automatically falls back to using the configuration file
409 `ConfigDir + "/icinga2.conf"` (where ConfigDir is usually `/etc/icinga2`).
411 ### Validation <a id="cli-command-daemon-validation"></a>
413 The `--validate` option can be used to check if configuration files
414 contain errors. If any errors are found, the exit status is 1, otherwise 0
415 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
417 ## CLI command: Feature <a id="cli-command-feature"></a>
419 The `feature enable` and `feature disable` commands can be used to enable and disable features:
422 # icinga2 feature disable <tab>
423 --app --define --include --log-level --version checker graphite mainlog
424 --color --help --library --script-debugger api command ido-mysql notification
428 # icinga2 feature enable <tab>
429 --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog
430 --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata
433 The `feature list` command shows which features are currently enabled:
436 # icinga2 feature list
437 Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
438 Enabled features: api checker command graphite ido-mysql mainlog notification
441 ## CLI command: Node <a id="cli-command-node"></a>
443 Provides the functionality to setup master and client
444 nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) scenario.
447 # icinga2 node --help
448 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
451 icinga2 <command> [<arguments>]
454 * node setup (set up node)
455 * node wizard (wizard for node setup)
458 -h [ --help ] show this help message
459 -V [ --version ] show version information
460 --color use VT100 color codes even when stdout is not a
462 -D [ --define ] arg define a constant
463 -a [ --app ] arg application library name (default: icinga)
464 -l [ --library ] arg load a library
465 -I [ --include ] arg add include search directory
466 -x [ --log-level ] arg specify the log level for the console log.
467 The valid value is either debug, notice,
468 information (default), warning, or critical
469 -X [ --script-debugger ] whether to enable the script debugger
471 Report bugs at <https://github.com/Icinga/icinga2>
472 Icinga home page: <https://icinga.com/>
475 ## CLI command: Object <a id="cli-command-object"></a>
477 The `object` CLI command can be used to list all configuration objects and their
478 attributes. The command also shows where each of the attributes was modified and as such
479 provides debug information for further configuration problem analysis.
480 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
482 Runtime modifications via the [REST API](12-icinga2-api.md#icinga2-api-config-objects)
483 are not immediately updated. Furthermore there is a known issue with
484 [group assign expressions](17-language-reference.md#group-assign) which are not reflected in the host object output.
485 You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
487 More information can be found in the [troubleshooting](15-troubleshooting.md#troubleshooting-list-configuration-objects) section.
490 # icinga2 object --help
491 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
494 icinga2 <command> [<arguments>]
497 * object list (lists all objects)
500 -h [ --help ] show this help message
501 -V [ --version ] show version information
502 --color use VT100 color codes even when stdout is not a
504 -D [ --define ] arg define a constant
505 -a [ --app ] arg application library name (default: icinga)
506 -l [ --library ] arg load a library
507 -I [ --include ] arg add include search directory
508 -x [ --log-level ] arg specify the log level for the console log.
509 The valid value is either debug, notice,
510 information (default), warning, or critical
511 -X [ --script-debugger ] whether to enable the script debugger
513 Report bugs at <https://github.com/Icinga/icinga2>
514 Icinga home page: <https://icinga.com/>
517 ## CLI command: Pki <a id="cli-command-pki"></a>
519 Provides the CLI commands to
521 * generate a new certificate authority (CA)
522 * generate a new CSR or self-signed certificate
523 * sign a CSR and return a certificate
524 * save a master certificate manually
525 * request a signed certificate from the master
526 * generate a new ticket for the client setup
528 This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
529 You will need them in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
533 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
536 icinga2 <command> [<arguments>]
539 * pki new-ca (sets up a new CA)
540 * pki new-cert (creates a new CSR)
541 * pki request (requests a certificate)
542 * pki save-cert (saves another Icinga 2 instance's certificate)
543 * pki sign-csr (signs a CSR)
544 * pki ticket (generates a ticket)
547 -h [ --help ] show this help message
548 -V [ --version ] show version information
549 --color use VT100 color codes even when stdout is not a
551 -D [ --define ] arg define a constant
552 -a [ --app ] arg application library name (default: icinga)
553 -l [ --library ] arg load a library
554 -I [ --include ] arg add include search directory
555 -x [ --log-level ] arg specify the log level for the console log.
556 The valid value is either debug, notice,
557 information (default), warning, or critical
558 -X [ --script-debugger ] whether to enable the script debugger
560 Report bugs at <https://github.com/Icinga/icinga2>
561 Icinga home page: <https://icinga.com/>
564 ## CLI command: Troubleshoot <a id="cli-command-troubleshoot"></a>
566 Collects basic information like version, paths, log files and crash reports for troubleshooting
567 purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
569 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
571 Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
572 each of one of you instances.
573 This is only a tool to collect information to help others help you, it will not attempt to fix anything.
576 # icinga2 troubleshoot --help
577 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
580 icinga2 troubleshoot [<arguments>]
582 Collect logs and other relevant information for troubleshooting purposes.
585 -h [ --help ] show this help message
586 -V [ --version ] show version information
587 --color use VT100 color codes even when stdout is not a
589 -D [ --define ] arg define a constant
590 -a [ --app ] arg application library name (default: icinga)
591 -l [ --library ] arg load a library
592 -I [ --include ] arg add include search directory
593 -x [ --log-level ] arg specify the log level for the console log.
594 The valid value is either debug, notice,
595 information (default), warning, or critical
596 -X [ --script-debugger ] whether to enable the script debugger
599 -c [ --console ] print to console instead of file
600 -o [ --output ] arg path to output file
601 --include-objects Print the whole objectfile (like `object list`)
602 --include-vars Print all Variables (like `variable list`)
604 Report bugs at <https://github.com/Icinga/icinga2>
605 Icinga home page: <https://icinga.com/>
608 ## CLI command: Variable <a id="cli-command-variable"></a>
610 Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
613 # icinga2 variable --help
614 icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
617 icinga2 <command> [<arguments>]
620 * variable get (gets a variable)
621 * variable list (lists all variables)
624 -h [ --help ] show this help message
625 -V [ --version ] show version information
626 --color use VT100 color codes even when stdout is not a
628 -D [ --define ] arg define a constant
629 -a [ --app ] arg application library name (default: icinga)
630 -l [ --library ] arg load a library
631 -I [ --include ] arg add include search directory
632 -x [ --log-level ] arg specify the log level for the console log.
633 The valid value is either debug, notice,
634 information (default), warning, or critical
635 -X [ --script-debugger ] whether to enable the script debugger
637 Report bugs at <https://github.com/Icinga/icinga2>
638 Icinga home page: <https://icinga.com/>
641 ## Enabling/Disabling Features <a id="enable-features"></a>
643 Icinga 2 provides configuration files for some commonly used features. These
644 are installed in the `/etc/icinga2/features-available` directory and can be
645 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
646 [CLI commands](11-cli-commands.md#cli-command-feature), respectively.
648 The `icinga2 feature enable` CLI command creates symlinks in the
649 `/etc/icinga2/features-enabled` directory which is included by default
650 in the example configuration file.
652 You can view a list of enabled and disabled features:
655 # icinga2 feature list
656 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
657 Enabled features: checker mainlog notification
660 Using the `icinga2 feature enable` command you can enable features:
663 # icinga2 feature enable graphite
664 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
667 You can disable features using the `icinga2 feature disable` command:
670 # icinga2 feature disable ido-mysql livestatus
671 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
672 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
675 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
676 restart Icinga 2. You will need to restart Icinga 2 using the init script
677 after enabling or disabling features.
681 ## Configuration Validation <a id="config-validation"></a>
683 Once you've edited the configuration files make sure to tell Icinga 2 to validate
684 the configuration changes. Icinga 2 will log any configuration error including
685 a hint on the file, the line number and the affected configuration line itself.
687 The following example creates an apply rule without any `assign` condition.
690 apply Service "my-ping4" {
691 import "generic-service"
692 check_command = "ping4"
693 //assign where host.address
697 Validate the configuration:
702 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
703 /etc/icinga2/conf.d/tests/my.conf(5): }
704 /etc/icinga2/conf.d/tests/my.conf(6):
705 /etc/icinga2/conf.d/tests/my.conf(7): apply Service "my-ping4" {
707 /etc/icinga2/conf.d/tests/my.conf(8): import "test-generic-service"
708 /etc/icinga2/conf.d/tests/my.conf(9): check_command = "ping4"
710 Config error: 'apply' is missing 'assign'
711 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
712 Icinga 2 detected configuration errors.
715 If you encounter errors during configuration validation, please make sure
716 to read the [troubleshooting](15-troubleshooting.md#troubleshooting) chapter.
718 You can also use the [CLI command](11-cli-commands.md#cli-command-object) `icinga2 object list`
719 after validation passes to analyze object attributes, inheritance or created
720 objects by apply rules.
721 Find more on troubleshooting with `object list` in [this chapter](15-troubleshooting.md#troubleshooting-list-configuration-objects).
724 ## Reload on Configuration Changes <a id="config-change-reload"></a>
726 Every time you have changed your configuration you should first tell Icinga 2
727 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
728 safely reload the Icinga 2 daemon.
731 # systemctl reload icinga2
734 The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
735 which will validate the configuration in a separate process and not stop
736 the other events like check execution, notifications, etc.