1 ## <a id="cli-commands"></a> Icinga 2 CLI Commands
3 Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion.
5 These CLI commands will allow you to use certain functionality
6 provided by and around the Icinga 2 daemon.
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.1.1-299-gf695275)
19 icinga2 <command> [<arguments>]
22 * daemon (starts Icinga 2)
23 * feature disable (disables specified feature)
24 * feature enable (enables specified feature)
25 * feature list (lists all enabled features)
27 * node blacklist add (adds a new blacklist filter)
28 * node blacklist list (lists all blacklist filters)
29 * node blacklist remove (removes a blacklist filter)
30 * node list (lists all nodes)
31 * node remove (removes node)
32 * node set (set node attributes)
33 * node setup (set up node)
34 * node update-config (update node config)
35 * node whitelist add (adds a new whitelist filter)
36 * node whitelist list (lists all whitelist filters)
37 * node whitelist remove (removes a whitelist filter)
38 * node wizard (wizard for node setup)
39 * object list (lists all objects)
40 * pki new-ca (sets up a new CA)
41 * pki new-cert (creates a new CSR)
42 * pki request (requests a certificate)
43 * pki save-cert (saves another Icinga 2 instance's certificate)
44 * pki sign-csr (signs a CSR)
45 * pki ticket (generates a ticket)
46 * repository clear-changes (clear uncommitted repository changes)
47 * repository commit (commit repository changes)
48 * repository endpoint add (adds a new Endpoint object)
49 * repository endpoint list (lists all Endpoint objects)
50 * repository endpoint remove (removes a Endpoint object)
51 * repository host add (adds a new Host object)
52 * repository host list (lists all Host objects)
53 * repository host remove (removes a Host object)
54 * repository service add (adds a new Service object)
55 * repository service list (lists all Service objects)
56 * repository service remove (removes a Service object)
57 * repository zone add (adds a new Zone object)
58 * repository zone list (lists all Zone objects)
59 * repository zone remove (removes a Zone object)
60 * variable get (gets a variable)
61 * variable list (lists all variables)
64 -h [ --help ] show this help message
65 -V [ --version ] show version information
66 --color use VT100 color codes even when stdout is not a
68 -D [ --define ] arg define a constant
69 -l [ --library ] arg load a library
70 -I [ --include ] arg add include search directory
71 -x [ --log-level ] arg specify the log level for the console log
75 Report bugs at <https://dev.icinga.org/>
76 Icinga home page: <https://www.icinga.org/>
79 ### <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion
81 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
83 While `--config` will suggest and auto-complete files and directories on disk,
84 `feature enable` will only suggest disabled features. `repository` will know
85 about object specific attributes, and so on. Try it yourself.
87 RPM and Debian packages install the bash completion files into
88 `/etc/bash_completion.d/icinga2`.
90 You will need to install the `bash-completion` package if not already installed.
94 # yum install bash-completion
98 # zypper install bash-completion
102 # apt-get install bash-completion
104 ### <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
108 Instead of loading libraries using the [`library` config directive](10-language-reference.md#library)
109 you can also use the `--library` command-line option.
113 [Global constants](10-language-reference.md#constants) can be set using the `--define` command-line option.
115 #### <a id="config-include-path"></a> Config Include Path
117 When including files you can specify that the include search path should be
118 checked. You can do this by putting your configuration file name in angle
123 This would cause Icinga 2 to search its include path for the configuration file
124 `test.conf`. By default the installation path for the Icinga Template Library
125 is the only search directory.
127 Using the `--include` command-line option additional search directories can be
132 ### <a id="cli-command-daemon"></a> CLI command: Daemon
134 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
135 Furthermore it provides the [configuration validation](5-cli-commands.md#config-validation).
137 # icinga2 daemon --help
138 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
141 icinga2 daemon [<arguments>]
146 -h [ --help ] show this help message
147 -V [ --version ] show version information
148 --color use VT100 color codes even when stdout is not a
150 -D [ --define ] arg define a constant
151 -l [ --library ] arg load a library
152 -I [ --include ] arg add include search directory
153 -x [ --log-level ] arg specify the log level for the console log
156 -c [ --config ] arg parse a configuration file
157 -z [ --no-config ] start without a configuration file
158 -C [ --validate ] exit after validating the configuration
159 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
160 in combination with --daemonize)
161 -d [ --daemonize ] detach from the controlling terminal
163 Report bugs at <https://dev.icinga.org/>
164 Icinga home page: <https://www.icinga.org/>
168 Using the `--config` option you can specify one or more configuration files.
169 Config files are processed in the order they're specified on the command-line.
171 When no configuration file is specified and the `--no-config` is not used
172 Icinga 2 automatically falls back to using the configuration file
173 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
175 #### Config Validation
177 The `--validate` option can be used to check if your configuration files
178 contain errors. If any errors are found the exit status is 1, otherwise 0
179 is returned. More details in the [configuration validation](5-cli-commands.md#config-validation) chapter.
182 ### <a id="cli-command-feature"></a> CLI command: Feature
184 The CLI commands for `enable` and `disable` feature support bash auto-completion
185 and will only suggest features for the corresponding context. Like disabling a
186 feature will only bring up all enabled features.
188 # icinga2 feature disable <tab>
189 checker --color --define --help --include --library --log-level mainlog notification --version
191 # icinga2 feature enable <tab>
192 api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version
193 --color compatlog --define --help ido-mysql --include livestatus perfdata syslog
195 ### <a id="cli-command-node"></a> CLI command: Node
197 Provides the functionality to install and manage master and client
198 nodes in a [remote monitoring ](4-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or
199 [distributed cluster](4-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario.
202 # icinga2 node --help
203 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
206 icinga2 <command> [<arguments>]
209 * node add (add node)
210 * node blacklist add (adds a new blacklist filter)
211 * node blacklist list (lists all blacklist filters)
212 * node blacklist remove (removes a blacklist filter)
213 * node list (lists all nodes)
214 * node remove (removes node)
215 * node set (set node attributes)
216 * node setup (set up node)
217 * node update-config (update node config)
218 * node whitelist add (adds a new whitelist filter)
219 * node whitelist list (lists all whitelist filters)
220 * node whitelist remove (removes a whitelist filter)
221 * node wizard (wizard for node setup)
224 -h [ --help ] show this help message
225 -V [ --version ] show version information
226 --color use VT100 color codes even when stdout is not a
228 -D [ --define ] arg define a constant
229 -l [ --library ] arg load a library
230 -I [ --include ] arg add include search directory
231 -x [ --log-level ] arg specify the log level for the console log
235 Report bugs at <https://dev.icinga.org/>
236 Icinga home page: <https://www.icinga.org/>
239 ### <a id="cli-command-object"></a> CLI command: Object
241 The `object` CLI command can be used to list all configuration objects and their
242 attributes. The command also shows where each of the attributes was modified.
243 That way you can also identify which objects have been created from your [apply rules](10-language-reference.md#apply).
245 More information can be found in the [troubleshooting](8-troubleshooting.md#list-configuration-objects) section.
247 # icinga2 object --help
248 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
251 icinga2 <command> [<arguments>]
254 * object list (lists all objects)
257 -h [ --help ] show this help message
258 -V [ --version ] show version information
259 --color use VT100 color codes even when stdout is not a
261 -D [ --define ] arg define a constant
262 -l [ --library ] arg load a library
263 -I [ --include ] arg add include search directory
264 -x [ --log-level ] arg specify the log level for the console log
268 Report bugs at <https://dev.icinga.org/>
269 Icinga home page: <https://www.icinga.org/>
273 ### <a id="cli-command-pki"></a> CLI command: Pki
275 Provides the CLI commands to
277 * generate a new local CA
278 * generate a new CSR or self-signed certificate
279 * sign a CSR and return a certificate
280 * save a master certificate manually
281 * request a signed certificate from the master
282 * generate a new ticket for the client setup
284 This functionality is used by the [node setup/wizard](5-cli-commands.md#cli-command-pki) CLI commands too.
287 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
290 icinga2 <command> [<arguments>]
293 * pki new-ca (sets up a new CA)
294 * pki new-cert (creates a new CSR)
295 * pki request (requests a certificate)
296 * pki save-cert (saves another Icinga 2 instance's certificate)
297 * pki sign-csr (signs a CSR)
298 * pki ticket (generates a ticket)
301 -h [ --help ] show this help message
302 -V [ --version ] show version information
303 --color use VT100 color codes even when stdout is not a
305 -D [ --define ] arg define a constant
306 -l [ --library ] arg load a library
307 -I [ --include ] arg add include search directory
308 -x [ --log-level ] arg specify the log level for the console log
312 Report bugs at <https://dev.icinga.org/>
313 Icinga home page: <https://www.icinga.org/>
316 ### <a id="cli-command-repository"></a> CLI command: Repository
318 Provides the functionality to manage the Icinga 2 configuration repository in
319 `/etc/icinga2/repository.d`. All changes are logged and must be committed or
320 cleared after review.
325 > The CLI command `repository` only supports basic configuration manipulation (add, remove)
326 > and a limited set of objects required for the [remote client] integration. Future
327 > versions will support more options (set, etc.).
329 > Please check the Icinga 2 development roadmap for updates.
332 # icinga2 repository --help
333 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
336 icinga2 <command> [<arguments>]
339 * repository clear-changes (clear uncommitted repository changes)
340 * repository commit (commit repository changes)
341 * repository endpoint add (adds a new Endpoint object)
342 * repository endpoint list (lists all Endpoint objects)
343 * repository endpoint remove (removes a Endpoint object)
344 * repository host add (adds a new Host object)
345 * repository host list (lists all Host objects)
346 * repository host remove (removes a Host object)
347 * repository service add (adds a new Service object)
348 * repository service list (lists all Service objects)
349 * repository service remove (removes a Service object)
350 * repository zone add (adds a new Zone object)
351 * repository zone list (lists all Zone objects)
352 * repository zone remove (removes a Zone object)
355 -h [ --help ] show this help message
356 -V [ --version ] show version information
357 --color use VT100 color codes even when stdout is not a
359 -D [ --define ] arg define a constant
360 -l [ --library ] arg load a library
361 -I [ --include ] arg add include search directory
362 -x [ --log-level ] arg specify the log level for the console log
366 Report bugs at <https://dev.icinga.org/>
367 Icinga home page: <https://www.icinga.org/>
371 ### <a id="cli-command-variable"></a> CLI command: Variable
373 Lists all configured variables (constants) in a similar fasion like [object list](5-cli-commands.md#cli-command-object).
375 # icinga2 variable --help
376 icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
379 icinga2 <command> [<arguments>]
382 * variable get (gets a variable)
383 * variable list (lists all variables)
386 -h [ --help ] show this help message
387 -V [ --version ] show version information
388 --color use VT100 color codes even when stdout is not a
390 -D [ --define ] arg define a constant
391 -l [ --library ] arg load a library
392 -I [ --include ] arg add include search directory
393 -x [ --log-level ] arg specify the log level for the console log
397 Report bugs at <https://dev.icinga.org/>
398 Icinga home page: <https://www.icinga.org/>
404 ## <a id="features"></a> Enabling/Disabling Features
406 Icinga 2 provides configuration files for some commonly used features. These
407 are installed in the `/etc/icinga2/features-available` directory and can be
408 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
409 [CLI commands](5-cli-commands.md#cli-command-feature), respectively.
411 The `icinga2 feature enable` CLI command creates symlinks in the
412 `/etc/icinga2/features-enabled` directory which is included by default
413 in the example configuration file.
415 You can view a list of enabled and disabled features:
417 # icinga2 feature list
418 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
419 Enabled features: checker mainlog notification
421 Using the `icinga2 feature enable` command you can enable features:
423 # icinga2 feature enable graphite
424 Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
427 You can disable features using the `icinga2 feature disable` command:
429 # icinga2 feature disable ido-mysql livestatus
430 Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
431 Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
434 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
435 restart Icinga 2. You will need to restart Icinga 2 using the init script
436 after enabling or disabling features.
440 ## <a id="config-validation"></a> Configuration Validation
442 Once you've edited the configuration files make sure to tell Icinga 2 to validate
443 the configuration changes. Icinga 2 will log any configuration error including
444 a hint on the file, the line number and the affected configuration line itself.
446 The following example creates an apply rule without any `assign` condition.
448 apply Service "5872-ping4" {
449 import "generic-service"
450 check_command = "ping4"
451 //assign where match("5872-*", host.name)
454 Validate the configuration with the init script option `checkconfig`:
456 # /etc/init.d/icinga2 checkconfig
460 > Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using
461 > the CLI command below.
463 Or manually passing the `-C` argument:
465 # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C
467 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
468 /etc/icinga2/conf.d/tests/5872.conf(5): }
469 /etc/icinga2/conf.d/tests/5872.conf(6):
470 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
472 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
473 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
475 Config error: 'apply' is missing 'assign'
476 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
477 Icinga 2 detected configuration errors.
481 > Icinga 2 will automatically detect the default path for `icinga2.conf`
482 > in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter.
484 > `# icinga2 daemon -C`
486 If you encouter errors during configuration validation, please make sure
487 to read the [troubleshooting](8-troubleshooting.md#troubleshooting) chapter.
489 You can also use the [CLI command](5-cli-commands.md#cli-command-object) `icinga2 object list`
490 after validation passes to analyze object attributes, inheritance or created
491 objects by apply rules.
492 Find more on troubleshooting with `object list` in [this chapter](8-troubleshooting.md#list-configuration-objects).
494 Example filtered by `Service` objects with the name `ping*`:
496 # icinga2 object list --type Service --name *ping*
497 Object 'nbmif.int.netways.de!ping4' of type 'Service':
498 * __name = 'nbmif.int.netways.de!ping4'
499 * check_command = 'ping4'
500 % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25
501 * check_interval = 60
502 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21
503 * host_name = 'nbmif.int.netways.de'
504 % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
505 * max_check_attempts = 3
506 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24
508 % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
509 * retry_interval = 30
510 % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22
511 * templates = [ 'ping4', 'generic-service' ]
512 % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
513 % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1
516 % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
518 % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
522 ## <a id="config-change-reload"></a> Reload on Configuration Changes
524 Everytime you have changed your configuration you should first tell Icinga 2
525 to [validate](5-cli-commands.md#config-validation). If there are no validation errors you can
526 safely reload the Icinga 2 daemon.
528 # /etc/init.d/icinga2 reload
532 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
533 > which will validate the configuration in a separate process and not stop
534 > the other events like check execution, notifications, etc.
536 > Details can be found [here](9-migrating-from-icinga-1x.md#differences-1x-2-real-reload).