How it works
Panel certificate
How the panel orders a trusted certificate for its own host name over ACME, what the port 80 challenge block serves, renewal and how a failed order ends.
A fresh install serves the panel with a self-signed certificate, so a browser warns before it opens it. The panel can replace it with a trusted certificate for its own host name, ordered from the same ACME authority the sites use, and it keeps that certificate renewed.
Order one
Open Settings → Panel certificate as an administrator and press Request a trusted
certificate. The panel proves it controls its host name over HTTP on port 80 and installs the
result as /etc/maran/tls/panel.crt and /etc/maran/tls/panel.key, and reloads the web server.
Reload the page to use the new certificate.
The page shows the host name, when the certificate was issued and when it expires. Once one is installed, Renew now orders a new one straight away.
Only administrators can reach this page and its API (GET and POST /api/v1/panel-certificate).
A customer can neither order nor read the certificate.
The host name comes from the server
You do not type the name into the page. It is Panel__HostName in /etc/maran/panel.env, which
the installer writes from the machine's own host name. When that name is localhost, empty, or not
a plain name of letters, digits, dots and hyphens, the installer records nothing and no certificate
can be ordered.
To set it yourself, point the name's DNS at this server, add or edit the line, and restart the panel:
Panel__HostName=panel.example.com
The port 80 challenge block
The panel's web server configuration has one port 80 block for the panel's host name. It serves
only /.well-known/acme-challenge/, from /var/lib/maran-acme, and returns 404 for everything else.
It does not open a new port. The web server already listens on 80 for the sites, and your
firewall decides whether 80 is reachable, as it does for a site's certificate.
A server installed before this release does not have that block yet. Re-run the installer to get it. Until then, issuance fails at the challenge.
Renewal
A daily job renews a trusted panel certificate once it is within thirty days of expiry. If a renewal fails, the current certificate stays in place and the panel tries again the next day.
When issuance fails
Nothing is replaced. The certificate the panel was serving, self-signed or trusted, stays in place. The usual causes are:
- the host name does not resolve to this server;
- port 80 is closed by a firewall in front of the server;
- the authority refuses the order;
- the server is below its free-space floor, reported as
AgentBelowFreeSpaceFloor.
| Code | Status | Meaning |
|---|---|---|
PanelHostNameNotConfigured | 409 | Panel__HostName is not set. Set it in /etc/maran/panel.env and restart the panel. |
PanelCertificateNotIssued | 404 | No trusted certificate has been issued; the panel is served with its self-signed one. |
PanelChallengeWriteFailed | 500 | The verification file for the host name could not be placed on the server. |
Limits to know
- There is no command-line verb yet. Ordering and renewing happen in the panel only, so the
marancommand cannot order a certificate when the panel itself is unreachable. - There is no way back to self-signed. Once a trusted certificate is installed, the panel has no action that removes it and restores the installer's self-signed pair.
- The panel and the server agent must be updated together. This feature needs both at the same release.