Skip to content

Installing Icinga Director from Source

These are the instructions for manual Director installations.

Please see the Icinga Web documentation on how to install modules 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 (≥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 (≥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 (≥0.22.0)
    • If you are using Icinga Web <2.9.0, the following modules are also required
  • 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 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:

MODULE_VERSION="1.11.3"
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:

MODULE_VERSION="1.11.3"
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:

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

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 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!