25. 09. 2018 Benjamin Gröber Development, NetEye, Uncategorized

How to Add/Rename an Icinga2 Satellite

Infrastructures get reorganized, organizations grow and naming conventions change.
Icinga2 nodes can reliably trust each other by following the guidelines for certificate generation and building a dedicated certificate chain.  Certificates rely on hostnames and DNS, which aren’t usually subject to changes, but it does happen sometimes. What then?

First of all, all certificates in NetEye’s Icinga2 Instances must be signed by the same Certificate Authority (CA). You will usually either use your company’s own internal CA, or rely on the CA generated during the setup of your NetEye installation.

Requirements

Lets assume the following scenario:

  • neteye.example.com is the master node with the CA
  • icinga2-sat.example.com is a satellite at our only remote location
  • sat.example.com is the name of the satellite zone

As our business grows, we want to add a second remote location, but the naming conventions above no longer fit our organization.  We then decide on a rule set leading to the following setup:

  • neteye.example.com as Master (unchanged from before)
  • icinga2-sat.foo.example.com is a Satellite at our former remote location
  • icinga2-sat.bar.example.com is a Satellite at our new remote location
  • The zone naming should leave room for extension and as such be called foo.example.com and bar.example.com

Adding a New Satellite

The first step will be adding the new remote satellite to our Icinga infrastructure.  This can be be accomplished by either trivially using the Director Self Service API, or by manually executing the node setup command on any fresh icinga2 installation.

To give you a little insight into the process, I’ll show you the manual approach.  To start, create a Ticket on the master node for signing the certificate.

[root@neteye.example.com] icinga2-master pki ticket \
--cn icinga2-sat.bar.example.com
1636a7ef976eddffdf5997dd2784bec59b590fab

IMPORTANT: Execute the node setup command and all commands related to certificates after changing to the following directory: $ICINGA2_STATE_DIR/lib/icinga2/certs/

#Get Master Cert and save as neteye.example.com.crt
[root@icinga2-sat.bar.example.com] icinga2 pki save-cert \
--host "neteye.example.com" \
--trustedcert neteye.example.com.crt

#Run Node setup
[root@icinga2-sat.bar.example.com] icinga2 node-setup \
--ticket "1636a7ef976eddffdf5997dd2784bec59b590fab" \
--cn "icinga2-sat.bar.example.com" \
--zone "bar.example.com" \
--endpoint "neteye.example.com" \
--master_host "neteye.example.com" \
--trustedcert "./neteye.example.com.crt" \
--accept-commands \
--accept-config

The only thing left to do is to add the new zone bar.example.com and the new Endpoint to the Icinga Infrastructure in the Director.  After the next commit, the master will delegate checks for the new zone to the new Endpoint.

Renaming an Existing Satellite

As in the previous example, let’s execute all steps manually.  First, we need to correct the way the node sees itself.  In the config file constants.conf  we need to adapt the NodeName and ZoneName to match the new naming scheme.

const NodeName = "icinga2-sat.example.com"
const ZoneName = "sat.example.com"

becomes

const NodeName = "icinga2-sat.foo.example.com"
const ZoneName = "foo.example.com"

If the zones.conf  file uses the NodeName and ZoneName variables, you don’t need to do anything else.  Otherwise you should replicate the changes here as well.

Generating a New Certificate

Trying to restart icinga2 now will result in the following error:

Cannot get certificate from cert path: '$ICINGA2_STATE_DIR/lib/icinga2/certs/icinga2-sat.foo.example.com.crt'

The CN of the certificate must match the NodeName, so we need a new key/cert:

[root@icinga2-sat.foo.example.com] icinga2 pki new-cert \
--cn "icinga2-sat.foo.example.com" \
--key "icinga2-sat.foo.example.com.key" \
--cert "icinga2-sat.foo.example.com.crt"

Signing the New Certificate

Icinga2 will now no longer refuse to start. However the master node will complain as follows:

warning/ApiListener: Unexpected certificate common name while connecting to endpoint 'icinga2-sat.example.com': got 'icinga2-sat.foo.example.com'

To solve this, we generate another ticket on the master node, and use it to send a request to the master for signing our new certificates:

[root@neteye.example.com] icinga2-master pki ticket --cn icinga2-sat.foo.example.com
055cb6db4296f1e8c75ecf9f3bd3ed613e191122
[root@icinga2-sat.foo.example.com] icinga2 pki request \
--ticket 055cb6db4296f1e8c75ecf9f3bd3ed613e191122 \
--host "neteye.example.com" \
--key "icinga2-sat.foo.example.com.key" \
--cert icinga2-sat.foo.example.com.crt \
--trustedcert neteye.example.com.crt --ca ca.crt

The only work left to do now is in Director > Infrastructure Settings:
1. Adapt the Endpoint “icinga2-sat.example.com” to be called “icinga2-sat.foo.example.com”
2. Rename the former “sat.example.com” Zone to “foo.example.com”

Afterwards, all remote checks assigned to the zone will migrate and continue to work without further intervention.
Aaaaand we’re done!

information/ApiListener: Applying configuration file update for path '/neteye/local/icinga2/data/lib/icinga2/api/zones/foo.example.com'

 

Benjamin Gröber

Benjamin Gröber

R&D Software Architect at Wuerth Phoenix
Hi, my name is Benjamin and I'm Software Architect in the System Integration Research & Development Team at Wuerth Phoenix. I discovered my passion for Computers and Technology when I got my first PC shortly after my 7th birthday in 1999. Using computers and playing with them soon got boring and so, just a few years later, I taught myself Visual Basic and entered the world of Software Development. Since then I loved trying to keep up with the short lived, fast evolving IT world and exploring new technologies, eventually putting them to good use. Lately I'm investing my free time in the relatively new languages Go and Rust.

Author

Benjamin Gröber

Hi, my name is Benjamin and I'm Software Architect in the System Integration Research & Development Team at Wuerth Phoenix. I discovered my passion for Computers and Technology when I got my first PC shortly after my 7th birthday in 1999. Using computers and playing with them soon got boring and so, just a few years later, I taught myself Visual Basic and entered the world of Software Development. Since then I loved trying to keep up with the short lived, fast evolving IT world and exploring new technologies, eventually putting them to good use. Lately I'm investing my free time in the relatively new languages Go and Rust.

Leave a Reply

Your email address will not be published. Required fields are marked *

Archive