CERMM/wiki>

Deploy

HTTPS and certificates

CERMM serves HTTPS out of the box, on the same port as plain HTTP, with a certificate it makes itself. Agents pin its key and trust nothing else.

CERMM's own certificate

The first time it starts, CERMM makes its own certificate authority and, from it, a server certificate for every name and address the machine answers to. They live in /var/lib/cermm/tls/. The server certificate is reissued when the names or addresses change, or a month before it expires. The server's key never changes.

  • Agents get the server key's SHA-256 in their install line (--pinnedpubkey for curl, --pin for the agent) and keep it. They don't use any certificate authority, so nobody can stand in for the server with a certificate someone else issued.
  • Browsers warn until you trust CERMM's CA. Download it from https://<server>:4800/ca.crt or Settings → Security → Download CERMM's certificate, check its SHA-256 against the one deploy/lxc.sh printed (also in Settings → Security), and add it to your system or browser as a trusted authority.

One port, both protocols

A connection that opens with a TLS handshake is HTTPS. Plain HTTP on the same port only:

  • redirects browsers to HTTPS;
  • tells agents still on plain HTTP to move: a signed instruction with the new address and the key to pin, which the agent checks against the key it already has (agents too old to move are updated first);
  • serves the Windows installer (below).

Sign-in, jobs and enrolling are refused over plain HTTP.

Why Windows installs over plain HTTP

Windows' own TLS (SChannel) and a PowerShell certificate callback both failed against CERMM's certificate ("An unexpected error occurred on a send"). So the Windows line fetches install.ps1 over plain HTTP and runs it only if its SHA-256 matches the one written in the line; the script checks the agent's download the same way. The enroll token never crosses plain HTTP: it's only on the command line. The agent itself then talks HTTPS with the pinned key.

Your own certificate

Put the full chain and its key in the data folder, readable by the cermm user, and restart:

/var/lib/cermm/tls/custom.crt    the certificate and its chain
/var/lib/cermm/tls/custom.key    its private key
systemctl restart cermm

Agents installed after that check it the normal way, against the system's certificate authorities and the host name.

Decide before you add machines. Agents installed with CERMM's own certificate pinned its key, and refuse to talk to a server whose certificate has a different key. If you want a real certificate for browsers after agents are installed, put a reverse proxy in front for browsers instead: agents keep CERMM's own.

Turning HTTPS off

CERMM_TLS=off serves plain HTTP only. Passwords, commands and their output then cross the network readable, and the password vault won't open (it needs HTTPS). Only for testing, or behind a proxy that does HTTPS (CERMM_TRUST_PROXY=1 turns it off for you). CERMM_TLS=on keeps it on even with CERMM_TRUST_PROXY=1.

What it says in the app

  • The sign-in card says how you're connected.
  • Settings → Security shows the certificate, its fingerprint and the names it's for.
  • A device's Agent panel says HTTPS, key pinned or plain HTTP.

CERMM is in development. Something here wrong or out of date? Tell us or fix it.