granicus.if.org Git - icinga2/blob - doc/6-cli-commands.md

   1 ## <a id="cli-commands"></a> Icinga 2 CLI Commands
   2
   3 Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion.
   4
   5 These CLI commands will allow you to use certain functionality
   6 provided by and around the Icinga 2 daemon.
   7
   8 Each CLI command provides its own help and usage information, so please
   9 make sure to always run them with the `--help` parameter.
  10
  11 Run `icinga2` without any arguments to get a list of all available global
  12 options.
  13
  14     # icinga2
  15
  16     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
  17
  18     Usage:
  19       icinga2 <command> [<arguments>]
  20
  21     Supported commands:
  22       * daemon (starts Icinga 2)
  23       * feature disable (disables specified feature)
  24       * feature enable (enables specified feature)
  25       * feature list (lists all enabled features)
  26       * node add (add node)
  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)
  62
  63     Global options:
  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
  67                              terminal
  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
  72
  73     Command options:
  74
  75     Report bugs at <https://dev.icinga.org/>
  76     Icinga home page: <https://www.icinga.org/>
  77
  78
  79 ### <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion
  80
  81 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
  82
  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.
  86
  87 RPM and Debian packages install the bash completion files into
  88 `/etc/bash_completion.d/icinga2`.
  89
  90 You will need to install the `bash-completion` package if not already installed.
  91
  92 RHEL/CentOS/Fedora:
  93
  94     # yum install bash-completion
  95
  96 SUSE:
  97
  98     # zypper install bash-completion
  99
 100 Debian/Ubuntu:
 101
 102     # apt-get install bash-completion
 103
 104 ### <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
 105
 106 #### Libraries
 107
 108 Instead of loading libraries using the [`library` config directive](13-language-reference.md#library)
 109 you can also use the `--library` command-line option.
 110
 111 #### Constants
 112
 113 [Global constants](13-language-reference.md#constants) can be set using the `--define` command-line option.
 114
 115 #### <a id="config-include-path"></a> Config Include Path
 116
 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
 119 brackets like this:
 120
 121     include <test.conf>
 122
 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.
 126
 127 Using the `--include` command-line option additional search directories can be
 128 added.
 129
 130
 131
 132 ### <a id="cli-command-daemon"></a> CLI command: Daemon
 133
 134 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
 135 Furthermore it provides the [configuration validation](6-cli-commands.md#config-validation).
 136
 137     # icinga2 daemon --help
 138     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 139
 140     Usage:
 141       icinga2 daemon [<arguments>]
 142
 143     Starts Icinga 2.
 144
 145     Global options:
 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
 149                              terminal
 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
 154
 155     Command options:
 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
 162
 163     Report bugs at <https://dev.icinga.org/>
 164     Icinga home page: <https://www.icinga.org/>
 165
 166 #### Config Files
 167
 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.
 170
 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`).
 174
 175 #### Config Validation
 176
 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](6-cli-commands.md#config-validation) chapter.
 180
 181
 182 ### <a id="cli-command-feature"></a> CLI command: Feature
 183
 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.
 187
 188     # icinga2 feature disable <tab>
 189     checker       --color       --define      --help        --include     --library     --log-level   mainlog       notification  --version
 190
 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
 194
 195 ### <a id="cli-command-node"></a> CLI command: Node
 196
 197 Provides the functionality to install and manage master and client
 198 nodes in a [remote monitoring ](5-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or
 199 [distributed cluster](5-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario.
 200
 201
 202     # icinga2 node --help
 203     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 204
 205     Usage:
 206       icinga2 <command> [<arguments>]
 207
 208     Supported commands:
 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)
 222
 223     Global options:
 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
 227                              terminal
 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
 232
 233     Command options:
 234
 235     Report bugs at <https://dev.icinga.org/>
 236     Icinga home page: <https://www.icinga.org/>
 237
 238
 239 ### <a id="cli-command-object"></a> CLI command: Object
 240
 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](13-language-reference.md#apply).
 244
 245 More information can be found in the [troubleshooting](10-troubleshooting.md#list-configuration-objects) section.
 246
 247     # icinga2 object --help
 248     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 249
 250     Usage:
 251       icinga2 <command> [<arguments>]
 252
 253     Supported commands:
 254       * object list (lists all objects)
 255
 256     Global options:
 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
 260                              terminal
 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
 265
 266     Command options:
 267
 268     Report bugs at <https://dev.icinga.org/>
 269     Icinga home page: <https://www.icinga.org/>
 270
 271
 272
 273 ### <a id="cli-command-pki"></a> CLI command: Pki
 274
 275 Provides the CLI commands to
 276
 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
 283
 284 This functionality is used by the [node setup/wizard](6-cli-commands.md#cli-command-pki) CLI commands too.
 285
 286     # icinga2 pki --help
 287     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 288
 289     Usage:
 290       icinga2 <command> [<arguments>]
 291
 292     Supported commands:
 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)
 299
 300     Global options:
 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
 304                              terminal
 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
 309
 310     Command options:
 311
 312     Report bugs at <https://dev.icinga.org/>
 313     Icinga home page: <https://www.icinga.org/>
 314
 315
 316 ### <a id="cli-command-repository"></a> CLI command: Repository
 317
 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.
 321
 322
 323 > **Note**
 324 >
 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.).
 328 >
 329 > Please check the Icinga 2 development roadmap for updates.
 330
 331
 332     # icinga2 repository --help
 333     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 334
 335     Usage:
 336       icinga2 <command> [<arguments>]
 337
 338     Supported commands:
 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)
 353
 354     Global options:
 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
 358                              terminal
 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
 363
 364     Command options:
 365
 366     Report bugs at <https://dev.icinga.org/>
 367     Icinga home page: <https://www.icinga.org/>
 368
 369
 370
 371 ### <a id="cli-command-variable"></a> CLI command: Variable
 372
 373 Lists all configured variables (constants) in a similar fasion like [object list](6-cli-commands.md#cli-command-object).
 374
 375     # icinga2 variable --help
 376     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 377
 378     Usage:
 379       icinga2 <command> [<arguments>]
 380
 381     Supported commands:
 382       * variable get (gets a variable)
 383       * variable list (lists all variables)
 384
 385     Global options:
 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
 389                              terminal
 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
 394
 395     Command options:
 396
 397     Report bugs at <https://dev.icinga.org/>
 398     Icinga home page: <https://www.icinga.org/>
 399
 400
 401
 402
 403
 404 ## <a id="features"></a> Enabling/Disabling Features
 405
 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](6-cli-commands.md#cli-command-feature), respectively.
 410
 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.
 414
 415 You can view a list of enabled and disabled features:
 416
 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
 420
 421 Using the `icinga2 feature enable` command you can enable features:
 422
 423     # icinga2 feature enable graphite
 424     Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
 425
 426
 427 You can disable features using the `icinga2 feature disable` command:
 428
 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.
 432
 433
 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.
 437
 438
 439
 440 ## <a id="config-validation"></a> Configuration Validation
 441
 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.
 445
 446 The following example creates an apply rule without any `assign` condition.
 447
 448     apply Service "5872-ping4" {
 449       import "generic-service"
 450       check_command = "ping4"
 451       //assign where match("5872-*", host.name)
 452     }
 453
 454 Validate the configuration with the init script option `checkconfig`:
 455
 456     # /etc/init.d/icinga2 checkconfig
 457
 458 > **Note**
 459 >
 460 > Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using
 461 > the CLI command below.
 462
 463 Or manually passing the `-C` argument:
 464
 465     # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C
 466
 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" {
 471                                             ^^^^^^^^^^^^^
 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"
 474
 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.
 478
 479 > **Tip**
 480 >
 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.
 483 >
 484 > `# icinga2 daemon -C`
 485
 486 If you encouter errors during configuration validation, please make sure
 487 to read the [troubleshooting](10-troubleshooting.md#troubleshooting) chapter.
 488
 489 You can also use the [CLI command](6-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](10-troubleshooting.md#list-configuration-objects).
 493
 494 Example filtered by `Service` objects with the name `ping*`:
 495
 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
 507       * name = 'ping4'
 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
 514       * type = 'Service'
 515       * vars
 516         % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
 517         * sla = '24x7'
 518           % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
 519
 520
 521
 522 ## <a id="config-change-reload"></a> Reload on Configuration Changes
 523
 524 Everytime you have changed your configuration you should first tell Icinga 2
 525 to [validate](6-cli-commands.md#config-validation). If there are no validation errors you can
 526 safely reload the Icinga 2 daemon.
 527
 528     # /etc/init.d/icinga2 reload
 529
 530 > **Note**
 531 >
 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.
 535 >
 536 > Details can be found [here](12-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
 537