OP5 Monitor ["OP5 Monitor"]
["OP5 Monitor > Master", "OP5 Monitor > Poller"]["User Guide"]

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

1. On master, run the following command:

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

2. 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:

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.

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

3. 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.

1. On each node, run the following command:

    mon restart

2. 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.

Was this topic helpful?
Your thoughts...
How can we improve this topic?
It did not answer my question(s)
Confusing
Missing screenshot or graphics
Missing technical details
Information is out of date
Your thoughts...
Thank you for your feedback!