Set up encrypted Merlin

Overview

You can opt to configure Merlin to encrypt the packets sent over the Merlin port. This is useful if different OP5 Monitor nodes need to communicate over the internet, for example, if you have a remote poller.

For nodes which are placed within the same secure local network, encryption is often unnecessary and introduces an avoidable performance penalty.

This topic walks you through setting up an encrypted Merlin connection.

Encryption details

Merlin uses public key encryption, which requires setup of both a private and public key for each node:

Key agreement protocol: ECDH
Encryption: XSalsa20
Authentication: Poly1305 MAC

Generate and copy keys

Generate a key pair

To set up encryption, you must first generate a key pair on every node involved in the encrypted communication.

To generate a key pair, run the following command:

mon merlinkey generate

This command generates two files:

key.priv
key.pub

By default, the key pair is saved in /opt/monitor/op5/merlin.

Warning: The private key (key.priv) must never be shared.

Generate a key pair in a specific directory

To change the directory where the key pair is saved, add --path=<file path> to the command when you generate a key pair. For example:

mon merlinkey generate --path=/preferred/file/path

Copy the public key

When the keys have been created, copy the public key (key.pub) to the relevant servers. You can use the rsync command for this.

Example — one master and one poller

In a setup where you have one master and one poller, do the following:

On master, run the following command:

rsync -a /opt/monitor/op5/merlin/key.pub poller_ip:/opt/monitor/op5/merlin/master.pub

On poller, run the following command:

rsync -a /opt/monitor/op5/merlin/key.pub master_ip:/opt/monitor/op5/merlin/poller.pub

Example — Slim Poller

In the above example, the master public key is pushed from the master to the poller. In some situations, you may need to synchronise keys by initialising the transfer from the poller, such as when using the Slim Poller, or when you have a passive poller setup where you cannot SSH from the master to the poller.

In these cases, copy the master public key to the poller. On the poller, run the following command:

rsync -a  master_ip:/opt/monitor/op5/merlin/key.pub /opt/monitor/op5/merlin/master.pub

Change Merlin configuration

After you generate the key pairs and copy the public keys, you need to configure Merlin to use them. You need to do the following for each node:

Open the Merlin configuration file. By default, this is located in /opt/monitor/op5/merlin/merlin.conf.
To specify the location of the private key, add the top-level setting, ipc_privatekey = /opt/monitor/op5/merlin/key.priv. You can add this directly after the ipc_socket line.

Note: If you specified a different directory when you generated the key pair, then use the directory instead of the default.

At the end of the Merlin configuration file, you will find the configuration for every node. In each node definition, add the following settings:
- encrypted = 1 to enable encryption on the node
- publickey =<location of the node public key> to locate the copy of the public key from the node

Example — one master and one poller

On master, the Merlin configuration would have the following lines:

...
ipc_socket = /var/lib/merlin/ipc.sock;
ipc_privatekey = /opt/monitor/op5/merlin/key.priv;

log_level = info;
...
poller poller {
        address = IP_ADDR
        port = 15551
        encrypted = 1
        publickey = /opt/monitor/op5/merlin/poller.pub
        hostgroup = pollergroup
}

On poller, the Merlin configuration would have the following lines:

...
ipc_socket = /var/lib/merlin/ipc.sock;
ipc_privatekey = /opt/monitor/op5/merlin/key.priv;

log_level = info;
...
master master {
        address = IP_ADDR
        port = 15551
        encrypted = 1
        publickey = /opt/monitor/op5/merlin/master.pub
}

Restart OP5 Monitor

After you have made the configuration changes on all relevant nodes, restart OP5 Monitor on each of the relevant nodes.

On each node, run the following command:

mon restart

Verify that the encryption has been enabled by running the following command:

mon node status

Look for the encryption status at the end of the first line for each node. For example:

#01 0/1:1 poller encryption-poller: ACTIVE - 0.000s latency - (ENCRYPTED)
Uptime: 5h 23m 37s. Connected: 5h 23m 37s. Last alive: 8s ago
Host checks (handled, expired, total) : 3, 0, 3 (66.67% : 50.00%)
Service checks (handled, expired, total): 9, 0, 9 (66.67% : 11.76%)

Success: Merlin is now encrypted.