Install on your own server

From a new server to a working portal: DNS, firewall, HTTPS, the one install command, first agent, backups and troubleshooting.

This guide takes you from nothing to a working clm.mt server with your first agent and certificate. It assumes you have never seen clm.mt. Follow it in order.

The examples use certs.example.com. Replace it with your own name. Your version numbers, day counts and addresses will differ from the sample output.

1. What you get and how it fits together

clm.mt keeps track of your TLS certificates, renews them and puts them on the systems that use them.

There are two parts:

  • The server. One Linux machine. It holds the database, the web portal and the API. You and your team use it through a browser.
  • Agents. A small program on each system that uses certificates. Each agent connects out to the server, picks up its work, and renews and installs certificates locally. Private keys stay on that system.
Text
  Your browser                Let's Encrypt
       |                           |
       | HTTPS 443                 | HTTP 80 (proves you own the name)
       v                           v
  +--------------------------------------+
  | clm.mt server                        |
  |   HTTPS proxy (ports 80 and 443)     |
  |   clm-server (127.0.0.1:8088 only)   |
  |   database, keys, daily backups      |
  +--------------------------------------+
       ^                ^
       | HTTPS 443      | HTTPS 443
       | agents connect out, nothing connects in to them
  +----------+     +----------+
  | agent    |     | agent    |
  | web01    |     | iis02    |
  +----------+     +----------+

The installer sets up everything on the server: the program, the HTTPS proxy, the daily backup and the agent downloads. You do not install a database or a web server.

2. Before you start

What you received

  • The bundle: clm-server-VERSION-linux-amd64.tar.gz or clm-server-VERSION-linux-arm64.tar.gz. Use the one that matches the server.
  • The license: a file called license.json.

Who you need

PersonWhat they do
Server adminCreates the server and runs the installer with sudo
DNS adminCreates one DNS record
Firewall adminOpens the ports in section 5

How long it takes. The install command takes a few minutes. DNS and firewall requests usually take longer, so send them first.

Checklist to send to IT

Text
clm.mt server request

Server
[ ] Linux server with systemd, amd64 or arm64
[ ] 2 vCPUs, 4 GiB memory, 20 GiB disk
[ ] Static IP address
[ ] sudo access for the person installing
[ ] Python 3, OpenSSL 3.0 or newer, curl, tar installed
[ ] Time sync turned on

DNS
[ ] Name for the server: ______________ (for example certs.example.com)
[ ] A record from that name to the server's IP address
[ ] If Cloudflare: proxy off (grey cloud)

Firewall, inbound to the server
[ ] TCP 443 from everyone who uses the portal, and from every agent
[ ] TCP 80 from the internet (public certificate only)
[ ] TCP 22 from the admin network only

Firewall, outbound from the server
[ ] TCP 443 to the internet
[ ] TCP 587 or 465 to the mail relay, if email is used
[ ] UDP 123 for time

Firewall, outbound from each agent
[ ] TCP 443 to the server name
[ ] TCP 443 to the certificate authority and the DNS provider or acme-dns server

3. Choose the server

Size. 2 vCPUs, 4 GiB of memory and 20 GiB of disk is enough for 400 certificates and 40 agents. The installer refuses a server with under about 2 GiB of memory or under 5 GiB of free disk. The installer also refuses some 2 GiB instances that report less, such as an AWS t4g.small (1834 MiB). Use 4 GiB on those. Backups use most of the disk over time: 14 are kept.

Operating system. Any Linux with systemd on amd64 or arm64, with Python 3, OpenSSL 3.0 or newer, curl, util-linux, GNU tar and coreutils. Ubuntu 24.04 and Debian 12 have been tested. On a minimal image you may need:

Terminal
sudo apt-get install -y python3 openssl curl ca-certificates

Cloud or on-premises. Both work. In a cloud, give the server a fixed public address, such as an AWS Elastic IP. If the address changes, DNS points to the wrong place.

Use a dedicated server. Ports 80 and 443 must be free unless you use your own proxy (section 6).

Use a name, not an IP address. Agents remember the server’s name. If you move to a new server later, you change one DNS record and every agent follows. An IP address also cannot be used with the installer. Pick a public name if you can. If the server can only be reached inside your network, use an internal name and read section 6.

4. DNS

Pick a name, such as certs.example.com. Create this record, pointing at the server’s public address:

