Set up encrypted Merlin


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

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

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 ( 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:

  1. On master, run the following command:
  2. rsync -a /opt/monitor/op5/merlin/ poller_ip:/opt/monitor/op5/merlin/
  3. On poller, run the following command:
  4. rsync -a /opt/monitor/op5/merlin/ master_ip:/opt/monitor/op5/merlin/

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

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:

  1. Open the Merlin configuration file. By default, this is located in /opt/monitor/op5/merlin/merlin.conf.
  2. 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.
  3. Note: If you specified a different directory when you generated the key pair, then use the directory instead of the default.

  4. 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/
        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/

Restart OP5 Monitor

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

  1. On each node, run the following command:
  2. mon restart
  3. Verify that the encryption has been enabled by running the following command:
  4. 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.