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

   1 # <a id="cli-commands"></a> Icinga 2 CLI Commands
   2
   3 Icinga 2 comes with a number of CLI commands which support 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     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
  16
  17     Usage:
  18       icinga2 <command> [<arguments>]
  19
  20     Supported commands:
  21       * console (Icinga console)
  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       * troubleshoot (collect information for troubleshooting)
  61       * variable get (gets a variable)
  62       * variable list (lists all variables)
  63
  64     Global options:
  65       -h [ --help ]          show this help message
  66       -V [ --version ]       show version information
  67       --color                use VT100 color codes even when stdout is not a
  68                              terminal
  69       -D [ --define ] arg    define a constant
  70       -l [ --library ] arg   load a library
  71       -I [ --include ] arg   add include search directory
  72       -x [ --log-level ] arg specify the log level for the console log
  73
  74     Command options:
  75
  76     Report bugs at <https://dev.icinga.org/>
  77     Icinga home page: <https://www.icinga.org/>
  78
  79
  80 ## <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion
  81
  82 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
  83
  84 While `--config` will suggest and auto-complete files and directories on disk,
  85 `feature enable` will only suggest disabled features. `repository` will know
  86 about object specific attributes, and so on. Try it yourself.
  87
  88 RPM and Debian packages install the bash completion files into
  89 `/etc/bash_completion.d/icinga2`.
  90
  91 You will need to install the `bash-completion` package if not already installed.
  92
  93 RHEL/CentOS/Fedora:
  94
  95     # yum install bash-completion
  96
  97 SUSE:
  98
  99     # zypper install bash-completion
 100
 101 Debian/Ubuntu:
 102
 103     # apt-get install bash-completion
 104
 105 ## <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
 106
 107 ### Libraries
 108
 109 Instead of loading libraries using the [`library` config directive](19-language-reference.md#library)
 110 you can also use the `--library` command-line option.
 111
 112 ### Constants
 113
 114 [Global constants](19-language-reference.md#constants) can be set using the `--define` command-line option.
 115
 116 ### <a id="config-include-path"></a> Config Include Path
 117
 118 When including files you can specify that the include search path should be
 119 checked. You can do this by putting your configuration file name in angle
 120 brackets like this:
 121
 122     include <test.conf>
 123
 124 This would cause Icinga 2 to search its include path for the configuration file
 125 `test.conf`. By default the installation path for the Icinga Template Library
 126 is the only search directory.
 127
 128 Using the `--include` command-line option additional search directories can be
 129 added.
 130
 131
 132 ## <a id="cli-command-console"></a> CLI command: Console
 133
 134 The CLI command `console` can be used to evaluate Icinga config expressions, e.g. to test
 135 `assign where` rules.
 136
 137     $ icinga2 console
 138     Icinga (version: v2.2.0-435-gc95d2f1)
 139     <1> => function test(name) {
 140     <1> ..   log("Hello " + name)
 141     <1> .. }
 142     null
 143     <2> => test("World")
 144     information/config: Hello World
 145     null
 146
 147 The `console` command does not support line-editing or a command history. However you can
 148 use the `rlwrap` program if you require those features:
 149
 150     $ rlwrap icinga2 console
 151
 152 ## <a id="cli-command-daemon"></a> CLI command: Daemon
 153
 154 The CLI command `daemon` provides the functionality to start/stop Icinga 2.
 155 Furthermore it provides the [configuration validation](8-cli-commands.md#config-validation).
 156
 157     # icinga2 daemon --help
 158     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 159
 160     Usage:
 161       icinga2 daemon [<arguments>]
 162
 163     Starts Icinga 2.
 164
 165     Global options:
 166       -h [ --help ]          show this help message
 167       -V [ --version ]       show version information
 168       --color                use VT100 color codes even when stdout is not a
 169                              terminal
 170       -D [ --define ] arg    define a constant
 171       -l [ --library ] arg   load a library
 172       -I [ --include ] arg   add include search directory
 173       -x [ --log-level ] arg specify the log level for the console log
 174
 175     Command options:
 176       -c [ --config ] arg   parse a configuration file
 177       -z [ --no-config ]    start without a configuration file
 178       -C [ --validate ]     exit after validating the configuration
 179       -e [ --errorlog ] arg log fatal errors to the specified log file (only works
 180                             in combination with --daemonize)
 181       -d [ --daemonize ]    detach from the controlling terminal
 182
 183     Report bugs at <https://dev.icinga.org/>
 184     Icinga home page: <https://www.icinga.org/>
 185
 186 ### Config Files
 187
 188 Using the `--config` option you can specify one or more configuration files.
 189 Config files are processed in the order they're specified on the command-line.
 190
 191 When no configuration file is specified and the `--no-config` is not used
 192 Icinga 2 automatically falls back to using the configuration file
 193 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
 194
 195 ### Config Validation
 196
 197 The `--validate` option can be used to check if your configuration files
 198 contain errors. If any errors are found the exit status is 1, otherwise 0
 199 is returned. More details in the [configuration validation](8-cli-commands.md#config-validation) chapter.
 200
 201
 202 ## <a id="cli-command-feature"></a> CLI command: Feature
 203
 204 The `feature enable` and `feature disable` commands can be used to enable and disable features:
 205
 206     # icinga2 feature disable <tab>
 207     checker       --color       --define      --help        --include     --library     --log-level   mainlog       notification  --version
 208
 209     # icinga2 feature enable <tab>
 210     api           command       debuglog      graphite      icingastatus  ido-pgsql     --library     --log-level   statusdata    --version
 211     --color       compatlog     --define      --help        ido-mysql     --include     livestatus    perfdata      syslog
 212
 213 The `feature list` command shows which features are currently enabled:
 214
 215     # icinga2 feature list
 216     Disabled features: agent command compatlog debuglog gelf graphite icingastatus notification perfdata statusdata syslog
 217     Enabled features: api checker livestatus mainlog
 218
 219
 220 ## <a id="cli-command-node"></a> CLI command: Node
 221
 222 Provides the functionality to install and manage master and client
 223 nodes in a [remote monitoring ](10-icinga2-client.md#icinga2-client) or
 224 [distributed cluster](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenario.
 225
 226
 227     # icinga2 node --help
 228     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 229
 230     Usage:
 231       icinga2 <command> [<arguments>]
 232
 233     Supported commands:
 234       * node add (add node)
 235       * node blacklist add (adds a new blacklist filter)
 236       * node blacklist list (lists all blacklist filters)
 237       * node blacklist remove (removes a blacklist filter)
 238       * node list (lists all nodes)
 239       * node remove (removes node)
 240       * node set (set node attributes)
 241       * node setup (set up node)
 242       * node update-config (update node config)
 243       * node whitelist add (adds a new whitelist filter)
 244       * node whitelist list (lists all whitelist filters)
 245       * node whitelist remove (removes a whitelist filter)
 246       * node wizard (wizard for node setup)
 247
 248     Global options:
 249       -h [ --help ]          show this help message
 250       -V [ --version ]       show version information
 251       --color                use VT100 color codes even when stdout is not a
 252                              terminal
 253       -D [ --define ] arg    define a constant
 254       -l [ --library ] arg   load a library
 255       -I [ --include ] arg   add include search directory
 256       -x [ --log-level ] arg specify the log level for the console log
 257
 258     Command options:
 259
 260     Report bugs at <https://dev.icinga.org/>
 261     Icinga home page: <https://www.icinga.org/>
 262
 263
 264 ## <a id="cli-command-object"></a> CLI command: Object
 265
 266 The `object` CLI command can be used to list all configuration objects and their
 267 attributes. The command also shows where each of the attributes was modified.
 268 That way you can also identify which objects have been created from your [apply rules](19-language-reference.md#apply).
 269
 270 More information can be found in the [troubleshooting](16-troubleshooting.md#list-configuration-objects) section.
 271
 272     # icinga2 object --help
 273     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 274
 275     Usage:
 276       icinga2 <command> [<arguments>]
 277
 278     Supported commands:
 279       * object list (lists all objects)
 280
 281     Global options:
 282       -h [ --help ]          show this help message
 283       -V [ --version ]       show version information
 284       --color                use VT100 color codes even when stdout is not a
 285                              terminal
 286       -D [ --define ] arg    define a constant
 287       -l [ --library ] arg   load a library
 288       -I [ --include ] arg   add include search directory
 289       -x [ --log-level ] arg specify the log level for the console log
 290
 291     Command options:
 292
 293     Report bugs at <https://dev.icinga.org/>
 294     Icinga home page: <https://www.icinga.org/>
 295
 296
 297
 298 ## <a id="cli-command-pki"></a> CLI command: Pki
 299
 300 Provides the CLI commands to
 301
 302 * generate a new local CA
 303 * generate a new CSR or self-signed certificate
 304 * sign a CSR and return a certificate
 305 * save a master certificate manually
 306 * request a signed certificate from the master
 307 * generate a new ticket for the client setup
 308
 309 This functionality is used by the [node setup/wizard](8-cli-commands.md#cli-command-pki) CLI commands too.
 310
 311     # icinga2 pki --help
 312     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 313
 314     Usage:
 315       icinga2 <command> [<arguments>]
 316
 317     Supported commands:
 318       * pki new-ca (sets up a new CA)
 319       * pki new-cert (creates a new CSR)
 320       * pki request (requests a certificate)
 321       * pki save-cert (saves another Icinga 2 instance's certificate)
 322       * pki sign-csr (signs a CSR)
 323       * pki ticket (generates a ticket)
 324
 325     Global options:
 326       -h [ --help ]          show this help message
 327       -V [ --version ]       show version information
 328       --color                use VT100 color codes even when stdout is not a
 329                              terminal
 330       -D [ --define ] arg    define a constant
 331       -l [ --library ] arg   load a library
 332       -I [ --include ] arg   add include search directory
 333       -x [ --log-level ] arg specify the log level for the console log
 334
 335     Command options:
 336
 337     Report bugs at <https://dev.icinga.org/>
 338     Icinga home page: <https://www.icinga.org/>
 339
 340
 341 ## <a id="cli-command-repository"></a> CLI command: Repository
 342
 343 Provides the functionality to manage the Icinga 2 configuration repository in
 344 `/etc/icinga2/repository.d`. All changes are logged and must be committed or
 345 cleared after review.
 346
 347
 348 > **Note**
 349 >
 350 > The CLI command `repository` only supports basic configuration manipulation (add, remove)
 351 > and a limited set of objects required for the [remote client] integration. Future
 352 > versions will support more options (set, etc.).
 353 >
 354 > Please check the Icinga 2 development roadmap for updates.
 355
 356
 357     # icinga2 repository --help
 358     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 359
 360     Usage:
 361       icinga2 <command> [<arguments>]
 362
 363     Supported commands:
 364       * repository clear-changes (clear uncommitted repository changes)
 365       * repository commit (commit repository changes)
 366       * repository endpoint add (adds a new Endpoint object)
 367       * repository endpoint list (lists all Endpoint objects)
 368       * repository endpoint remove (removes a Endpoint object)
 369       * repository host add (adds a new Host object)
 370       * repository host list (lists all Host objects)
 371       * repository host remove (removes a Host object)
 372       * repository service add (adds a new Service object)
 373       * repository service list (lists all Service objects)
 374       * repository service remove (removes a Service object)
 375       * repository zone add (adds a new Zone object)
 376       * repository zone list (lists all Zone objects)
 377       * repository zone remove (removes a Zone object)
 378
 379     Global options:
 380       -h [ --help ]          show this help message
 381       -V [ --version ]       show version information
 382       --color                use VT100 color codes even when stdout is not a
 383                              terminal
 384       -D [ --define ] arg    define a constant
 385       -l [ --library ] arg   load a library
 386       -I [ --include ] arg   add include search directory
 387       -x [ --log-level ] arg specify the log level for the console log
 388
 389     Command options:
 390
 391     Report bugs at <https://dev.icinga.org/>
 392     Icinga home page: <https://www.icinga.org/>
 393
 394
 395
 396 ## <a id="cli-command-variable"></a> CLI command: Troubleshoot
 397
 398 Collects basic information like version, paths, log files and crash reports for troubleshooting purposes and prints them to a file or the console. See [troubleshooting](16-troubleshooting.md#troubleshooting-information-required).
 399
 400 Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
 401
 402 > **Note**
 403 > Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on
 404 > each of one of you instances.
 405 > This is only a tool to collect information to help others help you, it will not attempt to fix anything.
 406
 407
 408     # icinga2 troubleshoot --help
 409     icinga2 - The Icinga 2 network monitoring daemon (version: v2.2.0-551-g1d0f6ed)
 410
 411     Usage:
 412       icinga2 troubleshoot [<arguments>]
 413
 414     Global options:
 415       -h [ --help ]          show this help message
 416       -V [ --version ]       show version information
 417       --color                use VT100 color codes even when stdout is not aterminal
 418       -D [ --define ] arg    define a constant
 419       -l [ --library ] arg   load a library
 420       -I [ --include ] arg   add include search directory
 421       -x [ --log-level ] arg specify the log level for the console log
 422
 423     Command options:
 424       -c [ --console ]       print to console instead of file
 425       -o [ --output ] arg    path to output file
 426       --include-vars         print variables to separate file
 427       --inluce-objects       print object to separate file
 428
 429     Report bugs at <https://dev.icinga.org/>
 430     Icinga home page: <https://www.icinga.org/>
 431
 432 ## <a id="cli-command-variable"></a> CLI command: Variable
 433
 434 Lists all configured variables (constants) in a similar fasion like [object list](8-cli-commands.md#cli-command-object).
 435
 436     # icinga2 variable --help
 437     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
 438
 439     Usage:
 440       icinga2 <command> [<arguments>]
 441
 442     Supported commands:
 443       * variable get (gets a variable)
 444       * variable list (lists all variables)
 445
 446     Global options:
 447       -h [ --help ]          show this help message
 448       -V [ --version ]       show version information
 449       --color                use VT100 color codes even when stdout is not a
 450                              terminal
 451       -D [ --define ] arg    define a constant
 452       -l [ --library ] arg   load a library
 453       -I [ --include ] arg   add include search directory
 454       -x [ --log-level ] arg specify the log level for the console log
 455
 456     Command options:
 457
 458     Report bugs at <https://dev.icinga.org/>
 459     Icinga home page: <https://www.icinga.org/>
 460
 461
 462 ## <a id="features"></a> Enabling/Disabling Features
 463
 464 Icinga 2 provides configuration files for some commonly used features. These
 465 are installed in the `/etc/icinga2/features-available` directory and can be
 466 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
 467 [CLI commands](8-cli-commands.md#cli-command-feature), respectively.
 468
 469 The `icinga2 feature enable` CLI command creates symlinks in the
 470 `/etc/icinga2/features-enabled` directory which is included by default
 471 in the example configuration file.
 472
 473 You can view a list of enabled and disabled features:
 474
 475     # icinga2 feature list
 476     Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
 477     Enabled features: checker mainlog notification
 478
 479 Using the `icinga2 feature enable` command you can enable features:
 480
 481     # icinga2 feature enable graphite
 482     Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
 483
 484
 485 You can disable features using the `icinga2 feature disable` command:
 486
 487     # icinga2 feature disable ido-mysql livestatus
 488     Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
 489     Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
 490
 491
 492 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
 493 restart Icinga 2. You will need to restart Icinga 2 using the init script
 494 after enabling or disabling features.
 495
 496
 497
 498 ## <a id="config-validation"></a> Configuration Validation
 499
 500 Once you've edited the configuration files make sure to tell Icinga 2 to validate
 501 the configuration changes. Icinga 2 will log any configuration error including
 502 a hint on the file, the line number and the affected configuration line itself.
 503
 504 The following example creates an apply rule without any `assign` condition.
 505
 506     apply Service "5872-ping4" {
 507       import "generic-service"
 508       check_command = "ping4"
 509       //assign where match("5872-*", host.name)
 510     }
 511
 512 Validate the configuration with the init script option `checkconfig`:
 513
 514     # /etc/init.d/icinga2 checkconfig
 515
 516 > **Note**
 517 >
 518 > Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using
 519 > the CLI command below.
 520
 521 Or manually passing the `-C` argument:
 522
 523     # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C
 524
 525     [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
 526     /etc/icinga2/conf.d/tests/5872.conf(5): }
 527     /etc/icinga2/conf.d/tests/5872.conf(6):
 528     /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
 529                                             ^^^^^^^^^^^^^
 530     /etc/icinga2/conf.d/tests/5872.conf(8):   import "test-generic-service"
 531     /etc/icinga2/conf.d/tests/5872.conf(9):   check_command = "ping4"
 532
 533     Config error: 'apply' is missing 'assign'
 534     [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
 535     Icinga 2 detected configuration errors.
 536
 537 > **Tip**
 538 >
 539 > Icinga 2 will automatically detect the default path for `icinga2.conf`
 540 > in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter.
 541 >
 542 > `# icinga2 daemon -C`
 543
 544 If you encouter errors during configuration validation, please make sure
 545 to read the [troubleshooting](16-troubleshooting.md#troubleshooting) chapter.
 546
 547 You can also use the [CLI command](8-cli-commands.md#cli-command-object) `icinga2 object list`
 548 after validation passes to analyze object attributes, inheritance or created
 549 objects by apply rules.
 550 Find more on troubleshooting with `object list` in [this chapter](16-troubleshooting.md#list-configuration-objects).
 551
 552 Example filtered by `Service` objects with the name `ping*`:
 553
 554     # icinga2 object list --type Service --name *ping*
 555     Object 'nbmif.int.netways.de!ping4' of type 'Service':
 556       * __name = 'nbmif.int.netways.de!ping4'
 557       * check_command = 'ping4'
 558         % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25
 559       * check_interval = 60
 560         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21
 561       * host_name = 'nbmif.int.netways.de'
 562         % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
 563       * max_check_attempts = 3
 564         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24
 565       * name = 'ping4'
 566         % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
 567       * retry_interval = 30
 568         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22
 569       * templates = [ 'ping4', 'generic-service' ]
 570         % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
 571         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1
 572       * type = 'Service'
 573       * vars
 574         % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
 575         * sla = '24x7'
 576           % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
 577
 578
 579
 580 ## <a id="config-change-reload"></a> Reload on Configuration Changes
 581
 582 Everytime you have changed your configuration you should first tell Icinga 2
 583 to [validate](8-cli-commands.md#config-validation). If there are no validation errors you can
 584 safely reload the Icinga 2 daemon.
 585
 586     # /etc/init.d/icinga2 reload
 587
 588 > **Note**
 589 >
 590 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
 591 > which will validate the configuration in a separate process and not stop
 592 > the other events like check execution, notifications, etc.
 593 >
 594 > Details can be found [here](18-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
 595