I’ve just worked out how to do this by reading a combination of forum post, bug reports and searching GitHub, so I’d thought I’d put together a guide here.
How to use custom Icinga configuration inside the Icinga Director, for situations where the Icinga Director just doesn’t quite meet your needs
In this example, I am adding a new notification template that sets the zone variable - which you can’t do via the Director natively.
Firstly, you’ll need to make sure that you’ve got the Fileshipper module installed - you can find the installation instructions for that here: https://github.com/Icinga/icingaweb2-module-fileshipper/blob/master/doc/02-Installation.md
Create a folder that the user/group that the web server running as can read (not the Icinga daemon as I first did!).
For example, mine is: /etc/icingaweb2/modules/fileshipper/configs/director-custom-configuration/
Then, create a file called directories.ini in /etc/icingaweb2/modules/fileshipper/ with the following contents:
[custom]
source = /etc/icingaweb2/modules/fileshipper/configs/director-custom-configuration
target = zones.d/director-global/custom-rules
The [custom] line just gives the import source a name, it can be anything you like in the brackets, as long as it’s unique within fileshipper.
The source line tells fileshipper where to grab the Icinga configuration files from
The target line tells fileshipper where to copy these files internally when they are being deployed - in this case it’ll pop them in the director-global zone, in a folder called custom-rules.
You next need to actually create your custom configuration to put in the folder - in this case we’re creating a file called notification-zone.conf with the following contents. Obviously you can change this for your particular situation - just make a note of the template name, you’ll need it later.
template Notification "notification-zone" {
zone = host.zone
}
Now we can use the Icinga CLI to create a disabled version of this template, which will mean you’re able to use it inside the Director in imports etc. but it’s disabled because we don’t actually want to use the content of the Director based one we create - we just need the name to exist so the Director doesn’t complain.
icingacli director notification create notification-zone --object_type template --disabled
Replace notification with whatever the template type is and notification-zone with the name of the template.
You could do any arbitrary Icinga object (that the Director supports) if you really wanted to.
It’s time to log on to the Director web interface to use our template - here I’ve gone into Notifications → Notification Templates:
I can then modify my existing templates and import the new notification-zone that I’ve created:
If you have a look at the notification-zone template inside the Director, you’ll see that it is disabled and that it won’t be deployed - this is OK - and exactly what we want, as we want our custom version to be deployed instead!
Finally, you can go to the Activity Log and deploy your configuration:
If you then go to Deployments → Render Config and search, in this case, for custom you should see the file we’ve got fileshipper to deploy:
and then if we click on that - you can see that our custom DSL has been successfully deployed via the Director, and we have been able to use it inside the Director too!
You can find some more examples here: https://github.com/NETWAYS/icinga-examples/tree/main/fileshipper-templates