TypeNameValueTTL
Acerts203.0.113.10300

Use an AAAA record as well if the server has an IPv6 address that works. A TTL of 300 seconds means a mistake is quick to fix.

Check it from any machine:

Terminal
dig +short certs.example.com

It must print the server’s address. If it prints nothing, wait a few minutes and try again.

Amazon Route 53. Open Hosted zones and choose your domain. Choose Create record. Enter certs as the record name, leave the type as A, enter the address, set TTL to 300 and leave Alias off. Save.

Cloudflare. Open your domain and go to DNS, then Records. Add a record of type A, name certs, with the address as content. Set Proxy status to DNS only, the grey cloud. An orange cloud puts Cloudflare between the certificate authority and your server and the install check fails. Save.

Windows DNS Server. Open DNS Manager, go to Forward Lookup Zones and choose your zone. Right-click and choose New Host (A or AAAA). Enter certs and the address, then choose Add Host.

Other providers. Add an A record with the name and value in the table above.

Internal names and split DNS. If the name only exists inside your network, create the same record on your internal DNS server, pointing at the server’s private address. A public certificate authority cannot reach a private address, so you need your own certificate (section 6). If your public and internal DNS both hold the name, the server itself must see an address that reaches it.

5. Firewall and network

DirectionPortFrom or toWhy
InboundTCP 443Users and agentsPortal, API and agent check-ins
InboundTCP 80InternetProves the name for the certificate, and redirects to HTTPS. Not needed with your own certificate
InboundTCP 22Admin network onlyServer administration
OutboundTCP 443InternetCertificate authorities, DNS providers, cloud APIs
OutboundTCP 587 or 465Mail relaySystem email, if used
OutboundUDP 123Time serversA wrong clock breaks certificates and sign-in
Outbound from agentsTCP 443The server nameAgents never need an inbound port
Outbound from agentsTCP 443Certificate authority, and DNS provider or acme-dns serverAn agent assigned to a certificate orders it itself

The server program listens on 127.0.0.1:8088 only. Never open port 8088.

Cloud security group example (AWS). Add these inbound rules and leave the default rule that allows all outbound traffic:

TypePortSource
HTTPS4430.0.0.0/0
HTTP800.0.0.0/0
SSH22Your admin network

If the server also runs a host firewall:

Terminal
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp

Outbound proxies. The server uses the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables for calls to certificate authorities, DNS providers and targets. Put them in /etc/clm/server.env.

6. Do I need to set up a certificate?

This is about the certificate for the clm.mt portal itself.

Your situationDo you set up a certificate?What to add to the install command
Public name, ports 80 and 443 openNo. It is automatic and renews itselfNothing
Internal name, private CA, or no internetYes. You supply it and you renew it--cert and --key
You have an internal ACME serverNo, it comes from that server--acme-ca
You run your own proxy or load balancer on this serverIt stays on your proxy--own-proxy

Public name. The built-in proxy gets a free certificate from Let’s Encrypt during the install and renews it by itself. Two things must be true: the name points at this server, and the certificate authority can reach port 80 on this server from the internet.

Internal name or private CA. Get a certificate for the name from your CA. You need two PEM files: the full chain and the private key, without a passphrase. Add them to the install command:

Terminal
sudo ./install-server.sh --license /path/license.json --domain certs.example.com \
  --cert /path/fullchain.pem --key /path/key.pem

Port 80 is not used in this case. Nothing renews this certificate for you. You must replace it before it expires. To replace it, run the same command with the new files from the same bundle folder. HTTPS restarts with the new certificate and your data is kept. sudo /opt/clm/clm-ctl status shows how many days are left.

Agents must trust your CA as well. See section 9.

Internal ACME server. Add the directory address. Add the CA file if a private CA signs it:

Terminal
sudo ./install-server.sh --license /path/license.json --domain certs.example.com \
  --acme-ca https://acme.example.com/directory --acme-ca-root /path/ca.pem

Your own proxy. The proxy must run on this server, because the server program only listens on 127.0.0.1:8088. A load balancer elsewhere must go through that local proxy. Add --own-proxy. The installer does not touch your proxy. Set it to forward to 127.0.0.1:8088, keep the Host header and set X-Forwarded-For.

If the server cannot connect to its own public address, the DNS check cannot confirm the name. Add --skip-dns-check.

7. Install

Copy the bundle and license to the server. Then verify the download.

