Adding upstream version 1.10.2.upstream/1.10.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.