diff options
Diffstat (limited to 'doc/60-CLI.md')
| -rw-r--r-- | doc/60-CLI.md | 719 |
1 files changed, 719 insertions, 0 deletions
diff --git a/doc/60-CLI.md b/doc/60-CLI.md new file mode 100644 index 0000000..5d35244 --- /dev/null +++ b/doc/60-CLI.md @@ -0,0 +1,719 @@ +<a id="CLI"></a>Director CLI +============================ + +Large parts of the Director's functionality are also available on your CLI. + + +Manage Objects +-------------- + +Use `icingacli director <type> <action>` show, create modify or delete +Icinga objects of a specific type: + +| Action | Description | +|--------------|---------------------------------------| +| `create` | Create a new object | +| `delete` | Delete a specific object | +| `exists` | Whether a specific object exists | +| `set` | Modify an existing objects properties | +| `show` | Show a specific object | + + +Currently the following object types are available on CLI: + +* command +* endpoint +* host +* hostgroup +* notification +* service +* timeperiod +* user +* usergroup +* zone + + +### Create a new object + +Use this command to create a new Icinga object + + +#### Usage + +`icingacli director <type> create [<name>] [options]` + + +#### Options + +| Option | Description | +|-------------------|-------------------------------------------------------| +| `--<key> <value>` | Provide all properties as single command line options | +| `--json` | Otherwise provide all options as a JSON string | + + +#### Examples + +To create a new host you can provide all of its properties as command line +parameters: + +```shell +icingacli director host create localhost \ + --imports generic-host \ + --address 127.0.0.1 \ + --vars.location 'My datacenter' +``` + +It would say: + + Host 'localhost' has been created + +Providing structured data could become tricky that way. Therefore you are also +allowed to provide JSON formatted properties: + +```shell +icingacli director host create localhost \ + --json '{ "address": "127.0.0.1", "vars": { "test": [ "one", "two" ] } }' +``` + +Passing JSON via STDIN is also possible: + +```shell +icingacli director host create localhost --json < my-host.json +``` + + +### Delete a specific object + +Use this command to delete a single Icinga object. Just run + + icingacli director <type> delete <name> + +That's it. To delete the host created before, this would read + + icingacli director host delete localhost + +It will tell you whether your command succeeded: + + Host 'localhost' has been deleted + + +### Whether a specific object exists + +Use this command to find out whether a single Icinga object exists. Just +run: + + icingacli director <type> exists <name> + +So if you run... + + icingacli director host exists localhost + +...it will either tell you ... + + Host 'localhost' exists + +...or: + + Host 'localhost' does not exist + +When executed from custom scripts you could also just check the exit code, +`0` means that the object exists, `1` that it doesn't. + + +### Modify an existing objects properties + +Use this command to modify specific properties of an existing Icinga object. + + +#### Usage + + icingacli director <type> set <name> [options] + + +#### Options + +| Option | Description | +|----------------------------|-------------------------------------------------------| +| `--<key> <value>` | Provide all properties as single command line options | +| `--append-<key> <value>` | Appends to array values, like `imports`, | +| | `groups` or `vars.system_owners` | +| `--remove-<key> [<value>]` | Remove a specific property, eventually only | +| | when matching `value`. In case the property is an | +| | array it will remove just `value` when given | +| `--json` | Otherwise provide all options as a JSON string | +| `--replace` | Replace all object properties with the given ones | +| `--auto-create` | Create the object in case it does not exist | +| `--allow-overrides` | Set variable overrides for virtual Services | + + +#### Examples + +```shell +icingacli director host set localhost \ + --address 127.0.0.2 \ + --vars.location 'Somewhere else' +``` + +It will either tell you + + Host 'localhost' has been modified + +or, when for example issued immediately a second time: + + Host 'localhost' has not been modified + +Like create, this also allows you to provide JSON-formatted properties: + +```shell +icingacli director host set localhost --json '{ "address": "127.0.0.2" }' +``` + +This command will fail in case the specified object does not exist. This is +when the `--auto-create` parameter comes in handy. Command output will tell +you whether an object has either been created or (not) modified. + +With `set` you only set the specified properties and do not touch the other +ones. You could also want to completely override an object, purging all other +eventually existing and unspecified parameters. Please use `--replace` if this +is the desired behaviour. + + +### Show a specific object + +Use this command to show single objects rendered as Icinga 2 config or +in JSON format. + + +#### Usage + +`icingacli director <type> show <name> [options]` + + +#### Options + +| Option | Description | +|-------------------|------------------------------------------------------| +| `--resolved` | Resolve all inherited properties and show a flat | +| | object | +| `--json` | Use JSON format | +| `--no-pretty` | JSON is pretty-printed per default (for PHP >= 5.4) | +| | Use this flag to enforce unformatted JSON | +| `--no-defaults` | Per default JSON output skips null or default values | +| | With this flag you will get all properties | +| `--with-services` | For hosts only, also shows attached services | + +### Clone an existing object + +Use this command to clone a specific object. + +#### Usage + +`icingacli director <type> clone <name> --from <original> [options]` + +#### Options + +| Option | Description | +|---------------------|-----------------------------------------------------| +| `--from <original>` | The name of the object you want to clone | +| `--<key> <value>` | Override specific properties while cloning | +| `--replace` | In case an object <name> already exists replace it | +| | with the clone | +| `--flat` | Do no keep inherited properties but create a flat | +| | object with all resolved/inherited properties | + +#### Examples + +```shell +icingacli director host clone localhost2 --from localhost +``` + +```shell +icingacli director host clone localhost3 --from localhost --address 127.0.0.3 +``` + + +### Other interesting tasks + + +#### Rename objects + +There is no rename command, but a simple `set` can easily accomplish this task: + + icingacli director host set localhost --object_name localhost2 + +Please note that it is usually absolutely no problem to rename objects with +the Director. Even renaming something essential as a template like the famous +`generic-host` will not cause any trouble. At least not unless you have other +components outside your Director depending on that template. + + +#### Disable an object + +Objects can be disabled. That way they will still exist in your Director DB, +but they will not be part of your next deployment. Toggling the `disabled` +property is all you need: + + icingacli director host set localhost --disabled + +Valid values for booleans are `y`, `n`, `1` and `0`. So to re-enable an object +you could use: + + icingacli director host set localhost --disabled n + + +#### Working with booleans + +As we learned before, `y`, `n`, `1` and `0` are valid values for booleans. But +custom variables have no data type. And even if there is such, you could always +want to change or override this from CLI. So you usually need to provide booleans +in JSON format in case you need them in a custom variable. + +There is however one exception from this rule. CLI parameters without a given +value are handled as boolean flags by the Icinga Web 2 CLI. That explains why +the example disabling an object worked without passing `y` or `1`. You could +use this also to set a custom variable to boolean `true`: + + icingacli director host set localhost --vars.some_boolean + +Want to change it to false? No chance this way, you need to pass JSON: + + icingacli director host set localhost --json '{ "vars.some_boolean": false }' + +This example shows the dot-notation to set a specific custom variable. If we +have had used `{ "vars": { "some_boolean": false } }`, all other custom vars +on this object would have been removed. + + +#### Change object types + +The Icinga Director distincts between the following object types: + +| Type | Description | +|-------------------|-------------------------------------------------------------| +| `object` | The default object type. A host, a command and similar | +| `template` | An Icinga template | +| `apply` | An apply rule. This allows for assign rules | +| `external_object` | An external object. Can be referenced and used, will not be | +| | deployed | + +Example for creating a host template: + +```sh +icingacli director host create 'Some template' \ + --object_type template \ + --check_command hostalive +``` + +Please take a lot of care when modifying object types, you should not do so for +a good reason. The CLI allows you to issue operations that are not allowed in the +web frontend. Do not use this unless you really understand its implications. And +remember, with great power comes great responsibility. + + +Import/Export Director Objects +------------------------------ + +Some objects are not directly related to Icinga Objects but used by the Director +to manage them. To make it easier for administrators to for example pre-fill an +empty Director Instance with Import Sources and Sync Rules, related import/export +commands come in handy. + +Use `icingacli director export <type> [options]` to export objects of a specific +type: + +| Type | Description | +|-----------------------|-------------------------------------------------| +| `datafields` | Export all DataField definitions | +| `datalists` | Export all DataList definitions | +| `hosttemplatechoices` | Export all IcingaTemplateChoiceHost definitions | +| `importsources` | Export all ImportSource definitions | +| `jobs` | Export all Job definitions | +| `syncrules` | Export all SyncRule definitions | + +#### Options + +| Option | Description | +|---------------|------------------------------------------------------| +| `--no-pretty` | JSON is pretty-printed per default. Use this flag to | +| | enforce unformatted JSON | + +Use `icingacli director import <type> < exported.json` to import objects of a +specific type: + +| Type | Description | +|-----------------------|-------------------------------------------------| +| `importsources` | Import ImportSource definitions from STDIN | +| `syncrules` | Import SyncRule definitions from STDIN | + + +This feature is available since v1.5.0. + + +Director Configuration Basket +----------------------------- + +A basket contains a set of Director Configuration objects (like Templates, +Commands, Import/Sync definitions - but not single Hosts or Services). This +CLI command allows you to integrate them into your very own workflows + +## Available Actions + +| Action | Description | +|------------|---------------------------------------------------| +| `dump` | JSON-dump for objects related to the given Basket | +| `list` | List configured Baskets | +| `restore` | Restore a Basket from JSON dump provided on STDIN | +| `snapshot` | Take a snapshot for the given Basket | + +### Options + +| Option | Description | +|----------|------------------------------------------------------| +| `--name` | `dump` and `snapshot` require a specific object name | + +Use `icingacli director basket restore < exported-basket.json` to restore objects +from a specific basket. Take a snapshot or a backup first to be on the safe side. + +This feature is available since v1.6.0. + + +Health Check Plugin +------------------- + +You can use the Director CLI as an Icinga CheckPlugin and monitor your Director +Health. This will run all or just one of the following test suites: + +| Name | Description | +|--------------|-------------------------------------------------------------------| +| `config` | Configuration, Schema, Migrations | +| `sync` | All configured Sync Rules (pending changes are not a problem) | +| `import` | All configured Import Sources (pending changes are not a problem) | +| `jobs` | All configured Jobs (ignores disabled ones) | +| `deployment` | Deployment Endpoint, last deployment outcome | + +#### Usage + +`icingacli director health check [options]` + +#### Options + +| Option | Description | +|------------------|---------------------------------------| +| `--check <name>` | Run only a specific test suite | +| `--<db> <name>` | Use a specific Icinga Web DB resource | + +#### Examples + +```shell +icingacli director health check +``` + +Example for running a check only for the configuration: + +```shell +icingacli director health check --check config +``` + +Sample output: + +``` +Director configuration: 5 tests OK +[OK] Database resource 'Director DB' has been specified' +[OK] Make sure the DB schema exists +[OK] There are no pending schema migrations +[OK] Deployment endpoint is 'icinga.example.com' +[OK] There is a single un-deployed change +``` + + +Kickstart and schema handling +----------------------------- + +The `kickstart` and the `migration` command are handled in the [automation section](03-Automation.md), +so they are skipped here. + + +Configuration handling +---------------------- + +### Render your configuration + +The Director distincts between rendering and deploying your configuration. +Rendering means that Icinga 2 config will be pre-rendered and stored to the +Director DB. Nothing bad happens if you decide to render the current config +thousands of times in a loop. In case a config with the same checksum already +exists, it will store - nothing. + +You can trigger config rendering by running + +```shell +icingacli director config render +``` + +In case a new config has been created, it will tell you so: +``` +New config with checksum b330febd0820493fb12921ad8f5ea42102a5c871 has been generated +``` + +Run it once again, and you'll see that the output changes: +``` +Config with checksum b330febd0820493fb12921ad8f5ea42102a5c871 already exists +``` + + +### Config deployment + +#### Usage + +`icingacli director config deploy [options]` + +#### Options + +| Option | Description | +|----------------------------|------------------------------------------------------------------| +| `--checksum <checksum>` | Optionally deploy a specific configuration | +| `--force` | Force a deployment, even when the configuration hasn't changed | +| `--wait <seconds>` | Optionally wait until Icinga completed it's restart | +| `--grace-period <seconds>` | Do not deploy if a deployment took place less than <seconds> ago | + +#### Examples + +You do not need to explicitly render your config before deploying it to your +Icinga 2 master node. Just trigger a deployment, it will re-render the current +config: + +```shell +icingacli director config deploy +``` + +The output tells you which config has been shipped: + +``` +Config 'b330febd0820493fb12921ad8f5ea42102a5c871' has been deployed +``` + +Director tries to avoid needless deployments, so in case you immediately deploy +again, the output changes: +``` +Config matches active stage, nothing to do +``` + +You can override this by adding the `--force` parameter. It will then tell you: + +``` +Config matches active stage, deploying anyway +``` + +In case you want to do not want `deploy` to waste time to re-render your +config or in case you decide to re-deploy a specific, eventually older config +version the `deploy` command allows you to provide a specific checksum: + +```shell +icingacli director config deploy --checksum b330febd0820493fb12921ad8f5ea42102a5c871 +``` + +When using `icingacli` deployments in an automated way, and want to avoid fast +consecutive deployments, you can provide a grace period: + +```shell +icingacli director config deploy --grace-period 300 +``` + +### Deployments status +In case you want to fetch the information about the deployments status, +you can call the following CLI command: +```shell +icingacli director config deploymentstatus +``` +```json +{ + "active_configuration": { + "stage_name": "5c65cae0-4f1b-47b4-a890-766c82681622", + "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1", + "activity": "4f7bc6600dd50a989f22f82d3513e561ef333363" + } +} +``` +In case there is no active stage name related to the Director, active_configuration +is set to null. + +Another possibility is to pass a list of checksums to fetch the status of +specific deployments and (activity log) activities. +Following, you can see an example of how to do it: +```shell +icingacli director config deploymentstatus \ + --configs 617b9cbad9e141cfc3f4cb636ec684bd60073be1 \ + --activities 4f7bc6600dd50a989f22f82d3513e561ef333363 +``` +```json +{ + "active_configuration": { + "stage_name": "5c65cae0-4f1b-47b4-a890-766c82681622", + "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1", + "activity": "4f7bc6600dd50a989f22f82d3513e561ef333363" + }, + "configs": { + "617b9cbad9e141cfc3f4cb636ec684bd60073be1": "active" + }, + "activities": { + "4f7bc6600dd50a989f22f82d3513e561ef333363": "active" + } +} +``` + +You can also decide to access directly to a value inside the result JSON by +using the `--key` param: +```shell +icingacli director config deploymentstatus \ + --configs 617b9cbad9e141cfc3f4cb636ec684bd60073be1 \ + --activities 4f7bc6600dd50a989f22f82d3513e561ef333363 \ + --key active_configuration.config +``` +``` +617b9cbad9e141cfc3f4cb636ec684bd60073be1 +``` + + + +### Cronjob usage + +You could decide to pre-render your config in the background quite often. As of +this writing this has one nice advantage. It allows the GUI to find out whether +a bunch of changes still results into the very same config. +only one + + +Run sync and import jobs +------------------------ + +### Import Sources + +#### List available Import Sources + +This shows a table with your defined Import Sources, their IDs and +current state. As triggering Imports requires an ID, this is where you +can look up the desired ID. + +`icingacli director importsource list` + +#### Check a given Import Source for changes + +This command fetches data from the given Import Source and compares it +to the most recently imported data. + +`icingacli director importsource check --id <id>` + +##### Options + +| Option | Description | +|---------------|---------------------------------------------------------| +| `--id <id>` | An Import Source ID. Use the list command to figure out | +| `--benchmark` | Show timing and memory usage details | + +#### Fetch data from a given Import Source + +This command fetches data from the given Import Source and outputs them +as plain JSON + +`icingacli director importsource fetch --id <id>` + +##### Options + +| Option | Description | +|---------------|---------------------------------------------------------| +| `--id <id>` | An Import Source ID. Use the list command to figure out | +| `--benchmark` | Show timing and memory usage details | + +#### Trigger an Import Run for a given Import Source + +This command fetches data from the given Import Source and stores it to +the Director DB, so that the next related Sync Rule run can work with +fresh data. In case data didn't change, nothing is going to be stored. + +`icingacli director importsource run --id <id>` + +##### Options + +| Option | Description | +|---------------|---------------------------------------------------------| +| `--id <id>` | An Import Source ID. Use the list command to figure out | +| `--benchmark` | Show timing and memory usage details | + +### Sync Rules + +#### List defined Sync Rules + +This shows a table with your defined Sync Rules, their IDs and current +state. As triggering a Sync requires an ID, this is where you can look +up the desired ID. + +`icingacli director syncrule list` + +#### Check a given Sync Rule for changes + +This command runs a complete Sync in memory but doesn't persist eventual +changes. + +`icingacli director syncrule check --id <id>` + +##### Options + +| Option | Description | +|---------------|----------------------------------------------------| +| `--id <id>` | A Sync Rule ID. Use the list command to figure out | +| `--benchmark` | Show timing and memory usage details | + +#### Trigger a Sync Run for a given Sync Rule + +This command builds new objects according your Sync Rule, compares them +with existing ones and persists eventual changes. + +`icingacli director syncrule run --id <id>` + +##### Options + +| Option | Description | +|---------------|----------------------------------------------------| +| `--id <id>` | A Sync Rule ID. Use the list command to figure out | +| `--benchmark` | Show timing and memory usage details | + + +Database housekeeping +--------------------- + +Your database may grow over time and ask for various housekeeping tasks. You +can usually store a lot of data in your Director DB before you would even +notice a performance impact. + +Still, we started to prepare some tasks that assist with removing useless +garbage from your DB. You can show available tasks with: + + icingacli director housekeeping tasks + +The output might look as follows: + +``` + Housekeeping task (name) | Count +-----------------------------------------------------------|------- + Undeployed configurations (oldUndeployedConfigs) | 3 + Unused rendered files (unusedFiles) | 0 + Unlinked imported row sets (unlinkedImportedRowSets) | 0 + Unlinked imported rows (unlinkedImportedRows) | 0 + Unlinked imported properties (unlinkedImportedProperties) | 0 +``` + +You could run a specific task with + + icingacli director housekeeping run <taskName> + +...like in: + + icingacli director housekeeping run unlinkedImportedRows + +Or you could also run all of them, that's the preferred way of doing this: + + icingacli director housekeeping run ALL + +Please note that some tasks once issued create work for other tasks, as +lost imported rows might appear once you remove lost row sets. So `ALL` +is usually the best choice as it runs all of them in the best order. |