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 helper functions `api setup` and `api user`. The first to enable the REST API, the second to create
139 ApiUser objects with hashed password strings.
140 More details in the [Icinga 2 API](12-icinga2-api.md#icinga2-api-setup) chapter.
144 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
147 icinga2 <command> [<arguments>]
150 * api setup (setup for API)
151 * api user (API user creation helper)
154 -h [ --help ] show this help message
155 -V [ --version ] show version information
156 --color use VT100 color codes even when stdout is not a
158 -D [ --define ] arg define a constant
159 -a [ --app ] arg application library name (default: icinga)
160 -l [ --library ] arg load a library
161 -I [ --include ] arg add include search directory
162 -x [ --log-level ] arg specify the log level for the console log.
163 The valid value is either debug, notice,
164 information (default), warning, or critical
165 -X [ --script-debugger ] whether to enable the script debugger
167 Report bugs at <https://github.com/Icinga/icinga2>
168 Icinga home page: <https://www.icinga.com/>
171 ## CLI command: Ca <a id="cli-command-ca"></a>
173 List and manage incoming certificate signing requests. More details
174 can be found in the [signing methods](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master)
175 chapter. This CLI command is available since v2.8.
179 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
182 icinga2 <command> [<arguments>]
185 * ca list (lists all certificate signing requests)
186 * ca sign (signs an outstanding certificate request)
189 -h [ --help ] show this help message
190 -V [ --version ] show version information
191 --color use VT100 color codes even when stdout is not a
193 -D [ --define ] arg define a constant
194 -a [ --app ] arg application library name (default: icinga)
195 -l [ --library ] arg load a library
196 -I [ --include ] arg add include search directory
197 -x [ --log-level ] arg specify the log level for the console log.
198 The valid value is either debug, notice,
199 information (default), warning, or critical
200 -X [ --script-debugger ] whether to enable the script debugger
202 Report bugs at <https://github.com/Icinga/icinga2>
203 Icinga home page: <https://www.icinga.com/>
206 ## CLI command: Console <a id="cli-command-console"></a>
208 The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
209 e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
213 Icinga 2 (version: v2.8.0)
214 <1> => function test(name) {
215 <1> .. log("Hello " + name)
219 information/config: Hello World
224 Further usage examples can be found in the [library reference](18-library-reference.md#library-reference) chapter.
227 # icinga2 console --help
228 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
231 icinga2 console [<arguments>]
233 Interprets Icinga script expressions.
236 -h [ --help ] show this help message
237 -V [ --version ] show version information
238 --color use VT100 color codes even when stdout is not a
240 -D [ --define ] arg define a constant
241 -a [ --app ] arg application library name (default: icinga)
242 -l [ --library ] arg load a library
243 -I [ --include ] arg add include search directory
244 -x [ --log-level ] arg specify the log level for the console log.
245 The valid value is either debug, notice,
246 information (default), warning, or critical
247 -X [ --script-debugger ] whether to enable the script debugger
250 -c [ --connect ] arg connect to an Icinga 2 instance
251 -e [ --eval ] arg evaluate expression and terminate
252 -r [ --file ] arg evaluate a file and terminate
253 --syntax-only only validate syntax (requires --eval or --file)
254 --sandbox enable sandbox mode
256 Report bugs at <https://github.com/Icinga/icinga2>
257 Icinga home page: <https://www.icinga.com/>
261 On operating systems without the `libedit` library installed there is no
262 support for line-editing or a command history. However you can
263 use the `rlwrap` program if you require those features:
266 $ rlwrap icinga2 console
269 The debug console can be used to connect to a running Icinga 2 instance using
270 the [REST API](12-icinga2-api.md#icinga2-api). [API permissions](12-icinga2-api.md#icinga2-api-permissions)
271 are required for executing config expressions and auto-completion.
275 > The debug console does not currently support SSL certificate verification.
277 > Runtime modifications are not validated and might cause the Icinga 2
278 > daemon to crash or behave in an unexpected way. Use these runtime changes
279 > at your own risk and rather *inspect and debug objects read-only*.
281 You can specify the API URL using the `--connect` parameter.
283 Although the password can be specified there process arguments on UNIX platforms are
284 usually visible to other users (e.g. through `ps`). In order to securely specify the
285 user credentials the debug console supports two environment variables:
287 Environment variable | Description
288 ---------------------|-------------
289 ICINGA2_API_USERNAME | The API username.
290 ICINGA2_API_PASSWORD | The API password.
295 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
296 Icinga 2 (version: v2.8.0)
300 Once connected you can inspect variables and execute other expressions by entering them at the prompt:
303 <1> => var h = get_host("icinga2-client1.localdomain")
305 <2> => h.last_check_result
308 check_source = "icinga2-client1.localdomain"
309 command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
310 execution_end = 1446653527.174983
311 execution_start = 1446653523.152673
312 exit_status = 0.000000
313 output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
314 performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
315 schedule_end = 1446653527.175133
316 schedule_start = 1446653583.150000
323 state_type = 1.000000
329 state_type = 1.000000
335 You can use the `--eval` parameter to evaluate a single expression in batch mode.
336 Using the `--file` option you can specify a file which should be evaluated.
337 The output format for batch mode is JSON.
339 The `--syntax-only` option can be used in combination with `--eval` or `--file`
340 to check a script for syntax errors. In this mode the script is parsed to identify
341 syntax errors but not evaluated.
343 Here's an example that retrieves the command that was used by Icinga to check the `icinga2-client1.localdomain` host:
346 $ 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
348 "/usr/local/sbin/check_ping",
358 ## CLI command: Daemon <a id="cli-command-daemon"></a>
360 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
361 Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
364 # icinga2 daemon --help
365 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
368 icinga2 daemon [<arguments>]
373 -h [ --help ] show this help message
374 -V [ --version ] show version information
375 --color use VT100 color codes even when stdout is not a
377 -D [ --define ] arg define a constant
378 -a [ --app ] arg application library name (default: icinga)
379 -l [ --library ] arg load a library
380 -I [ --include ] arg add include search directory
381 -x [ --log-level ] arg specify the log level for the console log.
382 The valid value is either debug, notice,
383 information (default), warning, or critical
384 -X [ --script-debugger ] whether to enable the script debugger
387 -c [ --config ] arg parse a configuration file
388 -z [ --no-config ] start without a configuration file
389 -C [ --validate ] exit after validating the configuration
390 -e [ --errorlog ] arg log fatal errors to the specified log file (only
391 works in combination with --daemonize or
393 -d [ --daemonize ] detach from the controlling terminal
394 --close-stdio do not log to stdout (or stderr) after startup
396 Report bugs at <https://github.com/Icinga/icinga2>
397 Icinga home page: <https://www.icinga.com/>
400 ### Config Files <a id="cli-command-daemon-config-files"></a>
402 You can specify one or more configuration files with the `--config` option.
403 Configuration files are processed in the order they're specified on the command-line.
405 When no configuration file is specified and the `--no-config` is not used
406 Icinga 2 automatically falls back to using the configuration file
407 `ConfigDir + "/icinga2.conf"` (where ConfigDir is usually `/etc/icinga2`).
409 ### Validation <a id="cli-command-daemon-validation"></a>
411 The `--validate` option can be used to check if configuration files
412 contain errors. If any errors are found, the exit status is 1, otherwise 0
413 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
415 ## CLI command: Feature <a id="cli-command-feature"></a>
417 The `feature enable` and `feature disable` commands can be used to enable and disable features:
420 # icinga2 feature disable <tab>
421 --app --define --include --log-level --version checker graphite mainlog
422 --color --help --library --script-debugger api command ido-mysql notification
426 # icinga2 feature enable <tab>
427 --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog
428 --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata
431 The `feature list` command shows which features are currently enabled:
434 # icinga2 feature list
435 Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
436 Enabled features: api checker command graphite ido-mysql mainlog notification
439 ## CLI command: Node <a id="cli-command-node"></a>
441 Provides the functionality to setup master and client
442 nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) scenario.
445 # icinga2 node --help
446 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
449 icinga2 <command> [<arguments>]
452 * node setup (set up node)
453 * node wizard (wizard for node setup)
456 -h [ --help ] show this help message
457 -V [ --version ] show version information
458 --color use VT100 color codes even when stdout is not a
460 -D [ --define ] arg define a constant
461 -a [ --app ] arg application library name (default: icinga)
462 -l [ --library ] arg load a library
463 -I [ --include ] arg add include search directory
464 -x [ --log-level ] arg specify the log level for the console log.
465 The valid value is either debug, notice,
466 information (default), warning, or critical
467 -X [ --script-debugger ] whether to enable the script debugger
469 Report bugs at <https://github.com/Icinga/icinga2>
470 Icinga home page: <https://www.icinga.com/>
473 ## CLI command: Object <a id="cli-command-object"></a>
475 The `object` CLI command can be used to list all configuration objects and their
476 attributes. The command also shows where each of the attributes was modified and as such
477 provides debug information for further configuration problem analysis.
478 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
480 Runtime modifications via the [REST API](12-icinga2-api.md#icinga2-api-config-objects)
481 are not immediately updated. Furthermore there is a known issue with
482 [group assign expressions](17-language-reference.md#group-assign) which are not reflected in the host object output.
483 You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
485 More information can be found in the [troubleshooting](15-troubleshooting.md#troubleshooting-list-configuration-objects) section.
488 # icinga2 object --help
489 icinga2 - The Icinga 2 network monitoring daemon (version: v2.7.1-196-g23e8a6253; debug)
492 icinga2 <command> [<arguments>]
495 * object list (lists all objects)
498 -h [ --help ] show this help message
499 -V [ --version ] show version information
500 --color use VT100 color codes even when stdout is not a
502 -D [ --define ] arg define a constant
503 -a [ --app ] arg application library name (default: icinga)
504 -l [ --library ] arg load a library
505 -I [ --include ] arg add include search directory
506 -x [ --log-level ] arg specify the log level for the console log.
507 The valid value is either debug, notice,
508 information (default), warning, or critical
509 -X [ --script-debugger ] whether to enable the script debugger
511 Report bugs at <https://github.com/Icinga/icinga2>
512 Icinga home page: <https://www.icinga.com/>
515 ## CLI command: Pki <a id="cli-command-pki"></a>
517 Provides the CLI commands to
519 * generate a new certificate authority (CA)
520 * generate a new CSR or self-signed certificate
521 * sign a CSR and return a certificate
522 * save a master certificate manually
523 * request a signed certificate from the master
524 * generate a new ticket for the client setup
526 This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
527 You will need them in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
531 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
534 icinga2 <command> [<arguments>]
537 * pki new-ca (sets up a new CA)
538 * pki new-cert (creates a new CSR)
539 * pki request (requests a certificate)
540 * pki save-cert (saves another Icinga 2 instance's certificate)
541 * pki sign-csr (signs a CSR)
542 * pki ticket (generates a ticket)
545 -h [ --help ] show this help message
546 -V [ --version ] show version information
547 --color use VT100 color codes even when stdout is not a
549 -D [ --define ] arg define a constant
550 -a [ --app ] arg application library name (default: icinga)
551 -l [ --library ] arg load a library
552 -I [ --include ] arg add include search directory
553 -x [ --log-level ] arg specify the log level for the console log.
554 The valid value is either debug, notice,
555 information (default), warning, or critical
556 -X [ --script-debugger ] whether to enable the script debugger
558 Report bugs at <https://github.com/Icinga/icinga2>
559 Icinga home page: <https://www.icinga.com/>
562 ## CLI command: Troubleshoot <a id="cli-command-troubleshoot"></a>
564 Collects basic information like version, paths, log files and crash reports for troubleshooting
565 purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
567 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
569 Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
570 each of one of you instances.
571 This is only a tool to collect information to help others help you, it will not attempt to fix anything.
574 # icinga2 troubleshoot --help
575 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
578 icinga2 troubleshoot [<arguments>]
580 Collect logs and other relevant information for troubleshooting purposes.
583 -h [ --help ] show this help message
584 -V [ --version ] show version information
585 --color use VT100 color codes even when stdout is not a
587 -D [ --define ] arg define a constant
588 -a [ --app ] arg application library name (default: icinga)
589 -l [ --library ] arg load a library
590 -I [ --include ] arg add include search directory
591 -x [ --log-level ] arg specify the log level for the console log.
592 The valid value is either debug, notice,
593 information (default), warning, or critical
594 -X [ --script-debugger ] whether to enable the script debugger
597 -c [ --console ] print to console instead of file
598 -o [ --output ] arg path to output file
599 --include-objects Print the whole objectfile (like `object list`)
600 --include-vars Print all Variables (like `variable list`)
602 Report bugs at <https://github.com/Icinga/icinga2>
603 Icinga home page: <https://www.icinga.com/>
606 ## CLI command: Variable <a id="cli-command-variable"></a>
608 Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
611 # icinga2 variable --help
612 icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0; debug)
615 icinga2 <command> [<arguments>]
618 * variable get (gets a variable)
619 * variable list (lists all variables)
622 -h [ --help ] show this help message
623 -V [ --version ] show version information
624 --color use VT100 color codes even when stdout is not a
626 -D [ --define ] arg define a constant
627 -a [ --app ] arg application library name (default: icinga)
628 -l [ --library ] arg load a library
629 -I [ --include ] arg add include search directory
630 -x [ --log-level ] arg specify the log level for the console log.
631 The valid value is either debug, notice,
632 information (default), warning, or critical
633 -X [ --script-debugger ] whether to enable the script debugger
635 Report bugs at <https://github.com/Icinga/icinga2>
636 Icinga home page: <https://www.icinga.com/>
639 ## Enabling/Disabling Features <a id="enable-features"></a>
641 Icinga 2 provides configuration files for some commonly used features. These
642 are installed in the `/etc/icinga2/features-available` directory and can be
643 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
644 [CLI commands](11-cli-commands.md#cli-command-feature), respectively.
646 The `icinga2 feature enable` CLI command creates symlinks in the
647 `/etc/icinga2/features-enabled` directory which is included by default
648 in the example configuration file.
650 You can view a list of enabled and disabled features:
653 # icinga2 feature list
654 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
655 Enabled features: checker mainlog notification
658 Using the `icinga2 feature enable` command you can enable features:
661 # icinga2 feature enable graphite
662 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
665 You can disable features using the `icinga2 feature disable` command:
668 # icinga2 feature disable ido-mysql livestatus
669 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
670 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
673 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
674 restart Icinga 2. You will need to restart Icinga 2 using the init script
675 after enabling or disabling features.
679 ## Configuration Validation <a id="config-validation"></a>
681 Once you've edited the configuration files make sure to tell Icinga 2 to validate
682 the configuration changes. Icinga 2 will log any configuration error including
683 a hint on the file, the line number and the affected configuration line itself.
685 The following example creates an apply rule without any `assign` condition.
688 apply Service "my-ping4" {
689 import "generic-service"
690 check_command = "ping4"
691 //assign where host.address
695 Validate the configuration:
700 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
701 /etc/icinga2/conf.d/tests/my.conf(5): }
702 /etc/icinga2/conf.d/tests/my.conf(6):
703 /etc/icinga2/conf.d/tests/my.conf(7): apply Service "my-ping4" {
705 /etc/icinga2/conf.d/tests/my.conf(8): import "test-generic-service"
706 /etc/icinga2/conf.d/tests/my.conf(9): check_command = "ping4"
708 Config error: 'apply' is missing 'assign'
709 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
710 Icinga 2 detected configuration errors.
713 If you encounter errors during configuration validation, please make sure
714 to read the [troubleshooting](15-troubleshooting.md#troubleshooting) chapter.
716 You can also use the [CLI command](11-cli-commands.md#cli-command-object) `icinga2 object list`
717 after validation passes to analyze object attributes, inheritance or created
718 objects by apply rules.
719 Find more on troubleshooting with `object list` in [this chapter](15-troubleshooting.md#troubleshooting-list-configuration-objects).
722 ## Reload on Configuration Changes <a id="config-change-reload"></a>
724 Every time you have changed your configuration you should first tell Icinga 2
725 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
726 safely reload the Icinga 2 daemon.
729 # systemctl reload icinga2
732 The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
733 which will validate the configuration in a separate process and not stop
734 the other events like check execution, notifications, etc.