Save the key published on clm.mt in a file called clm-bundle-2026.pem, outside the bundle folder. Compare it with the one below:

Text
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAks2USTukRlSih6px645Zb+7IT4ZlHVUVi0z6nt1jv7w=
-----END PUBLIC KEY-----

Extract the bundle and check it:

Terminal
tar -xzf clm-server-VERSION-linux-ARCH.tar.gz && cd clm-server-VERSION-linux-ARCH
openssl pkeyutl -verify -rawin -pubin -inkey /path/to/clm-bundle-2026.pem -in SHA256SUMS -sigfile SHA256SUMS.sig
sha256sum -c SHA256SUMS

Expected output: Signature Verified Successfully, then one line ending in : OK for each file.

Check the host. This changes nothing:

Terminal
sudo ./install-server.sh --check --license /path/license.json --domain certs.example.com

Expected output:

Text
Host checks passed.

If something is wrong, it lists everything at once:

Text
This host is not ready. Nothing was changed.
  - Port 80 is in use by nginx. Stop that service, or rerun with --own-proxy to keep your own proxy.
  - certs.example.com does not resolve yet. Point an A or AAAA record at this server, then run this again.
  - The license has lapsed. Renew it with clm.mt, then run this again.

Then install:

Terminal
sudo ./install-server.sh --license /path/license.json --domain certs.example.com

Expected output:

Text
Host checks passed.

clm.mt on certs.example.com
  Service:   running
  Version:   1.1.1
  License:   364 days left
  HTTPS:     working, certificate good for 89 days
  Backup:    none yet, the first one runs tonight
  Agents:    0 of 0 online

Next: open this link within 60 minutes and create the first administrator.

  https://certs.example.com/#setup=cst_...

Backups stay on this server. Copying them somewhere safe is your job.

You do not need a second run, an SSH tunnel or a separate Caddy install. Running the command again is safe. It keeps your data and fixes what it can.

8. Create the first administrator

Open the link from the installer in a browser. Fill in your organization, name, email and a password. The password needs at least 10 characters. Choose Create workspace. You are now signed in.

The link works once, for 60 minutes. It is a secret, so do not paste it into tickets or chat.

If it expired or you lost it, get a new one on the server:

Terminal
sudo /opt/clm/clm-ctl setup-token
Text
Open this link within 60 minutes and create the first administrator:

  https://certs.example.com/#setup=cst_...

A new link cancels the old one. If you open the portal without the link, it asks for a Setup code. That code is the part of the link after #setup=.

9. First-day setup

Email. Invitations and password resets need an SMTP relay. Pipe the password in so it stays out of your shell history:

Terminal
printf '%s' 'YOUR-RELAY-PASSWORD' | sudo /opt/clm/clm-ctl smtp-setup --host smtp.example.com \
  --from certificates@example.com --username clm --password-stdin
sudo systemctl restart clm-server.service
sudo /opt/clm/clm-ctl smtp-test you@example.com

Expected output of the first command:

Text
System email settings saved. Restart clm-server.service to apply, then run: clm-ctl smtp-test RECIPIENT

Single sign-on. In the portal, open Settings, then Single sign-on. Add the redirect URI shown there to your identity provider, then fill in the issuer URL, client ID, client secret and allowed email domains, turn on Enabled and save. For Entra ID, also tick the option to trust email addresses the provider doesn't mark verified. People then enter the Organization ID shown on that page and choose Sign in with SSO. Keep your password sign-in as a way back in while you test.

Your first agent. In the portal, open Servers and choose Add server. The portal shows the command for each platform with a one-time token filled in. On Linux it looks like this:

Terminal
curl -fsSL 'https://certs.example.com/install.sh' | sudo env CLM_ENROLL_TOKEN='TOKEN' bash

Expected output:

Text
Downloading clm.mt agent 1.1.1 for linux/arm64
Verified SHA-256 ... and the release signature
Enrolled agent agt_...
Installed clm.mt agent 1.1.1. It now appears in the portal.
Status: systemctl status clm-agent
Logs:   journalctl -u clm-agent -f

The agents come from your own server, not from clm.mt. Within a minute the server status shows it:

Text
  Agents:    1 of 1 online

If you use a private CA, copy your CA file to the agent’s host and pass it twice:

