How to Add Icinga Director for Icinga 2 and Icinga Web 2
If you’ve been staring at a plain‑vanilla Icinga 2 installation and feel like you’re missing the “smart” part of your monitoring stack, it’s probably time to hook up Director. This guide walks you through getting that plugin in place so you can build hosts, services, and host groups from a web UI instead of wrestling with JSON every time.
Prerequisites: What You Need on Hand
1. Root or sudo access – Icinga’s packages will want to touch system files.
2. A working Icinga 2 install – without the core you’re just adding a layer that sits on top of nothing.
3. MariaDB (or MySQL) running – Director stores its objects in its own database; it can’t run off the same DB as your main config unless you want to get weird.
4. A browser‑friendly web server – Apache or Nginx, already configured for Icinga Web 2.
If any of those are missing, stop and fix them before we keep going. I’ve seen folks try to install Director on a system where MariaDB wasn’t running; the installer would fail mid‑step and leave you with a half‑baked config that broke the whole stack.
Step 1: Install the Director Package
On Debian/Ubuntu:
sudo apt update sudo apt install icinga2-director
On RHEL/CentOS:
sudo yum install icinga2-director
This pulls in a small set of PHP scripts, a MariaDB schema dump, and the web‑UI module. Don’t be fooled into thinking Director is just an “add‑on”; it actually rewrites parts of Icinga Web 2 to expose the new UI.
Why this matters: The package does all the heavy lifting for you – it creates the necessary PHP files, sets permissions, and hooks the web module into Icinga Web 2. Skipping it will force you to hand‑craft every file, and trust me, that’s a recipe for endless configuration drift.
Step 2: Prepare MariaDB
Create a dedicated database user so Director doesn’t stumble over permissions:
CREATE DATABASE icinga_director; GRANT ALL PRIVILEGES ON icinga_director.* TO 'icinga'@'localhost' IDENTIFIED BY 'StrongPassword'; FLUSH PRIVILEGES;
Replace StrongPassword with something that actually feels strong. It’s tempting to use the default password in the installer, but you’ll likely run into “Access denied” errors later if you don’t change it.
Why this matters: Director expects to own all of its tables. If you let it share the main Icinga 2 database, any accidental drop or alter could bring down your entire monitoring setup.
Step 3: Run the Web‑UI Wizard
Navigate in your browser to:
https://<your-server>/icingaweb2/module/director
You’ll see a wizard that asks for the DB credentials you just created. Fill them in and hit “Save”.
If the wizard complains about PHP extensions, install the missing ones (php-mysql, php-xml, etc.) – Director needs them to talk to MariaDB.
Why this matters: The wizard writes the config file under /etc/icingaweb2/modules/director/config.ini. Forgetting this step is a common rookie mistake and will leave you with a silent “module not found” error when you refresh Icinga Web 2.
Step 4: Import the Sample Object Templates
Once Director is live, open the “Configuration” menu inside the Director UI.
Choose Import => Sample Objects. This loads a set of default host and service templates that most people want.
Why this matters: Without these templates you’re basically building from scratch. The sample set includes sane defaults for checks like ping, HTTP, SSH, and even SNMP on popular devices. Skipping it means you’ll spend hours typing JSON by hand.
Step 5: Create Your First Host Group
1. Go to Objects => Host Groups.
2. Click “Add new host group”.
3. Give it a friendly name (“Prod‑Servers”) and a short description.
4. Save.
Why this matters: Host groups are the backbone of Director’s object‑relationship model. A single group can be referenced by multiple services, making your config DRY from day one.
Step 6: Add a Host
1. Objects => Hosts => “Add new host”.
2. Name it (web01.example.com), assign to the group you just made.
3. Set the address (IP or FQDN).
4. Pick a template (“Generic‑Linux‑Host”) – that’s what the wizard imported.
5. Save.
When Director writes this to the database, it also generates the necessary JSON for Icinga 2 and pushes it via icinga2 daemon -R. If you see a “Configuration reloaded” banner in Icinga Web 2, you’re good to go.
Step 7: Attach Services
1. In the host’s detail page click Add service.
2. Pick from the templates (“Ping”, “HTTP”, etc.).
3. Set any overrides (e.g., a longer timeout for a slow server).
4. Save.
Director will push these changes instantly. The best part? If you delete or rename a service, Director handles the cleanup in the database and Icinga 2 config automatically. No more orphaned files to hunt down.
Common Pitfalls & Quick Fixes
| Symptom | Likely Cause | Fix |
|---|---|---|
| “Module not found” after installing package | Permissions on /usr/share/icingaweb2/modules/director wrong | sudo chown -R icingaweb:icingaweb /usr/share/icingaweb2/modules/director |
| Database connection fails in wizard | Wrong password or MySQL host | Double‑check the credentials and make sure MariaDB is listening on localhost. |
| “Configuration reloaded” appears but nothing changes | JSON still stale in Icinga 2 cache | Run sudo icinga2 daemon -R manually to force a reload. |
I’ve seen people hit that exact “module not found” error when they installed Director on CentOS 7 and forgot to run chown on the module directory. A quick systemctl restart httpd usually clears it, but you’ll still need correct ownership.
Is Director Really Worth It?
If your monitoring needs are simple—just a handful of hosts and services—you can get away with plain Icinga 2 JSON files or even the built‑in CLI. Director shines when you have dozens or hundreds of objects that share common templates. It cuts down on duplication, lets non‑admins add new checks via the web UI, and keeps your config tidy.
On the flip side, it adds a database layer and a PHP front end to the stack. If you’re running a minimalistic environment (think Raspberry Pi with a handful of sensors) Director’s extra weight might feel unnecessary. Weigh the pros against your scale before committing.
Final Thoughts
Adding Icinga Director isn’t rocket science, but it does require a few deliberate steps to keep everything in sync. Treat the database as a separate entity, use the wizard to import templates, and let Director do its job of generating clean JSON for you. Once set up, adding or removing hosts is just a click away—no more copy‑paste JSON nightmares.
