diff options
Diffstat (limited to 'doc')
67 files changed, 4352 insertions, 0 deletions
diff --git a/doc/01-Introduction.md b/doc/01-Introduction.md new file mode 100644 index 0000000..6d767ae --- /dev/null +++ b/doc/01-Introduction.md @@ -0,0 +1,51 @@ +<a id="Introduction"></a>Introduction +===================================== + +Welcome to the Icinga Director, the bleeding edge configuration tool for +Icinga 2! Developed as an Icinga Web 2 module it aims to be your new +favorite Icinga config deployment tool. Even if you prefer plain text +files and manual configuration, chances are good that the Director will +change your mind. + +Director is here to make your life easier. As an Icinga 2 pro you know +all the knobs and tricks Icinga2 provides. However, you are not willing +to do the same work again and again. Someone wants to add a new server, +tweak some thresholds, adjust notifications? They shouldn't need to +bother you. + +No way, you might think. You do not trust your users, they might break +things. Well... no. Not with the Director. It provides an audit log that +shows any single change. You can re-deploy old configurations at any time. +And you will be allowed to restrict what your users are allowed to do in +a very granular way. + +Doing automation? Want to feed your monitoring from your configuration +management tool, or from your CMDB? You'll love the endless possibilities +Director provides. + + +Basic architecture +------------------ + +Icinga Director uses the Icinga 2 API to talk to your monitoring system. +It will help you to deploy your configuration, regardless of whether you +are using a single node Icinga installation or a distributed setup with +multiple masters and satellites. + + +------------+ +--------------+ +------------+ + | Sat 1 / EU | | Sat 2 / Asia | | Sat 3 / US | + +------------+ +--------------+ +------------+ + \ / / + \ / / + +-------------+ +-------------+ + | Master 1 | <===> | Master 2 | (Master-Zone) + +-------------+ +-------------+ + ^ ^ + | Icinga 2 REST API : + | : + +----------------------------+ + | Icinga Director | + +----------------------------+ + +Using the Icinga 2 Agent? Perfect, the Director will make your life much +easier! diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..10604d1 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,75 @@ +<!-- {% if index %} --> +# Installing Icinga Director + +The recommended way to install Icinga Director and its dependencies is to use prebuilt packages for +all supported platforms from our official release repository. +Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is required to run Icinga Director +and if it is not already set up, it is best to do this first. + +The following steps will guide you through installing and setting up Icinga Director. + +To upgrade an existing Icinga Director installation to a newer version, +see the [upgrading](05-Upgrading.md) documentation for the necessary steps. + +If you want to automate the installation, configuration and upgrade, +you can learn more about it in the [automation](03-Automation.md) section of this documentation. + +## Optional Requirements + +The following requirements are not necessary for installation, +but may be needed later if you want to import from one of the listed sources: + +* For **IBM Db2** imports: `php-pdo-ibm` +* For **Microsoft SQL Server** imports: `php-mssql`, `php-pdo-dblib` or `php-sybase` depending on your platform +* For **Oracle Database** imports: `php-oci8` or `php-pdo-oci` depending on your platform +* For **SQLite** imports: `php-pdo-sqlite` +<!-- {% else %} --> +<!-- {% if not icingaDocs %} --> + +## Installing Icinga Director Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-director` package +or install [from source](02-Installation.md.d/From-Source.md). +<!-- {% endif %} --> + +## Setting up the Database + +A MySQL (≥5.7), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Director. +Please follow the steps listed for your target database, to set up the database and the user. +The schema will be imported later via the web interface. + +### Setting up a MySQL or MariaDB Database + +> **Warning** +> Make sure to replace `CHANGEME` with a secure password. + +``` +mysql -e "CREATE DATABASE director CHARACTER SET 'utf8'; + CREATE USER director@localhost IDENTIFIED BY 'CHANGEME'; + GRANT ALL ON director.* TO director@localhost;" +``` + +### Setting up a PostgreSQL Database + +> **Warning** +> Make sure to replace `CHANGEME` with a secure password. + +``` +psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';" +psql director -q -c "CREATE USER director WITH PASSWORD 'CHANGEME'; +GRANT ALL PRIVILEGES ON DATABASE director TO director; +CREATE EXTENSION pgcrypto;" +``` + +## Configuring Icinga Director + +Log in to your running Icinga Web setup with a privileged user +and follow the steps below to configure Icinga Director: + +1. Create a new resource for the Icinga Director [database](#setting-up-the-database) via the + `Configuration → Application → Resources` menu. + Please make sure that you configure `utf8` as encoding. +2. Select `Icinga Director` directly from the main menu + and you will be taken to the kickstart wizard. Follow the instructions and you are done! +<!-- {% endif %} --><!-- {# end else if index #} --> diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 0000000..ea17233 --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,83 @@ +# Installing Icinga Director from Source + +These are the instructions for manual Director installations. + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `director` as the module name. The following requirements must also be met. + +## Requirements + +* PHP (≥7.3) + * Director v1.10 is the last version with support for PHP v5.6 +* [Icinga 2](https://github.com/Icinga/icinga2) (≥2.8.0) + * It is recommended to use the latest feature release of Icinga 2 + * All versions since 2.4.3 should also work fine, but + we do no longer test and support them. + * Some features require newer Icinga 2 releases + * Flapping requires 2.8 for the thresholds to work - and at least 2.7 on all + nodes +* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.8.0). All versions since 2.2 should also work fine, but + might show smaller UI bugs and are not actively tested +* The following Icinga modules must be installed and enabled: + * [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (≥0.18.0) + * If you are using Icinga Web <2.9.0, the following modules are also required + * [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (≥0.5.0) + * [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (≥0.9.0) +* A database: MariaDB (≥10.1), MySQL (≥5.7), PostgreSQL (≥9.6). Other + forks and older versions might work, but are neither tested nor supported +* `php-pdo-mysql` and/or `php-pdo-pgsql` +* `php-curl` +* `php-iconv` +* `php-pcntl` (might already be built into your PHP binary) +* `php-posix` or `php-process` depending on your platform +* `php-sockets` (might already be built into your PHP binary) + +## Installing from Release Tarball + +Download the [latest version](https://github.com/Icinga/icingaweb2-module-director/releases) +and extract it to a folder named `director` in one of your Icinga Web module path directories. + +You might want to use a script as follows for this task: + +```shell +MODULE_VERSION="1.10.2" +ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules" +REPO_URL="https://github.com/icinga/icingaweb2-module-director" +TARGET_DIR="${ICINGAWEB_MODULEPATH}/director" +URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz" + +install -d -m 0755 "${TARGET_DIR}" +wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1 +icingacli module enable director +``` + +## Installing from Git Repository + +Another convenient method is to install directly from our Git repository. +Simply clone the repository in one of your Icinga web module path directories. + +You might want to use a script as follows for this task: + +```shell +MODULE_VERSION="1.10.2" +ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules" +REPO_URL="https://github.com/icinga/icingaweb2-module-director" +TARGET_DIR="${ICINGAWEB_MODULEPATH}/director" + +git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION} +icingacli module enable director +``` + +## Setting up the Director Daemon + +For manual installations, the daemon user, its directory, and the systemd service need to be set up: + +```shell +useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /sbin/nologin icingadirector +install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector +install -pm 0644 contrib/systemd/icinga-director.service /etc/systemd/system +systemctl daemon-reload +systemctl enable --now icinga-director +``` +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/03-Automation.md b/doc/03-Automation.md new file mode 100644 index 0000000..ca3d1d3 --- /dev/null +++ b/doc/03-Automation.md @@ -0,0 +1,134 @@ +<a id="Automation"></a>Automation - Configuration management +============================================================ + +Director has been designed to work in distributed environments. In case +you're using tools like Puppet, Ansible, Salt (R)?ex or similar, this +chapter is what you're looking for! + +Generic hints +------------- + +Director keeps all of its configuration in a relational database. So, +all you need to tell him is how it can reach and access that db. In case +you already rolled out Icinga Web 2 you should already be used to handle +resource definitions. + +The Director needs a `database resource`, and your RDBMS must either by +MySQL, MariaDB or PostgreSQL. This is how such a resource could look like +in your `/etc/icingaweb2/resources.ini`: + +```ini +[Director DB] +type = "db" +db = "mysql" +host = "localhost" +dbname = "director" +username = "director" +password = "***" +charset = "utf8" +``` + +Please note that the charset is required and MUST be `utf8`. + +Next you need to tell the Director to use this database resource. Create +its `config.ini` with the only required setting: + +```ini +[db] +resource = "Director DB" +``` + +Hint: `/etc/icingaweb2/modules/director/config.ini` is usually the full +path to this config file. + +#### Schema creation and migrations + +You do not need to manually care about creating the schema and to migrate +it for newer versions. Just `grant` the configured user all permissions on +his database. + +On CLI then please run: + + icingacli director migration run --verbose + +You should run this command after each upgrade, or you could also run it +at a regular interval. Please have a look at... + + icingacli director migration pending --verbose + +...in case you are looking for an idempotent way of managing the schema. +Use `--help` to learn more about those commands. + +If you have any good reason for doing so and feel experienced enough you +can of course also manage the schema on your own. All required files are +to be found in our `schema` directories. + + +Deploy Icinga Director with Puppet +---------------------------------- + +Drop the director source repository to a directory named `director` in +one of your `module_path`'s and enable the module as you did with all the +others. + +Deploy the mentioned database resource and `config.ini`. Director could +now be configured and kick-started via the web frontend. But you are here +for automation, so please read on. + +### Handle schema migrations + +It doesn't matter whether you already have a schema, did a fresh install +or just an upgrade. Migrations are as easy as defining: + + exec { 'Icinga Director DB migration': + path => '/usr/local/bin:/usr/bin:/bin', + command => 'icingacli director migration run', + onlyif => 'icingacli director migration pending', + } + +Hint: please do not travel back in time, schema downgrades are not +supported. + +### Kickstart an empty Director database + +The Director kickstart wizard helps you with setting up a connection to +Icinga2 master node, import its endpoint and zone definition and it also +syncs already configured command definitions. But this wizard is not only +available through the web frontend, you can perfectly trigger it in an +idempotent way with Puppet: + + exec { 'Icinga Director Kickstart': + path => '/usr/local/bin:/usr/bin:/bin', + command => 'icingacli director kickstart run', + onlyif => 'icingacli director kickstart required', + require => Exec['Icinga Director DB migration'], + } + +Nothing will happen so far. Kickstart will not do anything unless you +drop a `kickstart.ini` allowing the CLI kickstart helper to do so: + +```ini +[config] +endpoint = icinga-master +; host = 127.0.0.1 +; port = 5665 +username = director +password = *** +``` + +Usually `/etc/icingaweb2/modules/director/kickstart.ini` should be the +full path to this file. `endpoint` (master certificate name), `username` +and `password` (fitting an already configured `ApiUser`) are required. +`host` can be a resolvable hostname or an IP address. `port` is 5665 per +default in case none is given. And of course your Icinga2 installation +needs to have a corresponding `ApiListener` (look at your enabled +features) listening at the given port. + +You can run the `kickstart` from the CLI if you don't use a tool for +automation. + + icingacli director kickstart run + +You can rerun the kickstart if you have to reimport changed local +config, even when the beforementioned check tells you you don't need to. +Or you could use the import/synchronisation features of Director. diff --git a/doc/04-Getting-started.md b/doc/04-Getting-started.md new file mode 100644 index 0000000..1db80d6 --- /dev/null +++ b/doc/04-Getting-started.md @@ -0,0 +1,60 @@ +<a id="Getting-started"></a>Getting started +=========================================== + +When new to the Director please make your first steps with a naked Icinga +environment. Director is not allowed to modify existing configuration in +`/etc/icinga2`. And while importing existing config is possible (happens for +example automagically at kickstart time), it is a pretty advanced task you +should not tackle at the early beginning. + +Define a new global zone +------------------------ + +This zone must exist on every node directly or indirectly managed by the +Icinga Director: + +```icinga2 +object Zone "director-global" { + global = true +} +``` + +Create an API user +------------------ + +```icinga2 +object ApiUser "director" { + password = "***" + permissions = [ "*" ] + //client_cn = "" +} +``` + +To allow the configuration of an API user your Icinga 2 instance needs a +`zone` and an `endpoint` object for itself. If you have a clustered +setup or you are using agents you already have this. If you are using a +fresh Icinga 2 installation or a standalone setup with other ways of +checking your clients, you will have to create them. + +The easiest way to set up Icinga 2 with a `zone` and `endpoint` is by +running the [Icinga 2 Setup Wizard](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-setup-master). + +Take some time to really understand how to work with Icinga Director first. + + +Other topics that might interest you +------------------------------------ + +* [Working with agents](24-Working-with-agents.md) +* [Understanding how Icinga Director works](10-How-it-works.md) + +What you should not try to start with +------------------------------------- + +Director has not been built to help you with managing existing hand-crafted +configuration in /etc/icinga2. There are cases where it absolutely would +make sense to combine the Director with manual configuration. You can also +use multiple tools owning separate config packages. But these are pretty +advanced topics. + + diff --git a/doc/05-Upgrading.md b/doc/05-Upgrading.md new file mode 100644 index 0000000..63630b6 --- /dev/null +++ b/doc/05-Upgrading.md @@ -0,0 +1,230 @@ +<a id="Upgrading"></a>Upgrading +=============================== + +Icinga Director is very upgrade-friendly. We never had any complaint referring +data loss on upgrade. But to be on the safe side, please always [backup](#backup-first) +your database before running an upgrade. + +Then drop the new version to your Icinga Web 2 module folder, and you're all done. +Eventually refresh the page in your browser<sup>[[1]](#footnote1)</sup>, and you +are ready to go. + +Should there any other actions be required (like [schema migrations](#schema-migrations)), +you will be told so in your frontend. + +Please read more about: + +* [Database Backup](#backup-first) +* [Upgrading to 1.10.x](#upgrade-to-1.10.x) +* [Upgrading to 1.9.x](#upgrade-to-1.9.x) +* [Upgrading to 1.8.x](#upgrade-to-1.8.x) +* [Upgrading to 1.7.x](#upgrade-to-1.7.x) +* [Upgrading to 1.6.x](#upgrade-to-1.6.x) +* [Upgrading to 1.5.x](#upgrade-to-1.5.x) +* [Upgrading to 1.4.x](#upgrade-to-1.4.x) +* [Upgrading to 1.3.0](#upgrade-to-1.3.0) +* [Upgrading to 1.2.0](#upgrade-to-1.2.0) +* [Upgrading to 1.1.0](#upgrade-to-1.1.0) +* [How to work with the latest GIT master](#git-master) +* [Database schema upgrades](#schema-migrations) +* [Job Runner restart](#restart-jobrunner) +* [Downgrading](#downgrade) + +And last but not least, having a look at our [Changelog](82-Changelog.md) is +usually a good idea before applying an upgrade. + +<a name="backup-first"></a>Always take a backup first +----------------------------------------------------- + +All you need for backing up your Director is a snapshot of your database. Please +use the tools provided by your database backend, like `mysqldump` or `pg_dump`. +Restoring from a backup is trivial, and Director will always be able to apply +pending database migrations to an imported old database snapshot. + +<a name="upgrade-to-1.9.x"></a>Upgrading to 1.10.x +-------------------------------------------------- + +Please check module dependencies, we raised some of them. In case you're missing +one of them, the Web UI will tell you after the upgrade. You'll then be prompted +to apply pending Database Migrations. + +PHP 7.3 is now claimed to be required, but we still support 5.6+ on Director +v1.10.x. Same goes for database dependencies: you should upgrade them to recent +versions, but v1.10 still works on the ones supported with v1.9.x. + +<a name="upgrade-to-1.9.x"></a>Upgrading to 1.9.x +------------------------------------------------- + +Please check module dependencies, we raised some of them. In case you're missing +one of them, the Web UI will tell you after the upgrade. You'll then be prompted +to apply pending Database Migrations. + +<a name="upgrade-to-1.8.x"></a>Upgrading to 1.8.x +------------------------------------------------- + +Before upgrading, please upgrade the [incubator module](https://github.com/Icinga/icingaweb2-module-incubator) +to (at least) v0.6.0. As always, you'll be prompted to apply pending Database +Migrations. + +<a name="upgrade-to-1.7.x"></a>Upgrading to 1.7.x +------------------------------------------------- + +Since v1.7.0 Icinga Director requires at least PHP 5.6. Also, this version +introduces new dependencies. Please make sure that the following Icinga Web 2 +modules have been installed and enabled: + +* [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (>=0.3.0) +* [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (>=0.5.0) +* [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (>=0.7.0) + +Also, the following PHP libraries should be available: + +* php-pcntl (might already be built into your PHP binary) +* php-posix (on RHEL/CentOS this is php-process, or rh-php7x-php-process) +* php-sockets (might already be built into your PHP binary) + +Apart from this, in case you are running 1.6.x or any GIT master since then, +all you need is to replace the Director module folder with the new one. Or to +run `git checkout v1.7.x` in case you installed Director from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. There +is now a new, modern (and mandatory) Background Daemon, the old (optional) Jobs +Daemon must be removed. Please check our [documentation](75-Background-Daemon.md) +for related instructions. + +<a name="upgrade-to-1.6.x"></a>Upgrading to 1.6.x +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.5.x or any +GIT master since then, all you need is to replace the Director module folder +with the new one. Or to run git checkout v1.6.0 in case you installed Director +from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. + +<a name="upgrade-to-1.5.x"></a>Upgrading to 1.5.x +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.4.x or any +GIT master since then, all you need is to replace the Director module folder +with the new one. Or to run git checkout v1.5.0 in case you installed Director +from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. + +<a name="upgrade-to-1.4.x"></a>Upgrading to 1.4.x +------------------------------------------------- + +Since v1.4.0 Icinga Director requires at least PHP 5.4. Apart from this, there +is nothing special to take care of. In case you are running 1.3.x or any GIT +master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.4.x` in case you installed Director +from GIT. + +<a name="upgrade-to-1.3.x"></a>Upgrading to 1.3.x +------------------------------------------------- + +In case you are running 1.2.0 or any GIT master since then, all you need is to +replace the Director module folder with the new one. Or to run `git checkout v1.3.x` +in case you installed Director from GIT. + +When running Director since 1.1.0 or earlier on PostgreSQL, you might not yet +have the PostgreSQL crypto extension installed (Package: `postgresql-contrib`) and +enabled: + + psql -q -c "CREATE EXTENSION pgcrypto;" + + +<a name="upgrade-to-1.2.0"></a>Upgrading to 1.2.0 +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.1.0 or any +GIT master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.2.0` in case you installed Director from +GIT. + +<a name="upgrade-to-1.1.0"></a>Upgrading to 1.1.0 +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.0.0 or any +GIT master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.1.0` in case you installed Director from +GIT. + +<a name="git-master"></a>Work with the latest GIT master +-------------------------------------------------------- + +Icinga Director is still a very young project. Lots of changes are going on, +a lot of improvements, bug fixes and new features are still being added every +month. People living on the bleeding edge might prefer to use all of them as +soon as possible. + +So here is the good news: this is no problem at all. It's absolutely legal and +encouraged to run Director as a pure GIT clone, installed as such: + +```sh +ICINGAWEB_MODULES=/usr/share/icingaweb2/modules +DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git +git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director +``` + +Don't worry about schema upgrades. Once they made it into our GIT master there +will always be a clean upgrade path for you, no manual interaction should ever +be required. Like every human being, we are not infallible. So, while our strict +policy says that the master should never break, this might of course happen. + +In that case, please [let us know](https://github.com/Icinga/icingaweb2-module-director/issues). +We'll try to fix your issue as soon as possible. + +<a name="schema-migrations"></a>Database schema migrations +---------------------------------------------------------- + +In case there are any DB schema upgrades (and that's still often the case) this +is no problem at all. They will pop up on your Director Dashboard and can be +applied with a single click. And if your Director is deployed automatically by +and automation tool like Puppet, also schema upgrades can easily be handled +that way. Just follow the [related examples](03-Automation.md) in our documentation. + +<a name="schema-migrations"></a>Manual schema migrations +---------------------------------------------------------- + +Please *do not* manually apply our schema migration files. We are very strict +about our connection settings, encodings and SQL modes. Client encoding MUST be +UTF-8, for MySQL and MariaDB we are using the following SQL Mode: + +```sql +SET SESSION SQL_MODE='STRICT_ALL_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, +ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,ANSI_QUOTES,PIPES_AS_CONCAT, +NO_ENGINE_SUBSTITUTION'; +``` + +Our migration files are written based on the assumption that those rules are +strictly followed, and there may be other ones in future. So please use one +of the supported migration methods either on the web or on command line and +stay away from directly interfering with the schema. + +<a name="restart-jobrunner"></a>Restart the Job Runner service +-------------------------------------------------------------- + +The Job Runner forks it's jobs, so usually a changed code base will take effect +immediately. However, there might be (schema or code) changes involving the Runner +process itself. To be on the safe side please always restart it after an upgrade, +even when it's just a quick `git pull`: + +```sh +systemctl restart director-jobs.service +``` + +<a name="downgrade"></a>Downgrading +----------------------------------- + +Downgrading is **not supported**. Most parts of the code will even refuse to +work in case there are new fields in their database tables. Migrations are +intentionally provided for upgrades only. In case you want to travel back in +time please restore a matching former [Database Backup](#backup-first). + +<a name="footnote1">[1]</a>: +Future Icinga Web 2 version will also take care of this step. We want to be +able to have the latest JavaScript and CSS for any active module to be shipped +silently without manual interaction to any connected browser within less then +15 seconds after the latest module has been installed, enabled or upgraded. diff --git a/doc/10-How-it-works.md b/doc/10-How-it-works.md new file mode 100644 index 0000000..5f683fb --- /dev/null +++ b/doc/10-How-it-works.md @@ -0,0 +1,112 @@ +<a id="How-it-works"></a>How it works +===================================== + +This chapter wants to give you some basic understanding of how the +Director works with your Icinga installation. At least once you start +to work with satellite zones it might be worth to give this a read. + + +How your configuration is going to be rendered +---------------------------------------------- + +First of all, the Director doesn't write to `/etc/icinga2`. That's where +you keep to store your manual configuration and that's where you are +required to do the basic config tasks required to get Icinga 2 ready for +the Director. + +The Director uses the Icinga 2 API to ship the configuration. It does +so by shipping full config packages, it does not deal with single +objects. This makes deployments much faster. It also makes it easier to +eventually use Director in parallel with manual configuration or +configuration shipped by other tools. + +Internally, Icinga 2 manages part of its configuration in its `var/lib` +directory. This is usually to be found in `/var/lib/icinga2`. Config +packages are stored to `/var/lib/icinga2/api/packages` once shipped +through the API. So as soon as you deployed your first configuration +with the Director, there will be a new timestamped subdirectory +containing the new configuration. + +Those subdirectories are called stages. You'll often see more than one +of them. When a new config is deployed, Icinga 2 tries to restart with +that new stage. In case it fails, Icinga 2 will keep running with the +former configuration. When it succeeds, it will terminate the old process +and keep running with the new configuration. + +In either scenario, it writes an exit code and its startup log to the +corresponding stage directory. This allows the Director to check back +later on to fetch this information. That's why you see all those nice +startup log outputs along with your deployment history in your frontend. + +The configuration in such a stage directory is structured like your +Icinga 2 config directory in `/etc`: there is a `conf.d` and a `zones.d` +subdirectory. In `zones.d` Director will create a subdirectory for each +Zone it wants to deploy config to. + +Please note that those `zones.d` subdirectories are subject to config +sync. To get them syncronized to other nodes, the following must be +true for them: + +* they must have a zone definition for that zone in their local config +* they must make part of your deployment endpoints zone or be a direct + or indirect subzone of that one +* the `accept_config` setting must be `true` in their `ApiListener` + object definition + +The director does not try to create additional zones your nodes do not +know about. In a distributed environment it is essential that the +Director can ship parts of the configuration to specific zones and +other parts to a global zone. The name of its preferred global zone +is currently hardcoded to `director-global`. Please make sure that such +a zone exists on all involved nodes that should get config from the +Director in a direct or indirect way: + +```icinga2 +object Zone "director-global" { + global = true +} +``` + +Please do not use this zone for your own configuration files. +There is a zone called `global-templates` available in default Icinga +setups that's meant for configuration files. `director-global` is reserved +for use by Icinga Director. + +Zone membership handling +------------------------ + +Mostly you do not need to care much about Zones when working with the +Director. In case you have no Satellite node, you wouldn't even notice +their existence. + +You are not required to deal with Agent Zones, as the Director does +this for you. Please refer to [Working with agents](24-Working-with-agents.md) +for related examples. + +Currently the GUI does not allow you to set the zone property on single +objects. You can circumvent this through the Director's [REST API](70-REST-API.md), +with Sync rules and through the CLI. However, that shouldn't be part +of your normal workflow. So if this restriction causes trouble with what +you want to build please let us know. Explain your scenario, make us +understand what you want to achieve. + +We think of this restriction being a good idea, as it makes things +easier for most people. That doesn't mean that we would refuse to change +our mind on this. At least not if you come up with a very good +reasonable use case. + + +Object rendering +---------------- + +This chapter explains where the Director renders which config object to. + +* Most objects are rendered to the master zone per default +* Templates, commands and apply rules are rendered to the global zone +* Objects with a zone property are rendered to that zone, even if they + inherited that property +* Host objects configured as an Agent are rendered to the master zone, + as Director configures them as a Command Execution Bridge +* Agents with a zone property respect that setting +* Every command is rendered to the global zone per default + diff --git a/doc/12-Handling-custom-variables.md b/doc/12-Handling-custom-variables.md new file mode 100644 index 0000000..3c9a9cf --- /dev/null +++ b/doc/12-Handling-custom-variables.md @@ -0,0 +1,13 @@ +<a id="Handling-custom-variables"></a>Working with custom variables +=================================================================== + +Icinga Director allows you to work with custom variables in a very +powerful way. It implements the concept of `Data fields`. If you want +your users to be able to fill specific custom variables, you need to +add corresponding `fields` to + +Examples +-------- +* Add fields for existing commands +* Allow to fill an [array of interfaces](14-Fields-example-interfaces-array.md) + diff --git a/doc/14-Fields-example-interfaces-array.md b/doc/14-Fields-example-interfaces-array.md new file mode 100644 index 0000000..e2a3ba6 --- /dev/null +++ b/doc/14-Fields-example-interfaces-array.md @@ -0,0 +1,31 @@ +<a id="Fields-example-interfaces-array"></a>Working with fields - interfaces array example +============================================== + +This example wants to show you how to make use of the `Array` data type +when creating fields for custom variables. First, please got to the `Dashboard` +and choose the `Define data fields` dashlet: + + + +Then create a new data field and select `Array` as its data type: + + + +Then create a new `Host template` (or use an existing one): + + + +Now add your formerly created data field to your template: + + + +That's it, now you are ready to create your first corresponding host. Once +you add your formerly created template, a new form field for your custom +variable will show up: + + + +Have a look at the config preview, it will show you how your `Array`-based +custom variable will look like once deployed: + + diff --git a/doc/15-Service-apply-for-example.md b/doc/15-Service-apply-for-example.md new file mode 100644 index 0000000..531e4a7 --- /dev/null +++ b/doc/15-Service-apply-for-example.md @@ -0,0 +1,44 @@ +<a id="Service-apply-for-example"></a>Working with Apply for rules - tcp ports example +============================================== + +This example wants to show you how to make use of `Apply For` rule for services. + +First you need to define a `tcp_ports` data field of type `Array` assigned to a `Host Template`. +Refer to [Working with fields](14-Fields-example-interfaces-array.md) section to setup a data field. +You also need to define a `tcp_port` data field of type `String`, we will associate it to a +`Service Template` later. + +Then, please go to the `Dashboard` and choose the `Monitored services` dashlet: + + + +Then create a new `Service template` with check command `tcp`: + + + +Then associate the data field `tcp_port` to this `Service template`: + + + +Then create a new `apply-rule` for the `Service template`: + + + +Now define the `Apply For` property, select the previously defined field `tcp_ports` associated to +the host template. `Apply For` rule define a variable `config` that can be used as `$config$`, it +corresponds to the item of the array it will iterate on. + +Set the `Tcp port` property to `$config$`: + + + +(Side note: if you can't see your `tcp_ports` property in `Apply For` dropdown, try to create one +host with a non-empty `tcp_ports` value.) + +That's it, now all your hosts defining a `tcp_ports` variable will be assigned the `Tcp Check` +service. + +Have a look at the config preview, it will show you how `Apply For` services will look like once +deployed: + + diff --git a/doc/16-Fields-example-SNMP.md b/doc/16-Fields-example-SNMP.md new file mode 100644 index 0000000..3cc7569 --- /dev/null +++ b/doc/16-Fields-example-SNMP.md @@ -0,0 +1,104 @@ +<a id="Fields-example-SNMP"></a>Data Fields example: SNMP +========================= + +Ever wondered how to provide an easy to use SNMP configuration to your users? +That's what we're going to show in this example. Once completed, all your Hosts +inheriting a specific (or your "default") Host Template will provide an optional +`SNMP version` field. + +In case you choose no version, nothing special will happen. Otherwise, the host +offers additional fields depending on the chosen version. `Community String` for +`SNMPv1` and `SNMPv2c`, and five other fields ranging from `Authentication User` +to `Auth` and `Priv` types and keys for `SNMPv3`. + +Your services should now be applied not only based on various Host properties +like `Device Type`, `Application`, `Customer` or similar - but also based on +the fact whether credentials have been given or not. + + +Prepare required Data Fields +---------------------------- + +As we already have learned, `Fields` are what allows us to define which custom +variables can or should be defined following which rules. We want SNMP version +to be a drop-down, and that's why we first define a `Data List`, followed by +a `Data Field` using that list: + +### Create a new Data List + + + +### Fill the new list with SNMP versions + + + +### Create a corresponding Data Field + + + +Next, please also create the following elements: + +* a list *SNMPv3 Auth Types* providing `MD5` and `SHA` +* a list *SNMPv3 Priv Types* providing at least `AES` and `DES` +* a `String` type field `snmp_community` labelled *SNMP Community* +* a `String` type field `snmpv3_user` labelled *SNMPv3 User* +* a `String` type field `snmpv3_auth` labelled *SNMPv3 Auth* (authentication key) +* a `String` type field `snmpv3_priv` labelled *SNMPv3 Priv* (encryption key) +* a `Data List` type field `snmpv3_authprot` labelled *SNMPv3 Auth Type* +* a `Data List` type field `snmpv3_privprot` labelled *SNMPv3 Priv Type* + +Please do not forget to add meaningful descriptions, telling your users about +in-house best practices. + + +Assign your shiny new Fields to a Template +------------------------------------------ + +I'm using my default Host Template for this, but one might also choose to provide +`SNMP version` on Network Devices. Should Network Device be a template? Or just +an option in a `Device Type` field? You see, the possibilities are endless here. + +This screenshot shows part of my assigned Fields: + + + +While I kept `SNMP Version` optional, all other fields are mandatory. + + +Use your Template +----------------- + +As soon as you choose your template, a new field is shown: + + + +In case you change it to `SNMPv2c`, a `Community String` will be required: + + + +Switch it to SNMPv3 to see completely different fields: + + + +Once stored please check the rendered configuration. Switch the SNMP versions +forth and back, and you should see that filtered fields will also remove the +corresponding values from the object. + + +Assign Services based on those properties +----------------------------------------- + +You should design your Commands to use that set of properties. Change the example +slightly to fit ITL Commands in case you're using those (snmpv3_*_type VS _alg). + +Your Cisco Health checks assigned to all: + +* routers or switches +* manifactured by Cisco +* with SNMP credentials, regardless of which version + +...might then look as follows: + + + +Have fun! diff --git a/doc/24-Working-with-agents.md b/doc/24-Working-with-agents.md new file mode 100644 index 0000000..24473db --- /dev/null +++ b/doc/24-Working-with-agents.md @@ -0,0 +1,80 @@ +<a id="Working-with-agents"></a>Working with Agents and Config Zones +==================================================================== + +Working with Icinga 2 Agents can be quite tricky, as each Agent needs +its own Endpoint and Zone definition, correct parent, peering host and +log settings. There may always be reasons for a completely custom-made +configuration. However, I'd **strongly suggest** using the **Director- +assisted** variant. It will save you a lot of headaches. + + +Preparation +----------- + +Agent settings are not available for modification directly on a host +object. This requires you to create an "Icinga Agent" template. You +could name it exactly like that; it's important to use meaningful names +for your templates. + + + +As long as you're not using Satellite nodes, a single Agent zone is all +you need. Otherwise, you should create one Agent template per satellite +zone. If you want to move an Agent to a specific zone, just assign it +the correct template and you're all done. + + +Usage +----- + +Well, create a host, choose an Agent template, that's it: + + + +Once you import the "Icinga Agent" template, you'll see a new "Agent" tab. +It tries to assist you with the initial Agent setup by showing a sample +config: + + + + + +The preview shows that the Icinga Director would deploy multiple objects +for your newly created host: + + + + +Create Agent-based services +--------------------------- + +Similar game for services that should run on your Agents. First, create a +template with a meaningful name. Then, define that Services inheriting from +this template should run on your Agents. + + + +Please do not set a cluster zone, as this would rarely be necessary. +Agent-based services will always be deployed to their Agent's zone by +default. All you need to do now for services that should be executed +on your Agents is importing that template: + + + +Config preview shows that everything works as expected: + + + +It's perfectly valid to assign services to host templates. Look how the +generated config differs now: + + + +While services added to a host template are implicitly rendered as +assign rules, you could of course also use your `Agent-based service` +template in custom apply rules: + + + + + diff --git a/doc/30-Configuration-Baskets.md b/doc/30-Configuration-Baskets.md new file mode 100644 index 0000000..f077a74 --- /dev/null +++ b/doc/30-Configuration-Baskets.md @@ -0,0 +1,92 @@ +<a id="baskets"></a> Importing Director Configurations with Baskets +=================================================================== + +Director already takes care of importing configurations for monitored objects. This same concept +is also useful for Director's internal configuration. *Configuration Baskets* allow you to +export, import, share and restore all or parts of your Icinga Director configuration, as many +times as you like. + +Configuration baskets can save or restore the configurations for almost all internal Director +objects, such as host groups, host templates, service sets, commands, notifications, sync +rules, and much more. Because configuration baskets are supported directly in Director, all +customizations included in your Director configuration are imported and exported properly. +Each snapshot is a persistent, serialized (JSON) representation of all involved objects at that +moment in time. + +Configuration baskets allow you to: +- Back up (take a snapshot) and restore a Director configuration... + - To be able to restore in case of a misconfiguration you have deployed + - Copy specific objects as a static JSON file to migrate them from testing to production +- Understand problems stemming from your changes with a diff between two configurations +- Share configurations with others, either your entire environment or just specific parts such as commands +- Choose only some elements to snapshot (using a *custom selection*) in a given category such as + a subset of Host Templates + +In addition, you can script some changes with the following command: +``` +# icingacli director basket [options] +``` + + + +Using Configuration Baskets +--------------------------- + +To create or use a configuration basket, select **Icinga Director > Configuration Baskets**. At +the top of the new panel are options to: +- Make a completely new configuration basket with the *Create* action +- Make a new basket by importing a previously saved JSON file with the *Upload* action + +At the bottom you will find the list of existing baskets and the number of snapshots in each. +Selecting a basket will take you to the tabs for editing baskets and for taking snapshots. + + + +### Create a New Configuration Basket + +To create or edit a configuration basket, give it a name, and then select whether each of the +configuration elements should appear in snapshots for that basket. The following choices +are available for each element type: +- **Ignore:** Do not put this element in snapshots (for instance, do not include sync rules). +- **All of them:** Put all items of this element type in snapshots (for example, all host templates). +- **Custom Selection:** Put only specified items of this element type in a snapshot. You will + have to manually mark each element on the element itself. For instance, if you have marked host + templates for custom selection, then you will have to go to each of the desired host templates + and select the action *Add to Basket*. This will cause those particular host templates to be + included in the next snapshot. + + + +### Uploading and Editing Saved Baskets + +If you or someone else has created a serialized JSON snapshot (see below), you can upload that +basket from disk. Select the *Upload* action, give it a new name, use the file chooser to select +the JSON file, and click on the *Upload* button. The new basket will appear in the list of +configuration baskets. + +Editing a basket is simple: Click on its name in the list of configuration baskets to edit either +the basket name or else whether and how each configuration type will appear in snapshots. + + + +### Managing Snapshots + +From the *Snapshots* panel you can create a new snapshot by clicking on the *Create Snapshot* +button. The new snapshot should immediately appear in the table below, along with a short +summary of the included types (e.g., *2x HostTemplate*) and the time. If no configuration types +were selected for inclusion, the summary for that row will only show a dash instead of types. + +Clicking on a row summary will take you to the *Snapshot* panel for that snapshot, with the +actions +- **Show Basket:** Edit the basket that the snapshot was created from +- **Restore:** Requests the target Director database; clicking on the *Restore* button will begin + the process of restoring from the snapshot. Configuration types that are not in the snapshot + will not be replaced. +- **Download:** Saves the snapshot as a local JSON file. + +followed by its creation date, checksum, and a list of all configured types (or custom +selections). + +For each item in that list, the keywords *unchanged* or *new* will appear to the right. +Clicking on *new* will show the differences between the version in the snapshot and the +current configuration. 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. diff --git a/doc/70-Import-and-Sync.md b/doc/70-Import-and-Sync.md new file mode 100644 index 0000000..a413ab9 --- /dev/null +++ b/doc/70-Import-and-Sync.md @@ -0,0 +1,88 @@ +<a id="Import-and-Sync"></a>Import and Synchronization +====================================================== + +Icinga Director offers very powerful mechanisms when it comes to fetching data +from external data sources. + +The following examples should give you a quick idea of what you might want to +use this feature for. Please note that Import Data Sources are implemented as +hooks in Director. This means that it is absolutely possible and probably very +easy to create custom data sources for whatever kind of data you have. And you +do not need to modify the Director source code for this, you can ship your very +own importer in your very own Icinga Web 2 module. + +Examples +-------- + +### Import Servers from MS Active Directory + +#### Create a new import source + +Importing data from LDAP sources is pretty easy. We use MS Active Directory +as an example source: + + + +You must formerly have configured a corresponding LDAP resource in your Icinga Web. +Then you choose your preferred object class, you might add custom filters, a search +base should always be set. + +The only tricky part here are the chosen Properties. You must know them and you +are required to fill them in, no way around this right now. Also please choose one +column as your key column. + +In case you want to avoid trouble please make this the column that corresponds to +your desired object name for the objects you are going to import. Rows duplicating +this property will be considered erroneous, the Import would fail. + +#### Property modifiers + +Data sources like SQL databases provide very powerful modifiers themselves. With a +handcrafted query you can solve lots of data conversion problems. Sometimes this is +not possible, and some sources (like LDAP) do not even have such features. + +This is where property modifiers jump in to the rescue. Your computer names are +uppercase and you hate this? Use the lowercase modifier: + + + +You want to have the object SID as a custom variable, but the data is stored +binary in your AD? There is a dedicated modifier: + + + +You do not agree with the way Microsoft represents its version numbers? Regular +expressions are able to fix everything: + + + +#### Preview + +A quick look at the preview confirms that we reached a good point, that's the data +we want: + + + +#### Synchronization + +The Import itself just fetches raw data, it does not yet try to modify any of your +Icinga objects. That's what the Sync rules have been designed for. This distinction +has a lot of advantages when it goes to automatic scheduling for various import and +sync jobs. + +When creating a Synchronization rule, you must decide which Icinga objects you want +to work with. You could decide to use the same import source in various rules with +different filters and properties. + + + +For every property you must decide whether and how it should be synchronized. You +can also define custom expressions, combine multiple source fields, set custom +properties based on custom conditions and so on. + + + +Now you are all done and ready to a) launch the Import and b) trigger your synchronization +run. + + diff --git a/doc/70-REST-API.md b/doc/70-REST-API.md new file mode 100644 index 0000000..dd5d266 --- /dev/null +++ b/doc/70-REST-API.md @@ -0,0 +1,684 @@ +<a id="REST-API"></a>The Icinga Director REST API +================================================= + +Introduction +------------ + +Icinga Director has been designed with a REST API in mind. Most URLs you +can access with your browser will also act as valid REST url endpoints. + +Base Headers +------------ +All your requests MUST have a valid accept header. The only acceptable +variant right now is `application/json`, so please always append a header +as follows to your requests: + + Accept: application/json + + +Authentication +-------------- +Please use HTTP authentication and any valid Icinga Web 2 user, granted +enough permissions to accomplish the desired actions. The restrictions +and permissions that have been assigned to web users will also be enforced +for API users. In addition, the permission `director/api` is required for +any API access. + +Versioning +---------- + +There are no version strings so far in the Director URLs. We will try hard +to not break compatibility with future versions. Sure, sooner or later we +also might be forced to introduce some kind of versioning. But who knows? + +As a developer you can trust us to not remove any existing REST url or any +provided property. However, you must always be ready to accept new properties. + +URL scheme and supported methods +-------------------------------- + +We support GET, POST, PUT and DELETE. + +| Method | Meaning | +|--------|---------------------------------------------------------------------| +| GET | Read / fetch data. Not allowed to run operations with the potential | +| | to cause any harm | +| POST | Trigger actions, create or modify objects. Can also be used to | +| | partially modify objects | +| PUT | Creates or replaces objects, cannot be used to modify single object | +| | properties | +| DELETE | Remove a specific object | + +TODO: more examples showing the difference between POST and PUT + +POST director/host + gives 201 on success +GET director/host?name=hostname.example.com +PUT director/host?name=hostname.example.com + gives 200 ok on success and 304 not modified on no change +DELETE director/host?name=hostname.example.com + gives 200 on success + + +First example request with CURL +------------------------------- + +```sh +curl -H 'Accept: application/json' \ + -u 'username:password' \ + 'https://icinga.example.com/icingaweb2/director/host?name=hostname.example.com' +``` + +### CURL helper script + +A script like the following makes it easy to play around with curl: + +```sh +METHOD=$1 +URL=$2 +BODY="$3" +USERNAME="demo" +PASSWORD="***" +test -z "$PASSWORD" || USERNAME="$USERNAME:$PASSWORD" + +test -z "$BODY" && curl -u "$USERNAME" \ + -i https://icingaweb/icingaweb/$URL \ + -H 'Accept: application/json' \ + -X $METHOD + +test -z "$BODY" || curl -u "$USERNAME" \ + -i https://icingaweb/icingaweb/$URL \ + -H 'Accept: application/json' \ + -X $METHOD \ + -d "$BODY" + +echo +``` + +It can be used as follows: + +```sh +director-curl GET director/host?name=localhost + +director-curl POST director/host '{"object_name": "host2", "... }' +``` + + +Should I use HTTPS? +------------------- + +Sure, absolutely, no doubt. There is no, absolutely no reason to NOT use +HTTPS these days. Especially not for a configuration tool allowing you to +configure check commands that are going to be executed on all your servers. + +Icinga Objects +-------------- + +### Special parameters + +| Parameter | Description | +|----------------|-------------------------------------------------------------| +| resolved | Resolve all inherited properties and show a flat object | +| withNull | Retrieve default (null) properties also | +| withServices | Show services attached to a host. `resolved` and `withNull` | +| | are applied for services too | +| allowOverrides | Set variable overrides for virtual Services | +| showStacktrace | Returns the related stack trace, in case an error occurs | + +#### Resolve object properties + +In case you add the `resolved` parameter to your URL, all inherited object +properties will be resolved. Such a URL could look as follows: + + director/host?name=hostname.example.com&resolved + + +#### Retrieve default (null) properties also + +Per default properties with `null` value are skipped when shipping a result. +You can influence this behavior with the `properties` parameter. Just append +`&withNull` to your URL: + + director/host?name=hostname.example.com&withNull + + +#### Fetch host with it's services + +This is what the `withServices` parameter exists: + + director/host?name=hostname.example.com&withServices + + +#### Retrieve only specific properties + +The `properties` parameter also allows you to specify a list of specific +properties. In that case, only the given properties will be returned, even +when they have no (`null`) value: + + director/host?name=hostname.example.com&properties=object_name,address,vars + + +#### Override vars for inherited/applied Services + +Enabling `allowOverrides` allows you to let Director figure out, whether your +modified Custom Variables need to be applied to a specific individual Service, +or whether setting Overrides at Host level is the way to go. + + POST director/service?name=Uptime&host=hostname.example.com&allowOverrices + +```json +{ "vars.uptime_warning": 300 } +``` + +In case `Uptime` is an Apply Rule, calling this without `allowOverrides` will +trigger a 404 response. Please note that when modifying the Host object, the +body for response 200 will show the Host object, as that's the one that has +been modified. + +### Example + +GET director/host?name=pe2015.example.com +```json +{ + "address": "127.0.0.3", + "check_command": null, + "check_interval": null, + "display_name": "pe2015 (example.com)", + "enable_active_checks": null, + "flapping_threshold": null, + "groups": [ ], + "imports": [ + "generic-host" + ], + "retry_interval": null, + "vars": { + "facts": { + "aio_agent_build": "1.2.5", + "aio_agent_version": "1.2.5", + "architecture": "amd64", + "augeas": { + "version": "1.4.0" + }, + ... +} +``` + +director/host?name=pe2015.example.com&resolved +```json +{ + "address": "127.0.0.3", + "check_command": "tom_ping", + "check_interval": "60", + "display_name": "pe2015 (example.com)", + "enable_active_checks": true, + "groups": [ ], + "imports": [ + "generic-host" + ], + "retry_interval": "10", + "vars": { + "facts": { + "aio_agent_build": "1.2.5", + "aio_agent_version": "1.2.5", + "architecture": "amd64", + "augeas": { + "version": "1.4.0" + }, + ... +} +``` + +JSON is pretty-printed per default, at least for PHP >= 5.4 + +Error handling +-------------- + +Director tries hard to return meaningful output and error codes: +``` +HTTP/1.1 400 Bad Request +Server: Apache +Content-Length: 46 +Connection: close +Content-Type: application/json +``` + +```json +{ + "error": "Invalid JSON: Syntax error" +} +``` + +Trigger actions +--------------- +You can of course also use the API to trigger specific actions. Deploying the configuration is as simple as issueing: + + POST director/config/deploy + +More +---- + +Currently we do not handle Last-Modified und ETag headers. This would involve some work, but could be a cool feature. Let us know your ideas! + + +Sample scenario +--------------- + +Let's show you how the REST API works with a couple of practical examples: + +### Create a new host + +``` +POST director/host +``` + +```json +{ + "object_name": "apitest", + "object_type": "object", + "address": "127.0.0.1", + "vars": { + "location": "Berlin" + } +} +``` +#### Response +``` +HTTP/1.1 201 Created +Date: Tue, 01 Mar 2016 04:43:55 GMT +Server: Apache +Content-Length: 140 +Content-Type: application/json +``` + +```json +{ + "address": "127.0.0.1", + "object_name": "apitest", + "object_type": "object", + "vars": { + "location": "Berlin" + } +} +``` + +The most important part of the response is the response code: `201`, a resource has been created. Just for fun, let's fire the same request again. The answer obviously changes: + +``` +HTTP/1.1 500 Internal Server Error +Date: Tue, 01 Mar 2016 04:45:04 GMT +Server: Apache +Content-Length: 60 +Connection: close +Content-Type: application/json +``` + +```json +{ + "error": "Trying to recreate icinga_host (apitest)" +} +``` + +So, let's update this host. To work with existing objects, you must ship their `name` in the URL: + + POST director/host?name=apitest + +```json +{ + "object_name": "apitest", + "object_type": "object", + "address": "127.0.0.1", + "vars": { + "location": "Berlin" + } +} +``` + +Same body, so no change: +``` +HTTP/1.1 304 Not Modified +Date: Tue, 01 Mar 2016 04:45:33 GMT +Server: Apache +``` + +So let's now try to really change something: + + POST director/host?name=apitest + +```json +{"address": "127.0.0.2", "vars.event": "Icinga CAMP" } +``` + +We get status `200`, changes have been applied: + +``` +HTTP/1.1 200 OK +Date: Tue, 01 Mar 2016 04:46:25 GMT +Server: Apache +Content-Length: 172 +Content-Type: application/json +``` + +```json +{ + "address": "127.0.0.2", + "object_name": "apitest", + "object_type": "object", + "vars": { + "location": "Berlin", + "event": "Icinga CAMP" + } +} +``` + +The response always returns the full object on modification. This way you can immediately investigate the merged result. As you can see, `POST` requests only touch the parameters you passed - the rest remains untouched. + +One more example to prove this: + +``` +POST director/host?name=apitest +``` + +```json +{"address": "127.0.0.2", "vars.event": "Icinga CAMP" } +``` + +No modification, you get a `304`. HTTP standards strongly discourage shipping a body in this case: +``` +HTTP/1.1 304 Not Modified +Date: Tue, 01 Mar 2016 04:52:05 GMT +Server: Apache +``` + +As you might have noted, we only changed single properties in the vars dictionary. Now lets override the whole dictionary: + +``` +POST director/host?name=apitest +``` + +```json +{"address": "127.0.0.2", "vars": { "event": [ "Icinga", "Camp" ] } } +``` + +The response shows that this works as expected: + +``` +HTTP/1.1 200 OK +Date: Tue, 01 Mar 2016 04:52:33 GMT +Server: Apache +Content-Length: 181 +Content-Type: application/json +``` + +```json +{ + "address": "127.0.0.2", + "object_name": "apitest", + "object_type": "object", + "vars": { + "event": [ + "Icinga", + "Camp" + ] + } +} +``` + +If merging properties is not what you want, `PUT` comes to the rescue: + + PUT director/host?name=apitest + +``` +{ "vars": { "event": [ "Icinga", "Camp" ] } +``` + +All other properties vanished, all but name and type: +``` +HTTP/1.1 200 OK +Date: Tue, 01 Mar 2016 04:54:33 GMT +Server: Apache +Content-Length: 153 +Content-Type: application/json +``` + +```json +{ + "object_name": "apitest", + "object_type": "object", + "vars": { + "event": [ + "Icinga", + "Camp" + ] + } +} +``` + +Let's put "nothing": + + PUT director/host?name=apitest + +```json +{} +``` + +Works as expected: + +``` +HTTP/1.1 200 OK +Date: Tue, 01 Mar 2016 04:57:35 GMT +Server: Apache +Content-Length: 62 +Content-Type: application/json +``` + +```json +{ + "object_name": "apitest", + "object_type": "object" +} +``` + +Of course, `PUT` also supports `304`, you can check this by sending the same request again. + +Now let's try to cheat: + + KILL director/host?name=apitest + +``` +HTTP/1.1 400 Bad Request +Date: Tue, 01 Mar 2016 04:54:07 GMT +Server: Apache +Content-Length: 43 +Connection: close +Content-Type: application/json +``` + +```json +{ + "error": "Unsupported method KILL" +} +``` + +Ok, no way. So let's use the correct method: + + DELETE director/host?name=apitest + +``` +HTTP/1.1 200 OK +Date: Tue, 01 Mar 2016 05:59:22 GMT +Server: Apache +Content-Length: 109 +Content-Type: application/json +``` + +```json +{ + "imports": [ + "generic-host" + ], + "object_name": "apitest", + "object_type": "object" +} +``` + +### Service Apply Rules + +Please note that Service Apply Rule names are not unique in Icinga 2. They are +not real objects, they are creating other objects in a loop. This makes it +impossible to distinct them by name. Therefore, a dedicated REST API endpoint +`director/serviceapplyrules` ships all Service Apply Rules combined with their +internal ID. This ID can then be used to modify or delete a Rule via +`director/service`. + +### Deployment Status +In case you want to fetch the information about the deployments status, +you can call the following API: + + GET director/config/deployment-status + +``` +HTTP/1.1 200 OK +Date: Wed, 07 Oct 2020 13:14:33 GMT +Server: Apache +Content-Type: application/json +``` + +```json +{ + "active_configuration": { + "stage_name": "b191211d-05cb-4679-842b-c45170b96421", + "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1", + "activity": "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2" + } +} +``` +This throws a 500 in case Icinga isn't reachable. +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: + + GET director/config/deployment-status?config_checksums=617b9cbad9e141cfc3f4cb636ec684bd60073be2, + 617b9cbad9e141cfc3f4cb636ec684bd60073be1&activity_log_checksums=617b9cbad9e141cfc3f4cb636ec684bd60073be1, + 028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2 + +```json +{ + "active_configuration": { + "stage_name": "b191211d-05cb-4679-842b-c45170b96421", + "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1", + "activity": "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2" + }, + "configs": { + "617b9cbad9e141cfc3f4cb636ec684bd60073be2": "deployed", + "617b9cbad9e141cfc3f4cb636ec684bd60073be1": "active" + }, + "activities": { + "617b9cbad9e141cfc3f4cb636ec684bd60073be1": "undeployed", + "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2": "active" + } +} +``` +The list of possible status is: +* `active`: whether this configuration is currently active +* `deployed`: whether this configuration has ever been deployed +* `failed`: whether the deployment of this configuration has failed +* `undeployed`: whether this configuration has been rendered, but not yet deployed +* `unknown`: whether no configurations have been found for this checksum + +### Agent Tickets + +The Director is very helpful when it goes to manage your Icinga Agents. In +case you want to fetch tickets through the API, please do as follows: + + GET director/host/ticket?name=apitest + +``` +HTTP/1.1 200 OK +Date: Thu, 07 Apr 2016 22:19:24 GMT +Server: Apache +Content-Length: 43 +Content-Type: application/json +``` + +```json +"5de9883080e03278039bce57e4fbdbe8fd262c40" +``` + +Please expect an error in case the host does not exist or has not been +configured to be an Icinga Agent. + +### Self Service API + +#### Theory of operation + +Icinga Director offers a Self Service API, allowing new Icinga nodes to register +themselves. No credentials are required, authentication is based on API keys. +There are two types of such keys: + +* Host Template API keys +* Host Object API keys + +Template keys basically grant the permission to: + +* Create a new host based on that template +* Specify name and address properties for that host + +This is a one-time operation and allows one to claim ownership of a specific host. +Now, there are two possible scenarios: + +* The host already exists +* The host is not known to Icinga Director + +In case the host already exists, Director will check whether it's API key matches +the given one. [..] + +#### Request processing for Host registration + +A new node will `POST` to `self-service/register-host`, with two parameters in +the URL: + +* `name`: it's desired object name, usually the FQDN +* `key`: a valid Host Template API key + +In it's body it is allowed to specify a specific set of properties. At the time +of this writing, these are: + +* `display_name` +* `address` +* `address6` + +Director will validate the `key` and load the corresponding *Host Template*. In +case no such is found, the request is rejected. Then it checks whether a *Host* +with the given `name` exists. In case it does, the request is rejected unless: + +* It inherits the loaded *Host Template* +* It already has an API key + +If these conditions match, the request is processed. The following sketch roughly shows the decision tree (AFTER the key has been +validated): + +``` + +-----------------------------+ + +--------------+ | * Validate given properties | + | Host exists? | -- NO --> | * Create new host object |-----------+ + +--------------+ | * Return new Host API key | | + | +-----------------------------+ | + YES | + | | + v +-----------------------------+ | + +----------------------+ | * Validate given properties | | + | Host has an API key? | -- NO --> | * Apply eventual changes |----+ + +----------------------+ | * Return new Host API key | | + | +-----------------------------+ | + YES | + | +-------------------+ + v | + +--------------------+ v + | Reject the request | +---------------------+ + +--------------------+ | Client persists the | + | new Host API key | + +---------------------+ +``` diff --git a/doc/74-Self-Service-API.md b/doc/74-Self-Service-API.md new file mode 100644 index 0000000..897fd72 --- /dev/null +++ b/doc/74-Self-Service-API.md @@ -0,0 +1,49 @@ +<a id="Self-Service-API"></a>Self Service API +============================================= + +Introduction +------------ + +Icinga Director offers a Self Service API, allowing new Hosts running the Icinga +Agent to register themselves in a secure way. + +### Windows Agents + +Windows Agents are the main target audience for this feature. It allows you to +generate a single Powershell Script based on the [Icinga 2 Powershell Module]( +https://github.com/Icinga/icinga2-powershell-module +). You can either use the same script for all of your Windows Hosts or generate +different ones for different kind of systems. + +This installation script could then be shipped with your base images, invoked +remotely via **PowerShell Remoting**, distributed as a module via **Group +Policies** and/or triggered via **Run-Once** (AD Policies). + +### Linux Agents + +At the time of this writing, we do not ship a script with all the functionality +you can find in the Windows Powershell script. Linux and Unix environments are +mostly highly automated these days, and such a magic shell script is often not +what people want. + +Still, you can also benefit from this feature by directly using our [Self Service +REST API](70-REST-API.md). It should be easy to integrate it into +the automation tool of your choice. + +Base Configuration +------------------ + +You have full control over the automation Script generated by the Icinga Director. +Please got to the **Infrastructure Dashboard** and choose the **Self Service API**: + + + +This leads to the Self Service API Settings form. Most settings are self-explaining +and come with detailled inline hints. The most important choice is whether the +script should automatically install the Icinga Agent: + + + +In case you opted for automated installation, more options will pop up: + + diff --git a/doc/75-Background-Daemon.md b/doc/75-Background-Daemon.md new file mode 100644 index 0000000..69cecfc --- /dev/null +++ b/doc/75-Background-Daemon.md @@ -0,0 +1,65 @@ +<a id="Background-Daemon"></a>Background-Daemon +=============================================== + +The Icinga Director Background Daemon is available (and mandatory) since v1.7.0. +It is responsible for various background tasks, including fully automated Import, +Sync & Config Deployment Tasks. + +Daemon Installation +------------------- + +To run the Background Daemon, you need to tell `systemd` about your new service. +First make sure that the system user `icingadirector` exists. In case it doesn't, +please create one: + +```sh +useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /bin/false icingadirector +install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector +``` + +Then copy the provided Unit-File from our [contrib](../contrib/systemd/icinga-director.service) +to `/etc/systemd/system`, enable and start the service: + +```sh +MODULE_PATH=/usr/share/icingaweb2/modules/director +cp "${MODULE_PATH}/contrib/systemd/icinga-director.service" /etc/systemd/system/ +systemctl daemon-reload +``` + +Now your system knows about the Icinga Director Daemon. You should make sure that +it starts automatically each time your system boots: + +```sh +systemctl enable icinga-director.service +``` + +Starting the Daemon +------------------- + +You now can start the Background daemon like any other service on your Linux system: + +```sh +systemctl start icinga-director.service +``` + +Stopping the Daemon +------------------- + +You now can stop the Background daemon like any other service on your Linux system: + +```sh +systemctl stop icinga-director.service +``` + +Getting rid of the old Job Daemon +--------------------------------- + +Before v1.7.0, Icinga Director shipped an optional Job Daemon. This one is no longer +needed and should be removed from your system as follows: + +```sh +systemctl stop director-jobs +systemctl disable director-jobs +rm /etc/systemd/system/director-jobs.service +systemctl daemon-reload +``` diff --git a/doc/79-Jobs.md b/doc/79-Jobs.md new file mode 100644 index 0000000..09ab602 --- /dev/null +++ b/doc/79-Jobs.md @@ -0,0 +1,40 @@ +<a id="Jobs"></a>Jobs +===================== + +The [background daemon](75-Background-Daemon.md) is responsible for running +Jobs accoring our schedule. Director allows you to schedule eventually long- +running tasks so that they can run in the background. + +Currently this includes: + +* Import runs +* Sync runs +* Housekeeping tasks +* Config rendering and deployment + +This component is internally provided as a Hook. This allows other Icinga +Web 2 modules to benefit from the Job Runner by providing their very own Job +implementations. + +Theory of operation +------------------- + +Jobs are configured via the Web frontend. You can create multiple definitions +for the very same Job. Every single job will run with a configurable interval. +Please do not expect this to behave like a scheduler or a cron daemon. Jobs +are currently not executed in parallel. Therefore if one job takes longer, it +might have an influence on the scheduling of other jobs. + +Some of you might want actions like automated config deployment not to be +executed all around the clock. That's why you have the possibility to assign +time periods to your jobs. Choose an Icinga timeperiod, the job will only be +executed within that period. + +Time periods +------------ + +Icinga time periods can get pretty complex. You configure them with Director, +but until now it didn't have the necessity to "understand" them. This of course +changed with Time Period support in our Job Runner. Director will try to fully +"understand" periods in future, but right now it is only capable to interpret +a limited subset of timeperiod range definitions. diff --git a/doc/80-FAQ.md b/doc/80-FAQ.md new file mode 100644 index 0000000..0721b58 --- /dev/null +++ b/doc/80-FAQ.md @@ -0,0 +1,75 @@ +<a id="FAQ"></a>Frequently Asked Questions +========================================== + +I got an exception... +--------------------- + +This section tries to summarize well known pitfalls and their solution. + +### Binary data corruption with ZF 1.12.6 and 1.12.17 + +When deploying your first configuration, you might get this error: + + Refusing to render the configuration, your DB layer corrupts + binary data. You might be affected by Zend Framework bug #655 + +Zend Framework 1.12.16 and 1.12.17 silently [corrupt binary data](https://github.com/zendframework/zf1/issues/655). +This has been [fixed](https://github.com/zendframework/zf1/pull/670) with +[1.12.18](https://github.com/zendframework/zf1/releases/tag/release-1.12.18), +please either upgrade or downgrade to an earlier version. Debian Stable currently +ships 1.12.9, but as they backported the involved erraneous security bug their +version has been affected too. In the meantime they also backported the fix for +the fix, so Debian should no longer show this error. + +When you work on a RedHat-based distribution please follow +[Bug 1328032](https://bugzilla.redhat.com/show_bug.cgi?id=1328032). The new +release reached Fedora EPEL 6 and EPEL 7, so this should no longer be an issue +on related platforms. + +You could also manually fix this issue in `/usr/share/php/Zend/Db/Adapter/Pdo/Abstract.php`. +Search for the `_quote` function and delete the line saying: + +```php +$value = addcslashes($value, "\000\032"); +``` + +Please note that doing so would fix all problems, but re-introduce a potential +security issue affecting the MSSQL and Sqlite adapters. + +### Connection error when setting up the database + +When setting up and validating a database connection for Director in Icinga Web 2, +the following error might occur: + + SQLSTATE[HY000]: General error: 2014 Cannot execute queries while + other unbuffered queries are active. + +This happens with some PHP versions, we have not been able to figure out which ones +and why. However, we found a workaround and and fixed this in Icinga Web 2. Please +upgrade to the latest version, the issue should then be gone. + +You probably didn't notice this error before as in most environments the IDO for +historical reasons isn't configured for UTF-8. + +Connection lost to DB while.... +------------------------------- + +In case you are creating large configs or handling huge imports with the Director +it could happen that the default conservative max package size of your MySQL +server bites you. Raise `max packet size` to a reasonable value, this willi +usually fix this issue. + +Import succeeded but nothing happened +------------------------------------- + +Import and Sync are different tasks, you need to `Run` both of them. This allows +us to combine multiple import sources, even it if some of them are slow or failing +from time to time. It's easy to oversee those links right now, we'll fix this soon. + +My Director doesn't look as good as on your screenshots +------------------------------------------------------- + +There used to be a bug in older Icinga Web 2 versions that broke automagic cache +invalidation. So when updating a module you might be forced to do SHIFT-Reload or +similar in your browser. Please note that proxies in the way between you and +Icinga Web 2 might currently lead to similar issues. diff --git a/doc/82-Changelog.md b/doc/82-Changelog.md new file mode 100644 index 0000000..5867b41 --- /dev/null +++ b/doc/82-Changelog.md @@ -0,0 +1,1202 @@ +<a id="Changelog"></a>Changelog +=============================== + +Please make sure to always read our [Upgrading](05-Upgrading.md) documentation +before switching to a new version. + +v1.10.2 +------- + +This is a minor bugfix release, addressing some Sync-related issues: purge for +objects with uppercase characters now works as expected, automated Sync jobs run +again, and manually triggered Sync has been fixed on PostgreSQL. + +Some UI glitches have been addressed, and a few problems appearing only in +certain conditions - related to Configuration Baskets, our Self Service REST API +and the Activity Log. + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/31?closed=1) + +### UI +* FEATURE: improve Service Set table layout (#2648) +* FIX: modifying single time-period ranges had no effect (#2525) +* FIX: activity log pagination is now on a single line (#2649) + +### Import and Sync +* FIX: triggering Sync manually produced an error on PostgreSQL (#2636) +* FIX: purge stopped working for objects with uppercase characters (#2627) +* FIX: Notification Apply rule is now possible (wasn't since v1.8) (#2142, #2634) +* FIX: nested property access with intermediate NULL values now gives NULL (#2474, #2584) +* FIX: automated Sync jobs stopped working (#2633) + +### Configuration Baskets +* FEATURE: more details shown in error messages related to invalid characters (#2646) +* FIX: snapshots for Baskets containing Baskets failed since v1.10 (#2644) + +### REST API +* FIX: Self Service API returned invalid JSON on PHP 8.1 (#2614) + +### Internals +* FIX: issue with empty activity log, deprecate outdated method (#2630) + +v1.10.1 +------- + +This is a minor bugfix release, addressing issues with modifying services via +the monitoring module, Sync problems and a copy and paste error in the DB schema, +which caused problems for fresh installations since v1.10. + +Please note that a long-standing issue for our Sync Rules has been fixed: with +"merge" policy, NULL properties have been ignored for quite some time. This has +now been fixed. If in doubt, please **preview** your Sync Rules to make sure, +that they behave as expected. + +This release brings a small schema migration, cleaning up invalid Sync history +entries. If in doubt, please create a [database backup](05-Upgrading.md#backup-first) first. + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/30?closed=1) + +### Import and Sync +* FIX: sync lower-cased all object names since v1.10 (#2608) +* FIX: sync for Datalist entries has been fixed (#2618) +* FIX: Sync now applied NULL values with merge policy (#2623) +* FIX: Sync created Sync History entries for every preview (#2632) +* FIX: "Purge" stopped working for Sync (#2627) + +### UI +* FIX: "Modify" Services via the monitoring module (#2615, #2619) + +### Configuration Baskets +* FIX: restore Import/Sync/Job when exported with v1.10 (#2620) +* FIX: restoring Job with ImportSource or SyncRule (#2528) + +### Database Schema +* FIX: new DB schema failed due to duplicate line in SQL statement (#2609) + +v1.10.0 +------- + +An advanced **Sync Preview** is one of the features I'd love to highlight in +v1.10.0. We have been able to leverage our Configuration Branch support as +an underlying technology for this: + + + +In case you have lots of changes, you can browse all of them - formerly this +hasn't been possible. Also, this now allows you to inspect every single upcoming +change before applying the Sync: + + + +This has been possible based on the code we implemented to support the +[Director Branches](https://icinga.com/docs/icinga-director-branches/latest/) +module. In case you never heard about it, +[here](https://icinga.com/blog/2022/07/21/releasing-icinga-director-branches/) +you can find the related announcement. + +This release also contains a lot of related fixes and new Features. It is now +possible to deal with **Service Sets** in Configuration Branches, the **commit +remark** can be proposed with a merge request, and the Activity Log shows not +only who has merged the change, but also the **original author**. + +Powerful new features have been implemented for those who love to orchestrate +the Director from the outside. Please check our +[CLI](https://github.com/Icinga/icingaweb2-module-director/blob/v1.10.0/doc/60-CLI.md) +and [REST API](https://github.com/Icinga/icingaweb2-module-director/blob/v1.10.0/doc/70-REST-API.md) +documentation for related details, especially look for --with-services (withServices) +and --allow-overrides (allowOverrides). + +CLI now supports **JSON on STDIN**, REST API can request detailed stack traces +in case an error occurs. + +### Breaking Changes +* Module and system dependencies have been raised, [Upgrading](05-Upgrading.md) + and [Installation](02-Installation.md) documentations contain related details + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/27?closed=1) + +### User Interface +* FIX: links from Service Previews (Icinga DSL) to templates (#2554) +* FIX: daemon health visualization on systems w/o /proc filesystem (#2544) + +### Import and Sync +* FIX: Sync now compares keys in a case-insensitive way (#2598, #2419, #1140) +* FIX: Sync now preserves Self Service API keys in override mode (#2590) +* FEATURE: clone a row for nested Dictionary/Hash entries (#2555) +* FEATURE: Sync in "override" mode now preserves Self Service API keys (#2590) +* FEATURE: split a row in multiple ones, based on a Dictionary (#2555) +* FEATURE: it's now possible to sync to a configuration branch (#2552) +* FEATURE: Sync preview now allows to navigate single changes (#2607) + +### Configuration Baskets +* BREAKING: configuration baskets no longer contain originalId (#2549) +* FEATURE: exporting/snapshot-logic has been centralized (#2549) + +### Configuration Branches +* FIX: PostgreSQL now allows for the same object in multiple branches (#2605) +* FEATURE: merge comments can now be proposed (#2604) +* FEATURE: activity log now shows author and committer (#2606) + +### Integrations +* FIX: Monitoring Hooks are no longer provided with disable Director UI (#2597) +* FIX: cleanup for IcingaDbCube (#2484) + +### Kickstart +* FIX: breaking change in ipl/html, affected setups with ro INI files (#2595) +* FEATURE: better explanation for missing DSL bodies fetched from core (#2557) + +### REST API +* FIX: addressing service templates by name has been fixed (#2487) +* FIX: allow for object_name in body only (#2576) +* FIX: notice on PHP 8.1 (#2575) +* FEATURE: Stack traces can now be requested (#2570) +* FEATURE: Hosts can now be exported with their services (#2568) +* FEATURE: "magic" variable overrides are now supported (#2569) + +### CLI +* FIX: config deploy doesn't try to wait in case of no deployment (#2522) +* FIX: renderer now shows full service sets (#2550) +* FEATURE: improved wording for deployment error messages (#2523) +* FEATURE: JSON can now be shipped via STDIN (#1570) +* FEATURE: improved readability for some error messages (#2567) +* FEATURE: allows showing hosts with their services (#2565) +* FEATURE: allow showing resolved Host services (#2571) +* FEATURE: "magic" variable overrides are now supported (#2560) +* FEATURE: error messages are now friendlier (#2567) +* FEATURE: STDIN support for --json is now available (#1570) + +### Activity Log + +* FIX: deleted objects might have been missing related properties (#2559) + +### Deployment Log +* FEATURE: visualization performance has been improved (#2551) + +### Internals + +* FEATURE: there is now a centralized Exporter implementation (#2549) + +1.9.1 +----- + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/28?closed=1) + +### User Interface +* FIX: DataList-backed fields failed to validate (#2475) +* FIX: No Host list limit when adding a single service globally (#2481) +* FIX: Cleared activity log caused exception (#2505, #2506) +* FEATURE: Icinga Web 2.10 dark mode support (#2433) + +### Configuration Baskets +* FIX: failed to export Baskets with Service Sets (#2488) +* FIX: Sync Rule restore from snapshot on name change (#2467) +* FIX: Do not export UUIDs with Service Sets (#2488) + +### CLI +* FEATURE: Allow to define deployment grace period on CLI (#2499) + +### Integrations +* FIX: Cleanup IcingaDbCubeLinks (#2484) + +### DB Schema +* FIX: applying DB Schema migrations failed on PostgreSQL (#2482) + +1.9.0 +----- + +### Breaking Changes +* Module dependencies have been raised, [Upgrading](05-Upgrading.md) and + [Installation](02-Installation.md) documentations contain related details + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/25?closed=1) + +### Import and Sync +* FIX: string property modifiers now preserve NULL values (#2371) +* FIX: "to int" property modifiers now fails for non-string values (#2372) +* FEATURE: introduce 'disable' as your purge action on Sync (#2285) +* FEATURE: there is now a simple "group by" Property Modifier (#2317) + +### Configuration Baskets +* FIX: Notification Apply Rules have not been exported (#2335) +* FIX: Restore now supports the set_if_format switch (#2291) +* FEATURE: it's now possible to purge objects of specific types (#2201) +* FEATURE: exporting Users, User-Templates and -Groups is now possible (#2328) +* FEATURE: Data Field Categories are now supported (#2256) + +### Permissions and Restrictions +* FEATURE: allow using monitoring module permissions (#2304) +* FEATURE: it's now possible to grant (global) access to scheduled downtimes (#2086) + +### Configuration / Templating +* FEATURE: offering choices based on a specific imports is now possible (#1178) + +### User Interface +* FIX: allow switching DB config while connection is failing (#2300) +* FIX: Links to duplicate services in Sets didn't check for deactivation (#2323) +* FIX: SQL error for Data Fields table on PostgreSQL (#2310) +* FIX: SQL error when searching for Data Field Categories (#2367) +* FIX: Icon used for Notifications has been changed (#2455) +* FEATURE: show "deprecated" flag on object attribute inspection (#2312) +* FEATURE: Service Template for single Host services provides auto-completion (#1974) + +### CLI +* FEATURE: config deployment now allows to --wait for an Icinga restart (#2314) + +### Activity log +* FEATURE: Activity log now allows for remarks (addon module required, #2471) + +### Documentation +* FIX: configure the daemon with main setup instructions (#2296, #2320) + +### Internals +* FEATURE: PHP 8.1 is now supported, works once available in Icinga Web (#2435) +* FEATURE: Config Branches have been implemented, leveraged via Hook/Addon (#2376) +* FEATURE: UUIDs have been implemented for most Icinga objects, more to come +* FEATURE: new Deployment Hook, triggers onCollect(ing) Icinga startup info (#2315) + +1.8.1 +----- + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/24?closed=1) + +### User Interface +* FIX: show Override button when all Fields belong to Field Categories (#2303) +* FIX: don't fail when showing a Host overriding multiple inherited groups (#2253) +* FIX: deal with inherited values which are invalid for a select box (#2288) +* FIX: Service Set preview inline Service Template links (#2334) +* FIX: show Services applied with Rules involving applied Hostgroups (#2313) +* FIX: show "deactivated" services as such also for read-only users (#2344) +* FIX: Overrides for Services belonging to Sets on root Host Templates (#2333) +* FIX: show no header tabs for search result in web 2.8+ (#2141) +* FIX: show and link dependencies for web 2.9+ (#2354) + +### Icinga Configuration +* FIX: rare race condition, where generated config might miss some files (#2351) + +### Icinga API +* FIX: use Icinga 2's generate-ticket API, required for v2.13.0 (#2348) + +### Import and Sync +* FIX: Purge didn't remove more than 1000 services at once (#2339) + +### Automation, User Interface +* FIX: error message wording on failing related (or parent) object ref (#2224) + +### REST API +* FIX: creating scheduled downtime via api failed (#1879) + +1.8.0 +----- + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/21?closed=1) + +### User Interface +* FIX: It's now possible to set Endpoint ports > 32767 on PostgreSQL (#928) +* FIX: Group list is no longer prefixed with a comma (#2133) +* FIX: Change wording, avoid black/whitelist (#2134, #2135) +* FIX: Inherited values in sets (arrays) are now shown (#1310) +* FIX: Column layout broke with Web 2.8, has been fixed (#2065) +* FIX: filter suggestion gave wrong values for DataList fields (#1918) +* FIX: clone-related scheduled downtime links have been fixes (#1894) +* FEATURE: Data Fields can now be grouped into categories (#1969) +* FEATURE: Inspect is now available for Packages, Stages and Files (#1995) +* FEATURE: Allow to disable the Director frontend / UI (#2007) +* FEATURE: Endpoints table now shows the object type (e.g. external) (#2050) +* FEATURE: make sure that form label and fields stay close together (#2136) +* FEATURE: show more content, reduce padding (expect on mobile) (#2140) +* FEATURE: location details for non-Director services on "Modify" (#1531) +* FEATURE: Service Set table can now also be searched for Services (#1873) +* FEATURE: Apply-Rule-based Service Sets now show related Hosts (#2081) +* FEATURE: Notification Apply Rules as a DirectorObject DataField (#2199) +* FEATURE: Hint and Error styling has been unified and improved +* FEATURE: Form field rendering for sets now deals with invalid values +* FEATURE: Better descriptions for time-based and other fields (#1897, #1264) +* FEATURE: Daemon tab now gets red instead of yellow when not running (#2238) + +### Translations +* FEATURE: Italian translation is now available (#2080) +* FEATURE: German translation has been refreshed (#2240) + +### CLI +* FEATURE: Deployment Status and related utilities (#2189) + +### Import and Sync +* FEATURE: allow defining update-only Sync Rules (#2059) +* FEATURE: New Property Modifier: ListToObject (#2062) +* FEATURE: Property Modifier: convert binary UUID to HEX presentation (#2138) +* FEATURE: Property Modifier: get Host by Address (#2210) +* FEATURE: Property Modifier: skip duplicates (#2215) +* FEATURE: Property Modifier: trim strings (#1660) +* FEATURE: Property Modifier: negate boolean (#2227) +* FEATURE: Property Modifier Reject/Select: improve usability (#2228) +* FEATURE: Property Modifier: clone rows for every entry of an Array (#2192) +* FEATURE: Property Modifier: unique array values (#2229) +* FEATURE: Property Modifier: allow to rename columns (#2242) +* FEATURE: Import Sources now allows downloading previewed data as JSON (#2096) +* FEATURE: REST API Import now allows custom headers (#2132) +* FEATURE: REST API Import can now extract nested properties (#2132) +* FEATURE: REST API Form remembers passwords without exposing them (#2070) +* FEATURE: UTF8 validation for failed imports gives better error message (#2143) +* FEATURE: ArrayByElementPosition now allows filtering by key name (#1721) +* FEATURE: Use your Director Objects as an Import Source (#2198) +* FEATURE: Property modifiers are now granted access the current Property Name (#2241) +* FIX: Import Source preview now catches all errors +* FIX: Import Source download sends eventual errors as a valid JSON result +* FIX: LDAP Import is now able to paginate limited results (#2019) + +### Configuration Baskets +* FIX: Restoring Import Sources creating Modifiers now works (#2053) +* FEATURE: Support Baskets from Icinca for Windows (#2223) +* FEATURE: It's now possible to use Notification Templates in Baskets +* FEATURE: Snapshot status/diff layout has been improved (#2225) + +### Authentication and Permissions +* FIX: Users restricted to Hostgroups can now use related Templates (#2020, #2101) +* FEATURE: Optionally, restricted users can be allowed to set Groups (#2252) + +### Kickstart +* FEATURE: Friendlier message if object to be removed is still in use (#2206) +* FEATURE: Kickstart now removes obsolete External Commands (#985) + +### Icinga Configuration +* FIX: Correctly render Service Dependencies with Array-style parent hosts (#2088) +* FIX: times.begin and times.end are now rendered separately (#2193) +* REMOVED: magic-apply-for (a hidden deprecated feature) has been removed (#1851) + +### Icinga Agent handling +* FIX: Linux Agent installer now fails when unable to retrieve a certificate +* FEATURE: Linux Agent installer now supports Alpine Linux (#2216) +* FEATURE: Icinga for Windows support (#2147) + +### REST API +* FEATURE: Self Service API ignores empty/missing properties (e.g. no address) +* FEATURE: Search is now also available for the REST API (#1889) +* FEATURE: Deployment Status is now available (#2187) +* FEATURE: UTF-8 characters and slashes are no longer escaped (#2243) + +### Self Service API +* FIX: error handling has been fixed (#1728) + +### Database Support +* FIX: Added UTF8 to valid PostgreSQL encodings (used to be UTF-8) + +### Background Daemon +* FIX: Daemon Logger used to not override the given log level (#2139) +* FEATURE: Daemon: prepare for future reactphp promise versions (#2137) +* FEATURE: Daemon now logs that it is going to reload itself +* FEATURE: Now collects the Deployment status from Icinga (#2045, #1988) + +### Documentation +* FEATURE: We now also mention optional/indirect requirements (#2054, #2220) + +### Internals +* FEATURE: Property Modifiers are now able to clone rows (#2060) +* FEATURE: URL encoding for the Core API has been unified +* FEATURE: PHP 8.0 has been released and is officially supported (#2233) +* REMOVED: dipl has been dropped, we're using ipl/incubator since v1.7 (#2209) +* FIX: typo in DeploymentHook::onSuccessfulDump() has been fixed (#2069) +* FIX: forms now support dbResourceName (#2064) + +1.7.2 +----- + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/23?closed=1) + +### DB Schema +* FIX: Rolling out new installations on MySQL v5.6 fails (#1993) + +### Icinga Configuration +* FIX: Render service\_name for Notifications (#2006) + +### User Interface +* FIX: Cloning Import Sources failed since v1.7.0 (#1997) +* FIX: Switching Director DBs was broken since Web 2.6.3 (#2063) + +### CLI +* FIX: Importing Import Sources failed since v1.7.0 (#2005) + +### Automation +* FIX: Fixing linux install script version check (#2008) +* FIX: Windows Kickstart Script - $GlobalZones was empty (#2002) + +### Documentation +* FIX: Missing single quote in mysql example bug (#2003) + +1.7.1 +----- + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/22?closed=1) + +### User Interface +* FIX: Cloning Sync rules failed since v1.7.0 (#1982) +* FIX: It wasn't possible to multi-select Hosts belonging to a Group (#1973) +* FIX: Removed an un-formatted error in case Icinga is unreachable (#1966) +* FIX: Check for broken configs has been extended to Icinga v2.11.* (#1985) +* FEATURE: Show a warning when detecting a downgraded installation (#1992) + +### Import and Sync +* FIX: Upper- and Lowercase property modifiers are now multibyte/UTF8-safe (#710) + +### Health Check +* FIX: do not complain about no-due newly created jobs (#1994) + +### Background Daemon +* FIX: Daemon didn't report DB state to systemd (#1983) + +1.7.0 +----- +### Breaking Changes +* At least PHP 5.6.3 is now required, Director 1.7.x will refuse to work with + older versions +* New dependencies have been introduced, [Upgrading](05-Upgrading.md) and + [Installation](02-Installation.md) documentations contain related details + +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/18?closed=1) + +### User Interface +* FIX: Service-related links in Activity Log have been corrected (#1377, #1816) +* FIX: Activity Log now works for Service Sets (#1287, #1786, #1816) +* FIX: Assign Filters are no longer mandatory when modifying Service Groups (#930) +* FIX: Object type for CheckCommands has been corrected in config preview (#1799) +* FIX: Import preview in combination with Black/Whitelisting (#1825) +* FIX: Routing/redirection when working with Data Fields (#1847) +* FIX: Auto-suggestion field was positioned wrongly once scrolled down +* FIX: Timezone inconsistencie have been fixed (#1700) +* FIX: Link-like buttons where shortened on Icinga Web 2.7 (#1928) +* FIX: Search in range-filtered Activity Log no longer fails (#1381) +* FEATURE: It's now possible to clone a Service to a different Host (#1796) +* FEATURE: Scheduled Downtimes for "Hosts AND their services" (#1831) +* FEATURE: Auto-suggestion and more for Fields based on Data Lists (#1846) +* FEATURE: Show missing dependencies (#1938) + +### Translations +* FEATURE: German translation has been refreshed (#1951) +* FEATURE: Japanese is now available (#1869) + +### Import and Sync +* FIX: Avoid caching between multiple runs of sync (#1836) +* FIX: Imported Rows Table (history) eventually failed on Icinga Web 2 (#1925) +* FIX: Improved error handling on preview (#1941) +* FEATURE: When fetching invalid data, Import refers erroneous rows (#1741) +* FEATURE: Sync now offers a preview, showing what would happen (#1754) +* FEATURE: ParseURL property modifier has been added (#1746) +* FEATURE: There is a new generic REST API Import Source (#1818) +* FEATURE: Sync now supports Notifications and Dependencies (#1212, #925, #1209) +* FEATURE: Limits (memory, execution time) raised for Import runs via UI (#1954) + +### Configuration Baskets +* FIX: snapshots do no longer fail for deleted elements on snapshot (#1940) +* FEATURE: baskets now support External Commands (#1854) + +### REST API +* FIX: Command Arguments can now be managed via API (#1416) + +### CLI +* FIX: importsource fetch did not apply configured property modifiers (#1819) +* FEATURE: Service Groups are now available on CLI (#1745) +* FEATURE: A new background daemon has been introduced (#1905) + +### Icinga Configuration +* FIX: Allow to render single configuration files larger than 16MB (#1787) +* FIX: Icinga v2.11 version detection for Agent Installation script (#1957) +* DEPRECATED: magic-apply-for (a hidden feature) is now deprecated (#1850) +* FEATURE: It's now possible to define Scheduled Downtimes (#347, #1828) +* FEATURE: Allow to render command definitions as (v1.x-like) strings (#1809) +* FEATURE: host address now allows 255 characters (#1890) +* FEATURE: Director now assists with Services applied to parent Zones (#1634) +* FEATURE: Warn affected setups when affected by a specific core issue (#1958) + +### Documentation +* FIX: Installation instructions have been adjusted to fit MySQL 8 + +### Internals +* FIX: support different timezones with MySQL (#1332, #1840) +* FIX: support importing DSL-based Command Arguments (#1812) +* FEATURE: a new Hook allows to run custom code at deployment time (#1342, #1843) +* FEATURE: there is a new low-level IcingaObjectFormHook (#1841) + +1.6.2 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/20?closed=1) + +### Icinga Configuration +* FIX: rendering for Service Sets on single Hosts has been fixed (#1788, #1789) + +1.6.1 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/19?closed=1) + +### User Interface +* FIX: restoring a basket fails when there is only one configured DB (#1716) +* FIX: creating a new Basket with a "Custom Selection" failed with an error (#1733) +* FIX: some new reserved keywords are now escaped correctly (#1765) +* FIX: correctly render NOT used in apply rules (fixes #1777) +* FIX: Activity Log used to ignore Host filters (#1613) +* FIX: Basket failed to restore depending on PHP version (#1782) +* FIX: Loop detection works again (#1631) +* FIX: Snapshots for Baskets with Dependencies are now possible (#1739) +* FIX: Commands snapshots now carry fields in your Basket (#1747) +* FIX: Cloning services from one Set to another one no longer fails (#1758) +* FIX: Blacklisting a Service from a Set on a Host Template is now possible (#1707) +* FIX: Services from a Set assigned to a single Host can be blacklisted (#1616) +* FEATURE: Add TimePeriod support to Configuration Baskets (#1735) +* FEATURE: RO users could want to see where a configured service originated (#1785) +* FEATURE: introduce director/serviceapplyrules REST API endpoint (#1755) + +### REST API +* FIX: Self Service API now ships optional Service User parameter (#1297) + +### DB Schema +* FIX: it wasn't possible to use the same custom var in multiple notification + definitions on PostgreSQL (#1762) + +### Icinga Configuration +* FIX: escape newly introduced Icinga 2 keywords (#1765) + +1.6.0 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/15?closed=1) + +### User Interface +* FIX: link startup log warning even for non-standard package names (#1633) +* FIX: searching for fields assigned to a template was broken (#1670) +* FIX: changing an argument type from String to DSL didn't work (#1640) +* FIX: incorrect links from template-tree to non-template commands (#1544) +* FIX: drop useless object-type field for Time Periods (#788) +* FIX: clean up naming for some tabs (#1312) +* FIX: "remove" now removes the correct Service Set on a Host (#1619) +* FIX: do not fail when "inspecting" a pending service (#1641) +* FIX: a problem when selecting multiple host has been fixed (#1647) +* FIX: allow to remove renamed Service Sets (#1664) +* FIX: resolved a side-effect triggered by hooked Custom Fields (#1667) +* FIX: config diff URL behavior has been corrected (#1704) +* FEATURE: allow to filter templates by usage (#1339) +* FEATURE: allow to show SQL used for template tables +* FEATURE: allow to defined Service Groups for Set members and for Services + assigned to Host Templates (#619) +* FEATURE: it's now possible to choose another target Service Set when cloning + a member service (#886) +* FEATURE: Configuration Baskets with snapshot/import/export capabilities (#1630) +* FEATURE: Allow to clone a Service from one Set to another one (#886) +* FEATURE: form descriptions are now shown directly below the field, reverting + a change from v1.4.0 (#1510) +* FEATURE: show sub-sets in Config Preview (#1623) +* FEATURE: show live Health-Check in the frontend (#1669) + +### Import and Sync +* FIX: Core Api imports flapping only for 2.8+ (#1652) +* FEATURE: new Property Modifier allows to extract specific Array values (#473) + +### CLI +* FIX: Director Health Check no longer warns about no Imports/Syncs/Jobs (#1607) +* FEATURE: It's now possible to dump data as fetched by an Import Source (#1626) +* FEATURE: CLI implementation for Configuration Basket features (#1630) +* FEATURE: allow to append to or remove from array properties (#1666) + +### Icinga Configuration +* FIX: rendering of disabled objects containing `*/` has been fixed (#1263) +* FEATURE: support for Timeperiod include/exclude (#1639) +* FEATURE: improve legacy v1.x configuration rendering (#1624) + +### Icinga API +* FIX: ship workarounds for issues with specific Icinga 2 versions +* FIX: clean up deployed incomplete stages lost by Icinga (#1696) +* FEATURE: allow to behave differently based on Icinga 2 version (#1695) + +### Icinga Agent handling +* FEATURE: ship latest PowerShell module (#1632) +* FIX: PowerShell module runs in FIPS enforced mode (#1274) + +### DB Schema +* FIX: enforce strict object_name uniqueness on commands (#1496) + +### Documentation +* FEATURE: improve installation docs, fix URLs (#1656, #1655) + + +1.5.2 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/17?closed=1) + +### Configuration rendering +* FIX: Fix compatibility with Icinga v2.6, got broken with v1.5.0 (#1614) + +### REST API +* FIX: No more invalid JSON in some special circumstances (#1314) + +### User Interface +* FIX: Hostgroup assignment cache has been fixed (#1574, #1618) + +### DB Schema +* FIX: missing user/timeperiod constraint. We usually do not touch the schema + in minor versions, this has been cherry-picked by accident. However, don't + worry - the migration has been tested intensively. + +1.5.1 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/16?closed=1) + +### Icinga Configuration +* FIX: Switched Variable-Override related constant names broke the feature (#1601) + +### User Interface +* FIX: Custom Fields attached to a Service Template have not been shown for Apply + Rules whose name matched the Template Name (#1602) + +### Import and Sync +* FIX: There was an issue with specific binary checksums on MySQL (#1556) + +1.5.0 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/11?closed=1) + +### Security Fixes +* FIX: users with `director/audit` permission had the possibility to inject SQL. + Thanks to Boyd Ansems for reporting this. + +### Permissions and Restrictions +* FEATURE: Showing the executed SQL query now requires the `showsql` permission +* FEATURE: Grant access to Service Set in a controlled way +* FIX: do not allow a user to create hosts he wouldn't be allowed to see #1451 +* FIX: Hostgroup-based restrictions worked fine when applied, bug was buggy in + combination with directly assigned or inherited groups (#1464) + +### Icinga Configuration +* FEATURE: Add 'is false (or not set)' condition for apply rules (#1436) +* FEATURE: support flapping settings for Icinga >= 2.8.0 (#330) +* FEATURE: include all itl packages in Linux Agent sample config (#1450) +* FEATURE: it's now possible to blacklist inherited or applied Services on + single hosts (#907) +* FEATURE: timestamped startup log rendering for upcoming Icinga v2.9.0 (#1478) +* FEATURE: allow to switch between multiple Director databases (#1498) +* FEATURE: it's now possible to specify Zones for UserGroups (#1163) +* FEATURE: dependencies are no longer considered experimental + +### User Interface +* FEATURE: Admins have now access to JSON download links in many places +* FEATURE: Users equipped with related permissions can toggle "Show SQL" in the GUI +* FEATURE: A Service Set can now be assigned to multiple hosts at once #1281 +* FEATURE: Commands can now be filtered by usage (#1480) +* FEATURE: Show usage of Commands over templates and objects (#335) +* FEATURE: Allow horizontal size increase of Import Source DB Query field (#299) +* FEATURE: Small UI improvements like #1308 +* FEATURE: Data Lists can be chosen by name in Sync rules (#1048) +* FEATURE: Inspect feature got refactored, also for Services (#264, #689, #1396, #1397) +* FEATURE: The "Modify" hook is now available for Services (#689), regardless + of whether they have been directly assigned, inherited or applied +* FEATURE: Config preview links imports, hosts and commands to related objects (#1521) +* FEATURE: German translation has been refreshed (#1599) +* FEATURE: Apply Rule editor shows suggestions for Data-List vars (#1588) +* FIX: Don't suggest Command templates where Commands are required (#1414) +* FIX: Do not allow to delete Commands being used by other objects (#1443) +* FIX: Show 'Inspect' tab only for Endpoints with an ApiUser (#1293) +* FIX: It's now possible to specify TimePeriods for single Users #944 +* FIX: Redirect after not modifying a Command Argument failed on some RHEL 7 + setups (#1512) +* FIX: click on Service Set titles no longer removes them from their host (#1560) +* FIX: Restoring objects based on compound keys has been fixed (#1597) +* FIX: Linux Agent kickstart script improved and tweaked for Icinga 2.9 (#1596) + +### CLI +* FEATURE: Director Health Check Plugin (#1278) +* FEATURE: Show and trigger Import Sources (#1474) +* FEATURE: Show and trigger Sync Rules ( #1476) + +### Import and Sync +* FIX: Sync is very powerful and allows for actions not available in the GUI. It + however allowed to store invalid single Service Objects with no Host. This is + now illegal, as it never makes any sense +* FIX: Performance boost for "purge" on older MySQL/MariaDB systems (#1475) +* FEATURE: new Property Modifier for IPs formatted as number in Excel files (#1296) +* FEATURE: new Property Modifier to url-encode values +* FEATURE: new Property Modifier: uppercase the first character of each word +* FEATURE: Kickstart Helper now also imports Event Commands (#1389) +* FEATURE: Preserve _override_servicevars on sync, even when replacing vars (#1307) + +### Internals +* FIX: problems related to users working from different time zones have been + fixed (#1270, #1332) +* FEATURE: Html/Attribute now allows boolean properties +* FEATURE: Html/Attribute allows colons in attribute names (required for SVGs) +* FEATURE: Html/Attributes can be prefixed (helps with data-*) +* FEATURE: Html/Img data:-urls are now supported +* FEATURE: ipl has been aligned with the upcoming ipl-html library +* FEATURE: Director now supports multiple Databases, allows to switch between + them and to deploy different Config Packages. Other features based on this + combined with related documentation will follow. + +1.4.3 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/13?closed=1) + +### User Interface +* FIX: Pagination used to be broken for some tables (#1273) + +### Automation +* FIX: API calls changing only object relations and no "real" property resulted + in no change at all (#1315) + +1.4.2 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/13?closed=1) + +### Configuration rendering +* FIX: Caching had an influence on context-specific Custom Variable rendering + when those variables contained macros (#1257) + +### Sync +* FIX: The fix for #1223 caused a regression and broke Sync for objects without + a 'disabled' property (Sets, List members) (#1279) + +1.4.1 +----- +### Fixed issues +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/12?closed=1) + +### Automation +* FIX: A Sync Rule with `merge` policy used to re-enable manually disabled objects, + even when no Sync Property `disabled` has been defined (#1223) +* FIX: Fix SQL error on PostgreSQL when inspecting Template-Choice (#1242) + +### Large environments +* FIX: Director tries to raise it's memory limit for certain memory-intensive + tasks. When granted more (but not infinite) memory however this had the effect + that he self-restricted himself to a lower limit (#1222) + +### User Interface +* FIX: Assignment filters suggested only Host properties, you have been required + to manually type Service property names (#1207) +* FIX: Hostgroups Dashlet has been shown to users with restricted permissions, + clicking it used to throw an error (#1237) + +1.4.0 +----- +### New requirements +* Icinga Director now requires PHP 5.4, support for 5.3 has been dropped +* For best performance we strongly suggest PHP 7 +* When using MySQL, please consider slowly moving to at least version 5.5. One + of our next versions will introduce official Emoji support 😱😱😱! That's not + possible with older MySQL versions. However, 1.4.x still supports 5.1.x + +### Fixed issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/6?closed=1) + +### Dashboard and Dashlets +* Multiple new Dashboards have been introduced, their layout has been optimized +* Dashboards are made aware of newly introduced permissions and try to provide + useful hints + +### GUI, UX and Responsiveness +* Many little improvements related to mobile devices have been applied to + Dashboards, Forms and Tables +* Search has been both improved and simplified. On most tables search spawns + multiple columns, visible and invisible ones. Multiple search terms are + combined in an intuitive way. +* Pagination (and search) has been added to those tables where it was still + missing +* Some form fields referencing related objects are no longer static drop-down + selection elements but offer suggestions as you type. This makes forms faster, + especially in larger environments +* Navigation has been simplified, redirects after form submissions have been + improved, more possibilities to jump to related objects have been added +* Form field description has been moved to the bottom of the screen. Might be + easier to overlook this way, but while the former implementation was great + for people navigating forms with their Keyboard, it was annoying for Mouse + lovers +* Double-Click a Tab to enlarge it to full width +* Action Link bar has been unified, all links should now respect permissions +* All tables showing historic data are now grouped by day +* Property Modifiers, Sync Rules, Import Sources and more objects now offer + description fields. This allows you to explain your colleagues all the magic + going on behind the scenes + +### Object Types +* Service Sets got quite some tweaking and bug fixing +* Groups of all kinds are now able to list their members, even when being + applied based on filters +* Command Argument handling has been improved +* It is now possible to configure Dependencies through the Icinga Director +* Cloning Hosts now allows to also optionally clone their Services and Service + Sets + +### Templates +* The template resolver has been rewritten, is now easier to test, strict and + faster +* Template Tree has been re-written and now also immediately shows whether a + template is in use +* When navigating to a Template you'll notice a new usage summary page showing + you where and how that specific template is being used. Therefor, many tables + are now internally able to filter by inheritance + +### Template Choices +* While Host- and Service-Templates are powerful building blocks, having to choose + from a single long list might become unintuitive as this list starts growing. + That's where Template Choices jump in. They allow you to bundle related Templates + together and offer your users to choose amongst them in a meaningful way. + +### Apply rules +* Various related issues have been addressed +* A new virtual "is true / is set" operator is now available + +### Permissions and Restrictions +* It is now possible to limit access to Hosts belonging to a a list of Hostgroups. + This works also for Hostgroups assigned through Apply Rules. +* Data List entries can be made available based on Roles + +### Data Types +* SQL Query and Data List based Data Fields can now both be offered as Array fields, + so that you can choose among specific options when filling such +* New overview tables give admins a deep look into used Custom Variables, their + distinct values and usage +* Various issues related to Boolean values have been fixed + +### Import and Synchronization +* Many issues have been addressed. Merge behavior, handling of special fields and + data types +* Problems with Import Source deletion on PostgreSQL have been addressed +* New Property Modifiers are available. When importing single Services you might + love the "Combine" modifier +* It is now possible to re-arrange execution order of Property Modifiers and + Sync Properties +* Preview rendering got some improvements +* "Replace" policy on Custom Vars is now always respected +* Using VMware/vSphere/ESX? There is now a new powerful module providing a + dedicated Import Source + +### REST API +* A new Self Service API now allows to completely automate your Icinga Agent + roll-out, especially (but not only) for Microsoft Windows +* List views are now officially available. They are very fast and stream the + result in a memory-efficient way +* Documentation better explains how to deal with various objects, especially + with different types of Services (!!!!!) + +### Internal architecture +* Many base components have been completely replaced and re-written, based on + and early prototype of our upcoming Icinga PHP Library (ipl) + +1.3.2 +----- + +### Fixed issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/10?closed=1) + +### Apply Rules +* Slashes in Apply Rules have not been correctly escaped +* Services applied based on Arrays (contains) did not show up in the Hosts + Services list, and therefor it was not possible to override their vars +* Some magic has been introduced to detect numbers in apply rules - not perfect + yet + +### Host Groups +* It has not been possible to modify Host Groups without defining an apply rule +* Hostgroups have not been sorted +* It is now legal to have `external` HostGroup objects + +### Rendered Config +* Custom Endpoint objects are now rendered to their parent zone +* (Rendering) issues with the `in` operator have been fixed +* You are now allowed to put Notifications into specific Zones + +### Usability and UI +* Selecting multiple hosts at once and deleting them had no effect +* Documentation got some little improvements +* German translation has been refreshed +* Header alignment has been improved +* Escaping issues with the Inspect feature have been addressed + +### Kickstart + +* Kickstart is more robust and now able to deal with renamed Icinga Masters and + more + +### CLI +* It is not possible to list and show Service Sets on the CLI + +### Import and Sync +* Synchronizing Data List entries caused problems +* A new Import Modifier has been added to deal with LConf specialities +* Issues with special characters like spaces used in column names shipped by + Import Sources have been addressed +* A new Property Modifier allows to filter Arrays based on wildcards or regular + expressions +* A new Property Modifier allowing to "Combine multiple properties" has been + introduced. It's main purpose is to provide reliable unique keys when importing + single service objects. +* A new warning hint informs you in case you created a Sync Rule without related + properties +* Synchronization filters failed when built with columns not used in any property + mapping + +### Auditing +* The audit log now also carries IP address and username + +### Generic bug fixes +* Fixed erraneous loop detection under certain (rare) conditions +* Various issues with PHP 5.3 have been fixed +* Combination of multiple table filters might have failed (in very rare conditions) + +1.3.1 +----- + +### Fixed issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/8?closed=1) + +### Service Sets +* Various little issues have been fixed. You can now remove Sets from hosts, + even when being empty. Services from Sets assigned to parents or via apply + rule are now shown for every single host, and their custom vars can be + overridden at a single host level +* Sets assigned to single hosts have been shown, variable overrides have been + offered - but rendering did not include the Director-generated template + necessary to really put them into place. This has been fixed + +### Usability +* A nasty bug hindered fields inherited from Commands from being shown ad a + Service level - works fine right now +* There is now a pagination for Zones +* Multiedit no longer showed custom fields, now it works again as it should + +### Rendering +* Disabling a host now also disables rendering of related objects (Endpoint, + Zone) for hosts using the Icinga Agent + +### REST API +* Ticket creation through the REST API has been broken, is now fixed + +### Performance, Internals +* A data encoding inconsistency slowed down apply rule editing where a lot of + host custom vars exists +* Some internal changes have been made to make parts of the code easier to be + used by other modules + +1.3.0 +----- + +### Fixed issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/7?closed=1) + +### Service Sets +* You are now allowed to create sets of services and assign all of them at + once with an apply rule +* Sets can be assigned to host templates or directly to single hosts + +### Service Variable Overrides +* When switching to a host view's services tab, you'll now not only see its + very own services, but also ones that result from an apply rule +* You can override those services custom field values for every single host +* Same goes for services belonging to Service Sets + +### Apply rules +* A new "contains" operator gives more possibilities when working with arrays +* Service vars are now also offered in the apply rule form wizard + +### Custom Variables and Fields +* Issues with special characters in custom variables have been fixed +* In case mandatory fields should not have been enforced, this should work + fine right now +* Fields can now be shown based on filter rules. Example use case: show a + `Community String` field in case `SNMPv2` has been selected, but show + five other fields for `SNMPv3`. This allows one to build powerful little + wizard-like forms like shown [here](16-Fields-example-SNMP.md) + +### Agents and Satellites +* It is now possible to set Agent and Zone settings on every single host. This + means that you no longer need to provide dedicated Templates for Satellite + nodes +* The proposed Agent Deployment script has been improved for Windows and Linux +* Infrastructure management got a dedicated dashboard +* Kickstart Wizard helps when working with Satellites. This has formerly been + a hidden, now it can be accessed through the Infrastructure dashboard + +### Commands +* Command arguments are now always appended when inheriting a template. This + slightly changes the former behavior, but should mostly be what one would + expect anyways. + +### Testing +* [Testing instructions](93-Testing.md) have been improved +* Running the test suite has been simplified +* While we keep running our own [tests](93-Testing.md) on software platforms, tests + are now also visible on Travis-CI and triggered for all pull requests + +### Compatibility +* We worked around a bug in very old PHP 5.3 versions on CentOS 6 + +### Activity log +* You can now search and filter in the Activity log +* In case you have hundreds of thousands of changes you'll notice that pagination + performance improve a lot +* A quick-filter allows you to see just your very own changes with a single click + +### Deployment +* More performance tweaking took place. 1.2.0 was already very fast, 1.3.0 should + beat it +* Deployment log got better at detecting files and linking them directly from the + log output, in case any error occured + +### Work related to Icinga 1.x +* Deploying to Icinga 1.x is completely unsupported. However, it works and a + lot of effort has been put into this feature, so it should be mentioned here +* Please note that the Icinga Director has not been designed to deploy legacy + 1.x configuration. This is a sponsored feature for a larger migration project + and has therefore been built in a very opinionated way. You shouldn't even + try to use it. And if so, you're on your own. Nobody will help you when + running into trouble + +### Translation +* German translation is now again at 100% + +### REST API +* Issues related to fetching object lists have been fixed + +### Integrations +* We now hook into the [Cube](https://github.com/icinga/icingaweb2-module-cube) + module, this gives one more possibility to benefit from our multi-edit feature +* Icinga Web 2.4 caused some minor issues for 1.2.0. It works, but an upgrade to + Director 1.3.0 is strongly suggested + +1.2.0 +----- + +### Fixed a lot of issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/5?closed=1) + +### Permissions and restrictions +* Permissions are now enforced. Please check your role definitions, permission + names have changed and are now enforced everywhere +* Configuration preview, Inspect action, Deployment and others can be granted + independently + +### Auditing +* Director provides a nice activity log. Now it is also possible to additionally + log to Syslog or File in case you want to archive all actions elsewhere. Access + to the audit log in the Director can be controlled with a new permission + +### Configuration kickstart +* Now imports also existing notification commands +* Kickstart can be re-triggered on demand at any time + +### Performance +* Config rendering got a huge performance boost. In large environments we + managed it to deploy a real-world configuration 5 times as fast as before + +### Import / Sync +* Various improvements have been applied, mostly hidden small features that should + make work easier. Better form field descriptions, more possibilities when it + goes to syncing special fields like "imports" +* Property modifiers can now generate new modified columns at import time +* New property modifiers are available. There is a pretty flexible DNS lookup, you + can cast to Integer or Boolean, JSON decoding and more is offered +* Datalist entries can now be imported and synchronized, this was broken in 1.1 + +### Configuration possibilities +* You can now define assign rules nested as deep as you want, based on all host + and/or service properties +* It is now possible to define "assign for" constructs, looping over hashes or + dictionaries +* Improved Icinga 2 DSL support in commands, implicit support for skip\_key +* More and more developers are contributing code. We therefore simplified the + way to launch our unit tests and provided related documentation +* Other objects can be referred as a dropdown or similar in custom variables + +### GUI and usability +* Form error handling got a lot of tweaking, eventual exceptions are caught in + various places and presented in a readable way +* The deployment button is now easier to find +* Configuration preview has been improved and allows a full config diff even + before deploying the configuration +* Inheritance loops are now shown in a nice way and can be resolved in the GUI +* A new hidden gem is the multiedit functionality. Press SHIFT/CTRL while + selecting multiple hosts and modify imports, custom vars and other properties + for all of them at once +* Errors or warnings in all historic startup logs now link directly to the + related config file at the time being, pointing to the referred line + +### Agent setup +* The Windows kickstart script got some small improvements and now enables all + related ITL commands per default + +### CLI +* You can find a few new commands, with the ability to list or fetch all hosts + at once in various ways being the most prominent one + +### Related modules +* There are now more additional modules implementing Director Hooks. AWS import + for EC2 instances, ELBs and Autoscaling Groups. File import for CSV, JSON, + YAML and XML. We heard from various successful Import source implementations + in custom projects and would love to see more of those being publicly available! + +1.1.0 +----- + +### Fixed a lot of issues and related features +* You can find issues and feature requests related to this release on our + [roadmap](https://github.com/Icinga/icingaweb2-module-director/milestone/4?closed=1) + +### Icinga Agent handling +* A lot of effort has been put into making config deployment easier for + environments with lots of Icinga Agents +* Related bugs have been fixed, the generated configuration should now work fine + in distributed environments +* A customized Powershell Script for automatic Windows Agent setup is provided + +### Apply Rules +* It's now possible to work with apply rules in various places + +### Notifications +* All components required to deploy notifications are now available. ENV for + commands is still missing, however it's pretty easy to work around this + +### Automation +* Job Scheduler and Job Runner have been introduced. Import, Sync, Deploy and + run Housekeeping in the background with full control and feedback in the GUI +* There is a new intelligent `purge` option allowing one to purge only those + objects that vanished at involved Import Sources between multiple Import and + Sync Runs. + +### Data Types +* Booleans, Integers and Arrays are now first-class citizens when dealing with + custom variables diff --git a/doc/91-Want-more.md b/doc/91-Want-more.md new file mode 100644 index 0000000..cc22588 --- /dev/null +++ b/doc/91-Want-more.md @@ -0,0 +1,17 @@ +<a id="Want-more"></a>Want more? +================================ + +Icinga 2 configuration is a full-blown DSL, not just a configuration +format. It provides endless possibilities, the very same thing can +usually be accomplished in various ways. Director tries hard to offer +you as many of those as possible while strictly trying to keep things +simple. + +You are absolutely right if you think that this might not be an easy +task. We do our best to give you as much flexibility as possible. In +case you miss a feature or have a cool idea of what else we could add +please let us know. Just file an issue or a feature request to our +[issue tracker](https://github.com/Icinga/icingaweb2-module-director/issues). + +The Icinga project is and remains Open Source Software and lives from +community ideas and contributions. diff --git a/doc/93-Testing.md b/doc/93-Testing.md new file mode 100644 index 0000000..7d2f8fb --- /dev/null +++ b/doc/93-Testing.md @@ -0,0 +1,304 @@ +<a id="Testing"></a>Running Unit-Tests for the Director +======================================================= + +There are basically multiple ways of running our Unit-Tests. All of them +are explained here. + +Let others do the job +--------------------- + +Well, as there are tests available you might come to the conclusion that +there is probably already someone running them from time to time. So, just +lean back with full trust in our development toolchain and spend your time +elsewhere ;-) Cheers! + +### Tests on Travis-CI + +When pushing to [GitHub](https://github.com/Icinga/icingaweb2-module-director/) +or sending pull requests, Unit-Tests are automatically triggered on +[Travis-CI](https://travis-ci.org/Icinga/icingaweb2-module-director): + +[](https://travis-ci.org/Icinga/icingaweb2-module-director) + +We run our tests against MySQL and PostgreSQL, with PHP versions ranging from +5.3 to 7.1, including nightly builds. + +### Tests for supported Platforms + +As far as we know, Director is currently mostly used on CentOS (or RHEL) +versions 6 and 7, Debian Stable (Jessie) and Ubuntu LTS (Xenial). So we are +running our tests on our own platforms for exactly those systems. All of them +with PostgreSQL, MySQL (or MariaDB). + +This way we reach the mostly used Database and PHP versions: + + + + +Run tests on demand +------------------- + +The easiest variant is to run the tests directly on the system where you +have installed your Director. + +### Requirements + +* Icinga Web 2 configured +* Director module installed +* A dedicated DB resource +* PHPUnit installed + +### Configuration + +You can use your existing database resource or create a dedicated one. This +might be either MySQL or PostgreSQL, you just need to tell the Director the +name of your resource: + +```ini +; /etc/icingaweb2/modules/director/config.ini + +[db] +resource = "Director DB" + +[testing] +db_resource = "Director Test DB" +``` + +### Run your tests + +Just move to your Director module path... + + cd /usr/share/icingaweb2/modules/director + +...tell Director where to find your configuration... + + export ICINGAWEB_CONFIGDIR=/etc/icingaweb2 + +...and finally run the tests: + + phpunit + +Try parameters like `--testdox` or `--verbose` or check the PHPUnit documentation +to get an output that fits your needs. Depending on your parameters the output +might look like this... + +``` +PHPUnit 5.1.3 by Sebastian Bergmann and contributors. + +.................................................S............... 65 / 81 ( 80%) +..S............. 81 / 81 (100%) + +Time: 1.8 seconds, Memory: 10.00Mb + +OK, but incomplete, skipped, or risky tests! +Tests: 81, Assertions: 166, Skipped: 2. +``` + +...or this: + +``` +PHPUnit 5.1.3 by Sebastian Bergmann and contributors. + +s\Icinga\Module\Director\CustomVariable\CustomVariables + [x] Whether special key names + [x] Vars can be unset and set again + [x] Variables to expression + +s\Icinga\Module\Director\IcingaConfig\AssignRenderer + [x] Whether equal match is correctly rendered + [x] Whether wildcards render a match method + [x] Whether a combined filter renders correctly + +s\Icinga\Module\Director\IcingaConfig\ExtensibleSet + [x] No values result in empty set + [x] Values passed to constructor are accepted + [x] Constructor accepts single values + [x] Single values can be blacklisted + [x] Multiple values can be blacklisted + [x] Simple inheritance works fine + [x] We can inherit from multiple parents + [x] Own values override parents + [x] Inherited values can be blacklisted + [x] Inherited values can be extended + [x] Combined definition renders correctly + +s\Icinga\Module\Director\IcingaConfig\IcingaConfigHelper + [x] Whether interval string is correctly parsed + [x] Whether invalid interval string raises exception + [x] Whether an empty value gives null + [x] Whether interval string is correctly rendered + [x] Correctly identifies reserved words + ... + +``` + +The very same output could look as follows when shown by your CI-Tool: + + + +Running with Gitlab-CI +---------------------- + +This chapter assumes that you have Gitlab and Gitlab-CI up and running. Our +`gitlab-ci.yml` file currently supposes you to have shared runners providing +specific tags and the following operating systems, each of them with MySQL and +PostgreSQL installed locally: + +* CentOS 7 +* Debian Stable (Jessie) +* Ubuntu 16.04 LTS (Xenial) + +### Preparing the Gitlab Runners + +The following instructions suppose that you provide runner instances with a very +basic installation of each operating system. We used naked LXC instances immediately +after launching them. + +For all of them, please define the following variables first: + +```sh +# The URL pointing to your Gitlab installation +GITLAB_URL=https://your.gitlab.example.com + +# The registration token for your Gitlab runners +REGISTRATION_TOKEN=iwQs************kLbH7 +``` + +#### CentOS 7 + +```sh +yum makecache +curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | bash + +# Sad workaround for container/chroot issues +sed -i'' 's/repo_gpgcheck=1/repo_gpgcheck=0/' /etc/yum.repos.d/runner_gitlab-ci-multi-runner.repo + +# Package installation +yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm +yum install -y https://packages.icinga.com/epel/7/release/noarch/icinga-rpm-release-7-1.el7.centos.noarch.rpm +yum install -y php-Icinga icingaweb2-common phpunit mariadb-server postgresql-server \ + postgresql-contrib gitlab-ci-multi-runner + +# Initialize the PostgreSQL data directory +postgresql-setup initdb + +# We do not want to use Ident-based auth +sed -ri 's/(all\s+127.0.0.1\/32\s+)ident/\1md5/' /var/lib/pgsql/data/pg_hba.conf + +# Start and enable all services +systemctl enable postgresql +systemctl start postgresql +systemctl enable mariadb +systemctl start mariadb + +# Fix platform-specific encoding issues +echo "UPDATE pg_database SET datistemplate = FALSE WHERE datname = 'template1'" | su - postgres -c psql +echo "DROP DATABASE template1" | su - postgres -c psql +echo "CREATE DATABASE template1 WITH TEMPLATE = template0 ENCODING = 'UNICODE'" | su - postgres -c psql +echo "UPDATE pg_database SET datistemplate = TRUE WHERE datname = 'template1'" | su - postgres -c psql +echo "VACUUM FREEZE" | su - postgres -c psql template1 + +# Grant the gitlab-runner ident-based admin access +su - postgres -c 'createuser -a -d gitlab-runner' + +# Register the runner with your Gitlab installation +gitlab-ci-multi-runner register -n \ + -r "$REGISTRATION_TOKEN" \ + --executor shell \ + -u "$GITLAB_URL" \ + --tag-list centos7,director +``` + +#### CentOS 6 + +``` +yum makecache +curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | bash + +# Package installation +yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm +yum install -y https://packages.icinga.com/epel/6/release/noarch/icinga-rpm-release-6-1.el6.noarch.rpm +yum install -y php-Icinga icingaweb2-common phpunit mysql-server gitlab-ci-multi-runner + +# Start and enable MySQL +/etc/init.d/mysqld start +chkconfig mysqld on + +# No PostgeSQL, 8.4 on CentOS 6 is too old + +# Register the runner with your Gitlab installation +gitlab-ci-multi-runner register -n \ + -r "$REGISTRATION_TOKEN" \ + --executor shell \ + -u "$GITLAB_URL" \ + --tag-list centos6,director +``` + +#### Debian Stable (Jessie) + +```sh +# Package installation +apt-get update -q -q +apt-get install -y -q wget curl +wget -q -O - http://packages.icinga.com/icinga.key | apt-key add - +echo 'deb http://packages.icinga.com/debian icinga-jessie main' > /etc/apt/sources.list.d/icinga.list +curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | bash +apt-get update -q -q +DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -q -y \ + php5-cli phpunit php5-mysql php5-json php5-fpm zend-framework php-icinga php5-pgsql \ + mysql-server postgresql postgresql-client postgresql-contrib-9.4 \ + gitlab-ci-multi-runner + +# Grant the gitlab-runner ident-based admin access +su - postgres -c 'createuser -a -d gitlab-runner' + +# Register the runner with your Gitlab installation +gitlab-ci-multi-runner register -n \ + -r "$REGISTRATION_TOKEN" \ + --executor shell \ + -u "$GITLAB_URL" \ + --tag-list debian,jessie,director +``` + +#### Ubuntu 16.04 LTS (Xenial) + +```sh +# Package installation +apt-get update -q -q +apt-get install -y -q wget curl +wget -q -O - http://packages.icinga.com/icinga.key | apt-key add - +echo 'deb http://packages.icinga.com/ubuntu icinga-xenial main' > /etc/apt/sources.list.d/icinga.list +curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | bash +apt-get update -q -q +DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -q -y \ + php7.0-cli php7.0-mysql php7.0-pgsql php7.0-json php7.0-fpm phpunit zend-framework php-icinga \ + mariadb-server mariadb-client postgresql postgresql-client postgresql-contrib-9.5 \ + gitlab-ci-multi-runner + +# Zend Framework is not in our include_path +ln -sf /usr/share/php/libzend-framework-php/Zend /usr/share/php/ + +# Allow non-root users to use password-less root +mysql -e "UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE User='root'; FLUSH PRIVILEGES;" + +# Grant the gitlab-runner ident-based admin access +su - postgres -c 'createuser -a -d gitlab-runner' + +# Register the runner with your Gitlab installation +gitlab-ci-multi-runner register -n \ + -r "$REGISTRATION_TOKEN" \ + --executor shell \ + -u "$GITLAB_URL" \ + --tag-list ubuntu,xenial,director +``` + +A lot of work, sure. But it gives us a lot of confidence when shipping our +software for various platforms. + + + +### Docker, Docker, Docker... + +Yes, yes, yes. In future we might eventually provide a similar solution based on +Docker images. Working with throw-away containers seems to be overkill here, as +tearing up those containers would waste much more resources than running the tests. diff --git a/doc/screenshot/director/08_import-and-sync/081_director_import_source.png b/doc/screenshot/director/08_import-and-sync/081_director_import_source.png Binary files differnew file mode 100644 index 0000000..66126a5 --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/081_director_import_source.png diff --git a/doc/screenshot/director/08_import-and-sync/082_director_import_modifier_lowercase.png b/doc/screenshot/director/08_import-and-sync/082_director_import_modifier_lowercase.png Binary files differnew file mode 100644 index 0000000..ed8c1aa --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/082_director_import_modifier_lowercase.png diff --git a/doc/screenshot/director/08_import-and-sync/083_director_import_modifier_sid.png b/doc/screenshot/director/08_import-and-sync/083_director_import_modifier_sid.png Binary files differnew file mode 100644 index 0000000..c0dbd71 --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/083_director_import_modifier_sid.png diff --git a/doc/screenshot/director/08_import-and-sync/084_director_import_modifier_regex.png b/doc/screenshot/director/08_import-and-sync/084_director_import_modifier_regex.png Binary files differnew file mode 100644 index 0000000..63a6aec --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/084_director_import_modifier_regex.png diff --git a/doc/screenshot/director/08_import-and-sync/085_director_import_preview.png b/doc/screenshot/director/08_import-and-sync/085_director_import_preview.png Binary files differnew file mode 100644 index 0000000..b5aaa38 --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/085_director_import_preview.png diff --git a/doc/screenshot/director/08_import-and-sync/086_director_sync_rule_ad_hosts.png b/doc/screenshot/director/08_import-and-sync/086_director_sync_rule_ad_hosts.png Binary files differnew file mode 100644 index 0000000..55a7c0e --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/086_director_sync_rule_ad_hosts.png diff --git a/doc/screenshot/director/08_import-and-sync/087_director_sync_properties_ad_host.png b/doc/screenshot/director/08_import-and-sync/087_director_sync_properties_ad_host.png Binary files differnew file mode 100644 index 0000000..50cec5c --- /dev/null +++ b/doc/screenshot/director/08_import-and-sync/087_director_sync_properties_ad_host.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/141_define_datafields.png b/doc/screenshot/director/14_fields-for-interfaces/141_define_datafields.png Binary files differnew file mode 100644 index 0000000..26bc80c --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/141_define_datafields.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/142_add_datafield.png b/doc/screenshot/director/14_fields-for-interfaces/142_add_datafield.png Binary files differnew file mode 100644 index 0000000..42e7d8b --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/142_add_datafield.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/143_add_host_template.png b/doc/screenshot/director/14_fields-for-interfaces/143_add_host_template.png Binary files differnew file mode 100644 index 0000000..4961bb8 --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/143_add_host_template.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/144_add_template_field.png b/doc/screenshot/director/14_fields-for-interfaces/144_add_template_field.png Binary files differnew file mode 100644 index 0000000..8973409 --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/144_add_template_field.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/145_create_host.png b/doc/screenshot/director/14_fields-for-interfaces/145_create_host.png Binary files differnew file mode 100644 index 0000000..ed7b61b --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/145_create_host.png diff --git a/doc/screenshot/director/14_fields-for-interfaces/146_config_preview.png b/doc/screenshot/director/14_fields-for-interfaces/146_config_preview.png Binary files differnew file mode 100644 index 0000000..526b3d9 --- /dev/null +++ b/doc/screenshot/director/14_fields-for-interfaces/146_config_preview.png diff --git a/doc/screenshot/director/15_apply-for-services/151_monitored_services.png b/doc/screenshot/director/15_apply-for-services/151_monitored_services.png Binary files differnew file mode 100644 index 0000000..bbb321d --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/151_monitored_services.png diff --git a/doc/screenshot/director/15_apply-for-services/152_add_service_template.png b/doc/screenshot/director/15_apply-for-services/152_add_service_template.png Binary files differnew file mode 100644 index 0000000..8e3652d --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/152_add_service_template.png diff --git a/doc/screenshot/director/15_apply-for-services/153_add_service_template_field.png b/doc/screenshot/director/15_apply-for-services/153_add_service_template_field.png Binary files differnew file mode 100644 index 0000000..f2677ce --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/153_add_service_template_field.png diff --git a/doc/screenshot/director/15_apply-for-services/154_create_apply_rule.png b/doc/screenshot/director/15_apply-for-services/154_create_apply_rule.png Binary files differnew file mode 100644 index 0000000..3b621b9 --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/154_create_apply_rule.png diff --git a/doc/screenshot/director/15_apply-for-services/155_configure_apply_for.png b/doc/screenshot/director/15_apply-for-services/155_configure_apply_for.png Binary files differnew file mode 100644 index 0000000..b17ce9e --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/155_configure_apply_for.png diff --git a/doc/screenshot/director/15_apply-for-services/156_config_preview.png b/doc/screenshot/director/15_apply-for-services/156_config_preview.png Binary files differnew file mode 100644 index 0000000..c9b20f8 --- /dev/null +++ b/doc/screenshot/director/15_apply-for-services/156_config_preview.png diff --git a/doc/screenshot/director/16_fields_snmp/161_snmp_versions_create_list.png b/doc/screenshot/director/16_fields_snmp/161_snmp_versions_create_list.png Binary files differnew file mode 100644 index 0000000..a0de485 --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/161_snmp_versions_create_list.png diff --git a/doc/screenshot/director/16_fields_snmp/162_snmp_versions_fill_list.png b/doc/screenshot/director/16_fields_snmp/162_snmp_versions_fill_list.png Binary files differnew file mode 100644 index 0000000..6eadd98 --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/162_snmp_versions_fill_list.png diff --git a/doc/screenshot/director/16_fields_snmp/163_snmp_version_create_field.png b/doc/screenshot/director/16_fields_snmp/163_snmp_version_create_field.png Binary files differnew file mode 100644 index 0000000..e0bd71c --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/163_snmp_version_create_field.png diff --git a/doc/screenshot/director/16_fields_snmp/164_snmp_fields_on_template.png b/doc/screenshot/director/16_fields_snmp/164_snmp_fields_on_template.png Binary files differnew file mode 100644 index 0000000..6773c9c --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/164_snmp_fields_on_template.png diff --git a/doc/screenshot/director/16_fields_snmp/165_host_snmp_choose.png b/doc/screenshot/director/16_fields_snmp/165_host_snmp_choose.png Binary files differnew file mode 100644 index 0000000..138b63b --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/165_host_snmp_choose.png diff --git a/doc/screenshot/director/16_fields_snmp/166_host_snmp_v2c.png b/doc/screenshot/director/16_fields_snmp/166_host_snmp_v2c.png Binary files differnew file mode 100644 index 0000000..6a9186a --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/166_host_snmp_v2c.png diff --git a/doc/screenshot/director/16_fields_snmp/167_host_snmp_v3.png b/doc/screenshot/director/16_fields_snmp/167_host_snmp_v3.png Binary files differnew file mode 100644 index 0000000..a64b831 --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/167_host_snmp_v3.png diff --git a/doc/screenshot/director/16_fields_snmp/168_assign_snmp_check.png b/doc/screenshot/director/16_fields_snmp/168_assign_snmp_check.png Binary files differnew file mode 100644 index 0000000..320c7c2 --- /dev/null +++ b/doc/screenshot/director/16_fields_snmp/168_assign_snmp_check.png diff --git a/doc/screenshot/director/24-agents/2401_agent_template.png b/doc/screenshot/director/24-agents/2401_agent_template.png Binary files differnew file mode 100644 index 0000000..28ec8cf --- /dev/null +++ b/doc/screenshot/director/24-agents/2401_agent_template.png diff --git a/doc/screenshot/director/24-agents/2402_create_agent_based_host.png b/doc/screenshot/director/24-agents/2402_create_agent_based_host.png Binary files differnew file mode 100644 index 0000000..2fcd3e4 --- /dev/null +++ b/doc/screenshot/director/24-agents/2402_create_agent_based_host.png diff --git a/doc/screenshot/director/24-agents/2403_show_agent_instructions_1.png b/doc/screenshot/director/24-agents/2403_show_agent_instructions_1.png Binary files differnew file mode 100644 index 0000000..9ccf848 --- /dev/null +++ b/doc/screenshot/director/24-agents/2403_show_agent_instructions_1.png diff --git a/doc/screenshot/director/24-agents/2404_show_agent_instructions_2.png b/doc/screenshot/director/24-agents/2404_show_agent_instructions_2.png Binary files differnew file mode 100644 index 0000000..607bba8 --- /dev/null +++ b/doc/screenshot/director/24-agents/2404_show_agent_instructions_2.png diff --git a/doc/screenshot/director/24-agents/2405_agent_preview.png b/doc/screenshot/director/24-agents/2405_agent_preview.png Binary files differnew file mode 100644 index 0000000..97d9271 --- /dev/null +++ b/doc/screenshot/director/24-agents/2405_agent_preview.png diff --git a/doc/screenshot/director/24-agents/2406_agent_based_service.png b/doc/screenshot/director/24-agents/2406_agent_based_service.png Binary files differnew file mode 100644 index 0000000..bb4a717 --- /dev/null +++ b/doc/screenshot/director/24-agents/2406_agent_based_service.png diff --git a/doc/screenshot/director/24-agents/2407_create_agent_based_load_check.png b/doc/screenshot/director/24-agents/2407_create_agent_based_load_check.png Binary files differnew file mode 100644 index 0000000..8c173c2 --- /dev/null +++ b/doc/screenshot/director/24-agents/2407_create_agent_based_load_check.png diff --git a/doc/screenshot/director/24-agents/2409_agent_based_service_rendered_for_host.png b/doc/screenshot/director/24-agents/2409_agent_based_service_rendered_for_host.png Binary files differnew file mode 100644 index 0000000..53f1e67 --- /dev/null +++ b/doc/screenshot/director/24-agents/2409_agent_based_service_rendered_for_host.png diff --git a/doc/screenshot/director/24-agents/2410_agent_based_service_rendered_for_host_template.png b/doc/screenshot/director/24-agents/2410_agent_based_service_rendered_for_host_template.png Binary files differnew file mode 100644 index 0000000..4d3d1c9 --- /dev/null +++ b/doc/screenshot/director/24-agents/2410_agent_based_service_rendered_for_host_template.png diff --git a/doc/screenshot/director/24-agents/2411_assign_agent_based_service.png b/doc/screenshot/director/24-agents/2411_assign_agent_based_service.png Binary files differnew file mode 100644 index 0000000..f545da5 --- /dev/null +++ b/doc/screenshot/director/24-agents/2411_assign_agent_based_service.png diff --git a/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png b/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png Binary files differnew file mode 100644 index 0000000..e9b54f5 --- /dev/null +++ b/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png diff --git a/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png b/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png Binary files differnew file mode 100644 index 0000000..bbc7559 --- /dev/null +++ b/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png diff --git a/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png b/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png Binary files differnew file mode 100644 index 0000000..b7d3226 --- /dev/null +++ b/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png diff --git a/doc/screenshot/director/93_testing/931_director_testing_duration.png b/doc/screenshot/director/93_testing/931_director_testing_duration.png Binary files differnew file mode 100644 index 0000000..f51adae --- /dev/null +++ b/doc/screenshot/director/93_testing/931_director_testing_duration.png diff --git a/doc/screenshot/director/93_testing/932_director_testing_output_testdox.png b/doc/screenshot/director/93_testing/932_director_testing_output_testdox.png Binary files differnew file mode 100644 index 0000000..48f436c --- /dev/null +++ b/doc/screenshot/director/93_testing/932_director_testing_output_testdox.png diff --git a/doc/screenshot/director/93_testing/933_director_testing_history.png b/doc/screenshot/director/93_testing/933_director_testing_history.png Binary files differnew file mode 100644 index 0000000..884f80a --- /dev/null +++ b/doc/screenshot/director/93_testing/933_director_testing_history.png diff --git a/doc/screenshot/director/readme/director_main_screen.png b/doc/screenshot/director/readme/director_main_screen.png Binary files differnew file mode 100644 index 0000000..2a8e9f2 --- /dev/null +++ b/doc/screenshot/director/readme/director_main_screen.png |
