1 # <a id="cli-commands"></a> Icinga 2 CLI Commands
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
15 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
18 icinga2 <command> [<arguments>]
21 * api setup (setup for api)
22 * console (Icinga console)
23 * daemon (starts Icinga 2)
24 * feature disable (disables specified feature)
25 * feature enable (enables specified feature)
26 * feature list (lists all enabled features)
27 * node add (add node) (DEPRECATED)
28 * node blacklist add (adds a new blacklist filter) (DEPRECATED)
29 * node blacklist list (lists all blacklist filters) (DEPRECATED)
30 * node blacklist remove (removes a blacklist filter) (DEPRECATED)
31 * node list (lists all nodes) (DEPRECATED)
32 * node remove (removes node) (DEPRECATED)
33 * node set (set node attributes) (DEPRECATED)
34 * node setup (set up node)
35 * node update-config (update node config) (DEPRECATED)
36 * node whitelist add (adds a new whitelist filter) (DEPRECATED)
37 * node whitelist list (lists all whitelist filters) (DEPRECATED)
38 * node whitelist remove (removes a whitelist filter) (DEPRECATED)
39 * node wizard (wizard for node setup)
40 * object list (lists all objects)
41 * pki new-ca (sets up a new CA)
42 * pki new-cert (creates a new CSR)
43 * pki request (requests a certificate)
44 * pki save-cert (saves another Icinga 2 instance's certificate)
45 * pki sign-csr (signs a CSR)
46 * pki ticket (generates a ticket)
47 * repository clear-changes (clear uncommitted repository changes) (DEPRECATED)
48 * repository commit (commit repository changes) (DEPRECATED)
49 * repository endpoint add (adds a new Endpoint object) (DEPRECATED)
50 * repository endpoint list (lists all Endpoint objects) (DEPRECATED)
51 * repository endpoint remove (removes a Endpoint object) (DEPRECATED)
52 * repository host add (adds a new Host object) (DEPRECATED)
53 * repository host list (lists all Host objects) (DEPRECATED)
54 * repository host remove (removes a Host object) (DEPRECATED)
55 * repository service add (adds a new Service object) (DEPRECATED)
56 * repository service list (lists all Service objects) (DEPRECATED)
57 * repository service remove (removes a Service object) (DEPRECATED)
58 * repository zone add (adds a new Zone object) (DEPRECATED)
59 * repository zone list (lists all Zone objects) (DEPRECATED)
60 * repository zone remove (removes a Zone object) (DEPRECATED)
61 * troubleshoot (collect information for troubleshooting)
62 * variable get (gets a variable)
63 * variable list (lists all variables)
66 -h [ --help ] show this help message
67 -V [ --version ] show version information
68 --color use VT100 color codes even when stdout is not a
70 -D [ --define ] arg define a constant
71 -a [ --app ] arg application library name (default: icinga)
72 -l [ --library ] arg load a library
73 -I [ --include ] arg add include search directory
74 -x [ --log-level ] arg specify the log level for the console log.
75 The valid value is either debug, notice,
76 information (default), warning, or critical
77 -X [ --script-debugger ] whether to enable the script debugger
79 Report bugs at <https://github.com/Icinga/icinga2>
80 Icinga home page: <https://www.icinga.com/>
83 ## <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion
85 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
87 While `--config` suggests and auto-completes files and directories on disk,
88 `feature enable` only suggests disabled features.
90 RPM and Debian packages install the bash completion files into
91 `/etc/bash_completion.d/icinga2`.
93 You need to install the `bash-completion` package if not already installed.
97 # yum install bash-completion
101 # zypper install bash-completion
105 # apt-get install bash-completion
107 Ensure that the `bash-completion.d` directory is added to your shell
108 environment. You can manually source the icinga2 bash-completion file
109 into your current session and test it:
111 # source /etc/bash-completion.d/icinga2
114 ## <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
118 By default the `icinga2` binary loads the `icinga` library. A different application type
119 can be specified with the `--app` command-line option.
120 Note: This is not needed by the average Icinga user, only developers.
124 Instead of loading libraries using the [`library` config directive](17-language-reference.md#library)
125 you can also use the `--library` command-line option.
126 Note: This is not needed by the average Icinga user, only developers.
130 [Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option.
132 ### <a id="config-include-path"></a> Config Include Path
134 When including files you can specify that the include search path should be
135 checked. You can do this by putting your configuration file name in angle
140 This causes Icinga 2 to search its include path for the configuration file
141 `test.conf`. By default the installation path for the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
142 is the only search directory.
144 Using the `--include` command-line option additional search directories can be
148 ## <a id="cli-command-console"></a> CLI command: Console
150 The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
151 e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
154 Icinga 2 (version: v2.6.0)
155 <1> => function test(name) {
156 <1> .. log("Hello " + name)
160 information/config: Hello World
164 Further usage examples can be found in the [library reference](18-library-reference.md#library-reference) chapter.
166 On operating systems without the `libedit` library installed there is no
167 support for line-editing or a command history. However you can
168 use the `rlwrap` program if you require those features:
170 $ rlwrap icinga2 console
172 The debug console can be used to connect to a running Icinga 2 instance using
173 the [REST API](12-icinga2-api.md#icinga2-api). [API permissions](12-icinga2-api.md#icinga2-api-permissions)
174 are required for executing config expressions and auto-completion.
178 > The debug console does not currently support SSL certificate verification.
180 > Runtime modifications are not validated and might cause the Icinga 2
181 > daemon to crash or behave in an unexpected way. Use these runtime changes
182 > at your own risk and rather *inspect and debug objects read-only*.
184 You can specify the API URL using the `--connect` parameter.
186 Although the password can be specified there process arguments on UNIX platforms are
187 usually visible to other users (e.g. through `ps`). In order to securely specify the
188 user credentials the debug console supports two environment variables:
190 Environment variable | Description
191 ---------------------|-------------
192 ICINGA2_API_USERNAME | The API username.
193 ICINGA2_API_PASSWORD | The API password.
197 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
198 Icinga 2 (version: v2.6.0)
201 Once connected you can inspect variables and execute other expressions by entering them at the prompt:
203 <1> => var h = get_host("example.localdomain")
205 <2> => h.last_check_result
208 check_source = "example.localdomain"
209 command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
210 execution_end = 1446653527.174983
211 execution_start = 1446653523.152673
212 exit_status = 0.000000
213 output = "PING OK - Packet loss = 0%, RTA = 0.11 ms"
214 performance_data = [ "rta=0.114000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
215 schedule_end = 1446653527.175133
216 schedule_start = 1446653583.150000
223 state_type = 1.000000
229 state_type = 1.000000
235 You can use the `--eval` parameter to evaluate a single expression in batch mode.
236 Using the `--file` option you can specify a file which should be evaluated.
237 The output format for batch mode is JSON.
239 The `--syntax-only` option can be used in combination with `--eval` or `--file`
240 to check a script for syntax errors. In this mode the script is parsed to identify
241 syntax errors but not evaluated.
243 Here's an example that retrieves the command that was used by Icinga to check the `example.localdomain` host:
245 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("example.localdomain").last_check_result.command' | python -m json.tool
247 "/usr/local/sbin/check_ping",
256 ## <a id="cli-command-daemon"></a> CLI command: Daemon
258 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
259 Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
261 # icinga2 daemon --help
262 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
265 icinga2 daemon [<arguments>]
270 -h [ --help ] show this help message
271 -V [ --version ] show version information
272 --color use VT100 color codes even when stdout is not a
274 -D [ --define ] arg define a constant
275 -a [ --app ] arg application library name (default: icinga)
276 -l [ --library ] arg load a library
277 -I [ --include ] arg add include search directory
278 -x [ --log-level ] arg specify the log level for the console log.
279 The valid value is either debug, notice,
280 information (default), warning, or critical
281 -X [ --script-debugger ] whether to enable the script debugger
284 -c [ --config ] arg parse a configuration file
285 -z [ --no-config ] start without a configuration file
286 -C [ --validate ] exit after validating the configuration
287 -e [ --errorlog ] arg log fatal errors to the specified log file (only
288 works in combination with --daemonize)
289 -d [ --daemonize ] detach from the controlling terminal
291 Report bugs at <https://github.com/Icinga/icinga2>
292 Icinga home page: <https://www.icinga.com/>
297 You can specify one or more configuration files with the `--config` option.
298 Configuration files are processed in the order they're specified on the command-line.
300 When no configuration file is specified and the `--no-config` is not used
301 Icinga 2 automatically falls back to using the configuration file
302 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
304 ### Config Validation
306 The `--validate` option can be used to check if configuration files
307 contain errors. If any errors are found, the exit status is 1, otherwise 0
308 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
310 ## <a id="cli-command-feature"></a> CLI command: Feature
312 The `feature enable` and `feature disable` commands can be used to enable and disable features:
314 # icinga2 feature disable <tab>
315 --app --define --include --log-level --version checker graphite mainlog
316 --color --help --library --script-debugger api command ido-mysql notification
318 # icinga2 feature enable <tab>
319 --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog
320 --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata
322 The `feature list` command shows which features are currently enabled:
324 # icinga2 feature list
325 Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
326 Enabled features: api checker command graphite ido-mysql mainlog notification
329 ## <a id="cli-command-node"></a> CLI command: Node
333 > This CLI command and its sub commands except for `setup` and `wizard`
334 > have been deprecated in v2.6 and will be
335 > removed in future releases.
337 > Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com).
339 Provides the functionality to install and manage master and client
340 nodes in a [distributed monitoring](6-distributed-monitoring.md#distributed-monitoring) scenario.
342 # icinga2 node --help
343 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
346 icinga2 <command> [<arguments>]
349 * node add (add node) (DEPRECATED)
350 * node blacklist add (adds a new blacklist filter) (DEPRECATED)
351 * node blacklist list (lists all blacklist filters) (DEPRECATED)
352 * node blacklist remove (removes a blacklist filter) (DEPRECATED)
353 * node list (lists all nodes) (DEPRECATED)
354 * node remove (removes node) (DEPRECATED)
355 * node set (set node attributes) (DEPRECATED)
356 * node setup (set up node)
357 * node update-config (update node config) (DEPRECATED)
358 * node whitelist add (adds a new whitelist filter) (DEPRECATED)
359 * node whitelist list (lists all whitelist filters) (DEPRECATED)
360 * node whitelist remove (removes a whitelist filter) (DEPRECATED)
361 * node wizard (wizard for node setup)
364 -h [ --help ] show this help message
365 -V [ --version ] show version information
366 --color use VT100 color codes even when stdout is not a
368 -D [ --define ] arg define a constant
369 -a [ --app ] arg application library name (default: icinga)
370 -l [ --library ] arg load a library
371 -I [ --include ] arg add include search directory
372 -x [ --log-level ] arg specify the log level for the console log.
373 The valid value is either debug, notice,
374 information (default), warning, or critical
375 -X [ --script-debugger ] whether to enable the script debugger
377 Report bugs at <https://github.com/Icinga/icinga2>
378 Icinga home page: <https://www.icinga.com/>
382 ## <a id="cli-command-object"></a> CLI command: Object
384 The `object` CLI command can be used to list all configuration objects and their
385 attributes. The command also shows where each of the attributes was modified and as such
386 provides debug information for further configuration problem analysis.
387 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
389 Runtime modifications via the [REST API](12-icinga2-api.md#icinga2-api-config-objects)
390 are not immediately updated. Furthermore there is a known issue with
391 [group assign expressions](17-language-reference.md#group-assign) which are not reflected in the host object output.
392 You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
394 More information can be found in the [troubleshooting](15-troubleshooting.md#list-configuration-objects) section.
396 # icinga2 object --help
397 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
400 icinga2 <command> [<arguments>]
403 * object list (lists all objects)
406 -h [ --help ] show this help message
407 -V [ --version ] show version information
408 --color use VT100 color codes even when stdout is not a
410 -D [ --define ] arg define a constant
411 -a [ --app ] arg application library name (default: icinga)
412 -l [ --library ] arg load a library
413 -I [ --include ] arg add include search directory
414 -x [ --log-level ] arg specify the log level for the console log.
415 The valid value is either debug, notice,
416 information (default), warning, or critical
417 -X [ --script-debugger ] whether to enable the script debugger
419 Report bugs at <https://github.com/Icinga/icinga2>
420 Icinga home page: <https://www.icinga.com/>
422 ## <a id="cli-command-pki"></a> CLI command: Pki
424 Provides the CLI commands to
426 * generate a new certificate authority (CA)
427 * generate a new CSR or self-signed certificate
428 * sign a CSR and return a certificate
429 * save a master certificate manually
430 * request a signed certificate from the master
431 * generate a new ticket for the client setup
433 This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
434 You will need them in the [distributed monitoring chapter](6-distributed-monitoring.md#distributed-monitoring).
437 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
440 icinga2 <command> [<arguments>]
443 * pki new-ca (sets up a new CA)
444 * pki new-cert (creates a new CSR)
445 * pki request (requests a certificate)
446 * pki save-cert (saves another Icinga 2 instance's certificate)
447 * pki sign-csr (signs a CSR)
448 * pki ticket (generates a ticket)
451 -h [ --help ] show this help message
452 -V [ --version ] show version information
453 --color use VT100 color codes even when stdout is not a
455 -D [ --define ] arg define a constant
456 -a [ --app ] arg application library name (default: icinga)
457 -l [ --library ] arg load a library
458 -I [ --include ] arg add include search directory
459 -x [ --log-level ] arg specify the log level for the console log.
460 The valid value is either debug, notice,
461 information (default), warning, or critical
462 -X [ --script-debugger ] whether to enable the script debugger
464 Report bugs at <https://github.com/Icinga/icinga2>
465 Icinga home page: <https://www.icinga.com/>
467 ## <a id="cli-command-repository"></a> CLI command: Repository
471 > This CLI command has been deprecated in v2.6 and will be
472 > removed in future releases.
474 > Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com).
476 This command is experimental and not finished as public CLI command. Parts of its functionality
477 are used in the [node update-config](11-cli-commands.md#cli-command-node) cli command.
479 ## <a id="cli-command-troubleshoot"></a> CLI command: Troubleshoot
481 Collects basic information like version, paths, log files and crash reports for troubleshooting
482 purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
484 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
486 Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
487 each of one of you instances.
488 This is only a tool to collect information to help others help you, it will not attempt to fix anything.
490 # icinga2 troubleshoot --help
491 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
494 icinga2 troubleshoot [<arguments>]
496 Collect logs and other relevant information for troubleshooting purposes.
499 -h [ --help ] show this help message
500 -V [ --version ] show version information
501 --color use VT100 color codes even when stdout is not a
503 -D [ --define ] arg define a constant
504 -a [ --app ] arg application library name (default: icinga)
505 -l [ --library ] arg load a library
506 -I [ --include ] arg add include search directory
507 -x [ --log-level ] arg specify the log level for the console log.
508 The valid value is either debug, notice,
509 information (default), warning, or critical
510 -X [ --script-debugger ] whether to enable the script debugger
513 -c [ --console ] print to console instead of file
514 -o [ --output ] arg path to output file
515 --include-objects Print the whole objectfile (like `object list`)
516 --include-vars Print all Variables (like `variable list`)
518 Report bugs at <https://github.com/Icinga/icinga2>
519 Icinga home page: <https://www.icinga.com/>
521 ## <a id="cli-command-variable"></a> CLI command: Variable
523 Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
525 # icinga2 variable --help
526 icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
529 icinga2 <command> [<arguments>]
532 * variable get (gets a variable)
533 * variable list (lists all variables)
536 -h [ --help ] show this help message
537 -V [ --version ] show version information
538 --color use VT100 color codes even when stdout is not a
540 -D [ --define ] arg define a constant
541 -a [ --app ] arg application library name (default: icinga)
542 -l [ --library ] arg load a library
543 -I [ --include ] arg add include search directory
544 -x [ --log-level ] arg specify the log level for the console log.
545 The valid value is either debug, notice,
546 information (default), warning, or critical
547 -X [ --script-debugger ] whether to enable the script debugger
549 Report bugs at <https://github.com/Icinga/icinga2>
550 Icinga home page: <https://www.icinga.com/>
552 ## <a id="enable-features"></a> Enabling/Disabling Features
554 Icinga 2 provides configuration files for some commonly used features. These
555 are installed in the `/etc/icinga2/features-available` directory and can be
556 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
557 [CLI commands](11-cli-commands.md#cli-command-feature), respectively.
559 The `icinga2 feature enable` CLI command creates symlinks in the
560 `/etc/icinga2/features-enabled` directory which is included by default
561 in the example configuration file.
563 You can view a list of enabled and disabled features:
565 # icinga2 feature list
566 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
567 Enabled features: checker mainlog notification
569 Using the `icinga2 feature enable` command you can enable features:
571 # icinga2 feature enable graphite
572 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
575 You can disable features using the `icinga2 feature disable` command:
577 # icinga2 feature disable ido-mysql livestatus
578 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
579 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
582 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
583 restart Icinga 2. You will need to restart Icinga 2 using the init script
584 after enabling or disabling features.
588 ## <a id="config-validation"></a> Configuration Validation
590 Once you've edited the configuration files make sure to tell Icinga 2 to validate
591 the configuration changes. Icinga 2 will log any configuration error including
592 a hint on the file, the line number and the affected configuration line itself.
594 The following example creates an apply rule without any `assign` condition.
596 apply Service "5872-ping4" {
597 import "generic-service"
598 check_command = "ping4"
599 //assign where match("5872-*", host.name)
602 Validate the configuration with the init script option `checkconfig`:
604 # /etc/init.d/icinga2 checkconfig
608 > Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using
609 > the CLI command below.
611 Or manually passing the `-C` argument:
613 # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C
615 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
616 /etc/icinga2/conf.d/tests/5872.conf(5): }
617 /etc/icinga2/conf.d/tests/5872.conf(6):
618 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
620 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
621 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
623 Config error: 'apply' is missing 'assign'
624 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
625 Icinga 2 detected configuration errors.
629 > Icinga 2 will automatically detect the default path for `icinga2.conf`
630 > in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter.
632 > `# icinga2 daemon -C`
634 If you encounter errors during configuration validation, please make sure
635 to read the [troubleshooting](15-troubleshooting.md#troubleshooting) chapter.
637 You can also use the [CLI command](11-cli-commands.md#cli-command-object) `icinga2 object list`
638 after validation passes to analyze object attributes, inheritance or created
639 objects by apply rules.
640 Find more on troubleshooting with `object list` in [this chapter](15-troubleshooting.md#list-configuration-objects).
642 Example filtered by `Service` objects with the name `ping*`:
644 # icinga2 object list --type Service --name *ping*
645 Object 'icinga.com!ping4' of type 'Service':
646 * __name = 'icinga.com!ping4'
647 * check_command = 'ping4'
648 % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25
649 * check_interval = 60
650 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21
651 * host_name = 'icinga.com'
652 % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
653 * max_check_attempts = 3
654 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24
656 % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
657 * retry_interval = 30
658 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22
659 * templates = [ 'ping4', 'generic-service' ]
660 % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
661 % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1
664 % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
666 % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
670 ## <a id="config-change-reload"></a> Reload on Configuration Changes
672 Every time you have changed your configuration you should first tell Icinga 2
673 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
674 safely reload the Icinga 2 daemon.
676 # systemctl reload icinga2
678 The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
679 which will validate the configuration in a separate process and not stop
680 the other events like check execution, notifications, etc.