Terminal
curl -fsSL --cacert ca.pem 'https://certs.example.com/install.sh' | sudo env CLM_ENROLL_TOKEN='TOKEN' bash -s -- --ca-file ca.pem

Your first certificate. Use a staging name first. clm.mt proves you own a name with the ACME DNS-01 method, or with HTTP-01 through an agent’s webroot (agent 0.1.19 or later; never for wildcards; the CA must reach port 80, plus 443 if port 80 redirects). For a DNS-01 name you need one of these:

  • A DNS provider account that clm.mt can use.
  • acme-dns delegation, which needs no DNS password. You add one CNAME record once.
  1. In the portal, open Settings, Connections, DNS validation, and add a DNS profile. For acme-dns, save it, choose Configure, register the name, add the CNAME it shows and choose Check DNS.
  2. Under Certificate authorities, choose Connect authority. Enter a name and a contact email, and choose the DNS profile under Domain validation. Vault and OpenBao need no DNS profile: pick the mount and role from the lists the portal fills in.
  3. Make sure the web server already has a TLS site that uses the certificate paths you will enter. A temporary self-signed certificate at those paths is fine.
  4. Open Certificates, choose Manage certificate, keep the recipe for your server, then enter the domain, the agent, the certificate paths and the address to check, such as app.example.com:443. Choose Start automation.
  5. Confirm the status is Healthy and the address serves the new certificate.
  6. Assign an owner and test notifications.

10. Backups

What is backed up. Every night at midnight, a timer writes an archive to /var/lib/clm/backups and keeps the last 14. Each archive holds the database, the agent releases, the master key and the signing key. Here is what one contains:

Text
clm.db
releases/1.1.1/linux/amd64
releases/1.1.1/linux/arm64
releases/1.1.1/windows/amd64
releases/1.1.1/windows/arm64
master.key
release-signing.key
manifest.json

A backup does not hold the license, the server settings, the HTTPS settings or your DNS and firewall rules. The server gets a new certificate by itself.

Off-host copies are your job. A backup on the same server is lost with the server. Copy the archives somewhere else on a schedule, encrypted, with access limited. The archives hold keys, so treat them like the server.

The master key. The file /var/lib/clm/data/master.key encrypts every secret the server stores: CA and DNS credentials, target credentials and authenticator seeds. Keep a copy in a password manager or safe, apart from the backups. If you lose the key and every copy, the database, certificates and users survive, but every stored credential stops working. You must enter them all again and everyone must set up their authenticator again. Nobody can recover them, including clm.mt. The server refuses to start without the key if accounts exist.

Test a restore. Do this on a spare server, not on the one in use. Install as in section 7, ignore the link, then restore:

Terminal
sudo /opt/clm/clm-ctl restore /path/to/backup.tar.gz --replace

Expected output, shortened:

Text
Restored 7 files from a 1.1.1 backup (schema 34, taken 2026-11-02T03:34:38Z).
Verified 0 encrypted secrets and 0 hosted private keys.

The data this replaced is kept in /var/lib/clm/replaced-20261102T033447. Delete it only when you no longer need it.
Restored and running. Before you finish:

Sign in and check your certificates are there. --replace keeps the old data, so nothing is lost if you run it by mistake.

11. Running the server

Daily check.

Terminal
sudo /opt/clm/clm-ctl status

Monitoring. https://certs.example.com/healthz returns {"status":"ok","version":"1.1.1"} and /readyz returns {"status":"ready"}. For metrics, set CLM_METRICS_TOKEN to at least 32 characters in /etc/clm/server.env, restart the server and scrape /metrics with that bearer token. Alert on these: clm_license_days_left under 30, clm_agents{state="offline"}, backup age and disk space.

License renewal. Portal banners and notifications start 30 days before the end date and repeat at 7 days. To install a new license, run the install command again with the new file. It restarts the server briefly and keeps the old file as /etc/clm/license.json.previous.

What happens at expiry:

WhenWhat happens
Up to 30 days after the end dateNothing is refused. A banner shows when the grace period ends
After those 30 daysNew agents and new certificates are refused until you install a renewed license
AlwaysExisting certificates keep renewing and deploying

Upgrades. Nothing updates the server by itself. Admins see a notice in the portal when a release exists. Get the new bundle, then run:

Terminal
sudo /opt/clm/clm-upgrade.sh /path/to/clm-server-NEWVERSION-linux-ARCH.tar.gz

It lists its checks and ends with:

