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.
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.gzorclm-server-VERSION-linux-arm64.tar.gz. Use the one that matches the server. - The license: a file called
license.json.
Who you need
| Person | What they do |
|---|---|
| Server admin | Creates the server and runs the installer with sudo |
| DNS admin | Creates one DNS record |
| Firewall admin | Opens 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
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 server3. 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:
sudo apt-get install -y python3 openssl curl ca-certificatesCloud 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:
| Type | Name | Value | TTL |
|---|---|---|---|
| A | certs | 203.0.113.10 | 300 |
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:
dig +short certs.example.comIt 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
| Direction | Port | From or to | Why |
|---|---|---|---|
| Inbound | TCP 443 | Users and agents | Portal, API and agent check-ins |
| Inbound | TCP 80 | Internet | Proves the name for the certificate, and redirects to HTTPS. Not needed with your own certificate |
| Inbound | TCP 22 | Admin network only | Server administration |
| Outbound | TCP 443 | Internet | Certificate authorities, DNS providers, cloud APIs |
| Outbound | TCP 587 or 465 | Mail relay | System email, if used |
| Outbound | UDP 123 | Time servers | A wrong clock breaks certificates and sign-in |
| Outbound from agents | TCP 443 | The server name | Agents never need an inbound port |
| Outbound from agents | TCP 443 | Certificate authority, and DNS provider or acme-dns server | An 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:
| Type | Port | Source |
|---|---|---|
| HTTPS | 443 | 0.0.0.0/0 |
| HTTP | 80 | 0.0.0.0/0 |
| SSH | 22 | Your admin network |
If the server also runs a host firewall:
sudo ufw allow 443/tcp
sudo ufw allow 80/tcpOutbound 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 situation | Do you set up a certificate? | What to add to the install command |
|---|---|---|
| Public name, ports 80 and 443 open | No. It is automatic and renews itself | Nothing |
| Internal name, private CA, or no internet | Yes. You supply it and you renew it | --cert and --key |
| You have an internal ACME server | No, it comes from that server | --acme-ca |
| You run your own proxy or load balancer on this server | It 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:
sudo ./install-server.sh --license /path/license.json --domain certs.example.com \
--cert /path/fullchain.pem --key /path/key.pemPort 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:
sudo ./install-server.sh --license /path/license.json --domain certs.example.com \
--acme-ca https://acme.example.com/directory --acme-ca-root /path/ca.pemYour 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:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAks2USTukRlSih6px645Zb+7IT4ZlHVUVi0z6nt1jv7w=
-----END PUBLIC KEY-----Extract the bundle and check it:
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 SHA256SUMSExpected output: Signature Verified Successfully, then one line ending in : OK for each file.
Check the host. This changes nothing:
sudo ./install-server.sh --check --license /path/license.json --domain certs.example.comExpected output:
Host checks passed.If something is wrong, it lists everything at once:
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:
sudo ./install-server.sh --license /path/license.json --domain certs.example.comExpected output:
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:
sudo /opt/clm/clm-ctl setup-tokenOpen 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:
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.comExpected output of the first command:
System email settings saved. Restart clm-server.service to apply, then run: clm-ctl smtp-test RECIPIENTSingle 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:
curl -fsSL 'https://certs.example.com/install.sh' | sudo env CLM_ENROLL_TOKEN='TOKEN' bashExpected output:
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 -fThe agents come from your own server, not from clm.mt. Within a minute the server status shows it:
Agents: 1 of 1 onlineIf you use a private CA, copy your CA file to the agent’s host and pass it twice:
curl -fsSL --cacert ca.pem 'https://certs.example.com/install.sh' | sudo env CLM_ENROLL_TOKEN='TOKEN' bash -s -- --ca-file ca.pemYour 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.
- 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.
- 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.
- 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.
- 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. - Confirm the status is Healthy and the address serves the new certificate.
- 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:
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.jsonA 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:
sudo /opt/clm/clm-ctl restore /path/to/backup.tar.gz --replaceExpected output, shortened:
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.
sudo /opt/clm/clm-ctl statusMonitoring. 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:
| When | What happens |
|---|---|
| Up to 30 days after the end date | Nothing is refused. A banner shows when the grace period ends |
| After those 30 days | New agents and new certificates are refused until you install a renewed license |
| Always | Existing 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:
sudo /opt/clm/clm-upgrade.sh /path/to/clm-server-NEWVERSION-linux-ARCH.tar.gzIt lists its checks and ends with:
Upgraded to 1.2.0; previous binary and data snapshot retained in /opt/clm and /var/lib/clm-upgrade/rollbackIt 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.
- Stop the old server:
sudo systemctl stop clm-server.service clm-caddy.service. - Point DNS at the new server. Agents wait and retry.
- Install on the new server as in section 7, with the same name. Ignore the link.
- Copy the newest backup across and restore it with the command in section 10.
- Run
clm-ctl smtp-setupagain. - 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:
sudo /opt/clm/clm-ctl uninstall --dry-run
sudo /opt/clm/clm-ctl uninstallThis 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:
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 see | Cause | Fix |
|---|---|---|
certs.example.com does not resolve yet. | No DNS record yet | Create 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 on | Fix 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 certificate | Use --cert and --key (section 6) |
Port 80 is in use by nginx. | Another service holds the port | Stop it, or use --own-proxy |
HTTPS did not come up in 3 minutes. with Last HTTPS error: no certificate yet | The certificate authority could not reach port 80 | Open 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 status | The proxy has no certificate, or it stopped | Run journalctl -u clm-caddy.service -n 50 --no-pager |
rateLimited in journalctl -u clm-caddy.service | Let’s Encrypt limits how often a name can fail or be issued | Stop retrying, fix the cause, wait for the time in the message |
The clock on this host is off by 600 seconds. | No time sync | Turn on time sync, for example chrony |
This host cannot reach the certificate authority at ... | Outbound HTTPS blocked | Allow outbound TCP 443, or use --cert and --key |
The license file is not valid. | Wrong or changed file | Use the license.json clm.mt sent, unedited |
The license has lapsed. | Past the end date and the 30-day grace | Renew it with clm.mt |
This setup link has expired. in the portal | More than 60 minutes passed | Run sudo /opt/clm/clm-ctl setup-token |
This setup link is not valid. in the portal | An old link, or a typing mistake | Run sudo /opt/clm/clm-ctl setup-token |
curl: (60) SSL certificate problem on the agent host | The agent host does not trust your private CA | Use --cacert and --ca-file (section 9) |
| Agent shows offline | Agent cannot reach the server | On 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 installer | Use clm-upgrade.sh (section 11) |
This server already uses your own Caddy. | An older install with your own Caddy | Add --own-proxy, or keep using it as it is |
13. Getting support
Make a diagnostics bundle:
sudo /opt/clm/clm-ctl diagnostics --out /root/clm-diagnostics.tar.gzWrote /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.