Installation

cerberd ships as a release tarball: one static binary (linux/amd64), a templated systemd unit and an installer. Install it on the hub, then continue with New hub or Migrate from wg-quick / WGDashboard.

Requirements

Hub

• Linux with the kernel WireGuard module (mainline since 5.6)
• iproute2 (ip): cerberd uses it for the link, address, MTU and routes
• systemd (the unit, systemd-sysusers)
• Root, for the install and for cerberd init / cerberd import

RouterOS spokes (only nodes that get direct links)

• RouterOS v7 with WireGuard and REST (7.1+, ideally current stable)
• A limited user for cerberd (group policies read,write,api,rest-api,test)
• www or www-ssl reachable from the hub’s overlay address only

Plain peers (laptops, phones) need nothing beyond a WireGuard client.

Install

Copy cerberd-<version>-linux-amd64.tar.gz and SHA256SUMS to the hub, then as root:

sha256sum -c --ignore-missing SHA256SUMS
tar xzf cerberd-<version>-linux-amd64.tar.gz
cd cerberd-<version>-linux-amd64
./install.sh
cerberd --version

The tarball holds cerberd, install.sh, cerberd@.service, cerberd.sysusers and wg0.yaml.example.

What the installer does

install.sh:

Installs	Where
the binary	/usr/local/bin/cerberd (BINDIR)
the unit cerberd@.service	/etc/systemd/system/ (UNITDIR)
the cerberd system user	/etc/sysusers.d/cerberd.conf, created with systemd-sysusers
the config directory	/etc/cerberd (root:cerberd 0750) with wg0.yaml.example
boot-time module load	/etc/modules-load.d/cerberd.conf (wireguard)

It then loads the wireguard module and runs systemctl daemon-reload. It doesn’t start or enable anything.

Environment variables change the targets: BINDIR (default /usr/local/bin), UNITDIR (/etc/systemd/system), and DESTDIR to only stage the files under another root, e.g. for packaging:

BINDIR=/usr/bin ./install.sh

The unit runs cerberd as the cerberd user with only CAP_NET_ADMIN and a hardened sandbox. It exits with code 78 on setup errors (missing or invalid config, no database, hub key mismatch) and systemd doesn’t restart it then.

RouterOS password

If cerberd will drive routers, store the REST password where the config points (routeros.defaults.password_file), readable by the cerberd group:

install -m640 -g cerberd /dev/stdin /etc/cerberd/routeros.pass <<< 'router-rest-password'

Prepare a RouterOS spoke

Once per router that should get direct links:

1. /export file=pre-cerber as a backup.

2. A WireGuard interface with the overlay address and a hub peer (persistent-keepalive=10s, allowed-address covering the remote sites and the overlay). cerberd peer config <name> --format routeros prints a script that sets this up.

3. A limited group and user for cerberd: policies read,write,api,rest-api,test.

   Run these commands in the RouterOS terminal as an administrator. Replace router-rest-password with a strong password:

   /user group add name=cerber policy=read,write,api,rest-api,test
   /user add name=cerber group=cerber password="router-rest-password"

   To change the password of an existing cerber user:

   /user set [find where name="cerber"] password="router-rest-password"

   Set routeros.defaults.user to cerber in the hub configuration and store the same password in the password file. Update that file whenever you change the router password. See MikroTik’s user documentation for group policies and password settings.

4. REST (/ip service www or www-ssl) restricted to the hub’s overlay address, and an input rule allowing it from the overlay.

5. On the hub: cerberd peer set <name> --routeros, then cerberd status. The router shows ok <version>, not KEY MISMATCH or unreachable.

Next: New hub or Migrate from wg-quick / WGDashboard.