Manual Icinga2 PKI certificate creation / distribution

The Icinga2 distributed monitoring documentation explains how to set up PKI certificates between different nodes, but assumes that the Slave / Satellite nodes can connect to the Master node and request their certificates.

There are clues in section 6.12.5 which indicate how to create certificates manually, but the documentation does not explain how to create and distribute certificates when the Master node is not contactable by the Satellites / Slaves (for example, you want to have your Master node on a private network, perhaps behind a router doing NAT).

Provided that either the Master can contact the Satellites / Slaves, or the Satellites / Slaves can contact the Master, then Icinga will be happy. Both is okay too.

These instructions show how to do this.

1. On the master machine, make sure Icinga2's api feature is enabled:

   # icinga2 feature enable api
   # /etc/init.d/icinga2 reload

2. On the master, set up a CA (if you have not done this already - if you have, do not repeat the process), either by following the wizard instructions in section 6.7, or by using the command:

   # icinga2 pki new-ca

3. On the master, generate a Certificate Signing Request for the client:

   # icinga2 pki new-cert --cn client --key client.key --csr client.csr

   • Replace all three instances of "client" with the hostname of your client machine (paying attention to any capital letters - the name must match the output of "hostname -f" on the target client).
4. Also on the master machine, sign the Request to generate a Certificate:

   # icinga2 pki sign-csr --csr client.csr --cert client.crt

   • Replace both instances of "client" with the hostname of your client machine.
5. Transfer by whatever means possible the three files from the master:

   /etc/icinga2/pki/ca.crt
   /etc/icinga2/pki/client.key
   /etc/icinga2/pki/client.crt

   to /etc/icinga2/pki on the target client machine.

6. On the client machine, enable the api feature:

   # icinga2 feature enable api

7. On the client machine, allow the machine to accept configs and commands. Add the following two lines to the file /etc/icinga2/features-enabled/api.conf:

   accept_config = true
   accept_commands = true

   These go inside the ApiListener "api" stanza.

8. On the master machine, add the new slave to the file /etc/icinga2/zones.conf

   object Endpoint "client CN as used when generating certificate" { host "client FQDN or IP address" }
   
   object Zone "Slave" {
           endpoints = [ "client CN as used when generating certificate" ]
           parent = "master Zone name"
   }

9. On the client machine, add both machines to /etc/icinga2/zones.conf

   object Endpoint "master CN" { }
   
   object Zone "Master" { endpoints = [ "master CN" ] }
   
   object Endpoint "client CN as used when generating certificate" {
           host = "client FQDN or IP address"
   }
   
   object Zone "Slave" {
           endpoints = [ "client CN as used when generating certificate" ]
           parent = "master Zone name"
   }

   Note that you do not define the Master endpoint's "host" value in the above definition (because the Client cannot connect to the Master).

10. Restart Icinga2 on both machines (the order is not important).

Go up
Return to main index.