Text
Upgraded to 1.2.0; previous binary and data snapshot retained in /opt/clm and /var/lib/clm-upgrade/rollback

It takes a backup first. If the new version fails its health checks, it restores the old version and data by itself. Agents then update themselves from your server.

To roll back by hand after a successful upgrade, stop the server, keep a copy of /var/lib/clm/data, put back /var/lib/clm-upgrade/rollback as /var/lib/clm/data and /opt/clm/clm-server.previous as /opt/clm/clm-server, then start the server. You lose changes made since the upgrade.

Move to a new server.

  1. Stop the old server: sudo systemctl stop clm-server.service clm-caddy.service.
  2. Point DNS at the new server. Agents wait and retry.
  3. Install on the new server as in section 7, with the same name. Ignore the link.
  4. Copy the newest backup across and restore it with the command in section 10.
  5. Run clm-ctl smtp-setup again.
  6. In the portal, open Servers and check that each agent shows a recent last-seen time.

If agents were set up with an IP address instead of a name, they cannot follow the move.

Uninstall. See what would happen first:

Terminal
sudo /opt/clm/clm-ctl uninstall --dry-run
sudo /opt/clm/clm-ctl uninstall

This removes the program and services and keeps your data, backups, license and settings. To delete those too, copy the backups and master key somewhere safe first. This cannot be undone:

Terminal
sudo /opt/clm/clm-ctl uninstall --remove-config --remove-data --confirm "$(hostname)"

12. Troubleshooting

Rerun the install command after each fix. It is safe.

What you seeCauseFix
certs.example.com does not resolve yet.No DNS record yetCreate it (section 4), confirm with dig, run again
certs.example.com points to 203.0.113.99, which does not reach this server.Wrong address, or Cloudflare proxy onFix the record. Set Cloudflare to DNS only. If the server cannot connect to its own public address, add --skip-dns-check
points to 10.0.0.5, which the public certificate authority cannot reach.Internal name with a public certificateUse --cert and --key (section 6)
Port 80 is in use by nginx.Another service holds the portStop it, or use --own-proxy
HTTPS did not come up in 3 minutes. with Last HTTPS error: no certificate yetThe certificate authority could not reach port 80Open port 80 from the internet, check DNS, run again. Look for validating authorization in journalctl -u clm-caddy.service
HTTPS: not working in clm-ctl statusThe proxy has no certificate, or it stoppedRun journalctl -u clm-caddy.service -n 50 --no-pager
rateLimited in journalctl -u clm-caddy.serviceLet’s Encrypt limits how often a name can fail or be issuedStop retrying, fix the cause, wait for the time in the message
The clock on this host is off by 600 seconds.No time syncTurn on time sync, for example chrony
This host cannot reach the certificate authority at ...Outbound HTTPS blockedAllow outbound TCP 443, or use --cert and --key
The license file is not valid.Wrong or changed fileUse the license.json clm.mt sent, unedited
The license has lapsed.Past the end date and the 30-day graceRenew it with clm.mt
This setup link has expired. in the portalMore than 60 minutes passedRun sudo /opt/clm/clm-ctl setup-token
This setup link is not valid. in the portalAn old link, or a typing mistakeRun sudo /opt/clm/clm-ctl setup-token
curl: (60) SSL certificate problem on the agent hostThe agent host does not trust your private CAUse --cacert and --ca-file (section 9)
Agent shows offlineAgent cannot reach the serverOn the agent host, run curl -sS https://certs.example.com/healthz and journalctl -u clm-agent -n 50 --no-pager. Check outbound TCP 443
A different version is already installed.You ran a newer bundle’s installerUse clm-upgrade.sh (section 11)
This server already uses your own Caddy.An older install with your own CaddyAdd --own-proxy, or keep using it as it is

13. Getting support

Make a diagnostics bundle:

Terminal
sudo /opt/clm/clm-ctl diagnostics --out /root/clm-diagnostics.tar.gz
Text
Wrote /root/clm-diagnostics.tar.gz (private, mode 0600). Review it before sending it to support.

It holds versions, the names of your settings but not their values, health checks, service state, file names and recent logs. It does not hold the database, backups, keys, certificates or passwords. Log lines can still name your hosts and users, so read it before you send it.

Send it to the support contact in your clm.mt agreement, with the version from clm-ctl status, what you ran, and the exact message you saw.