Skip to content
Maran

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:

bash
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.
CodeStatusMeaning
PanelHostNameNotConfigured409Panel__HostName is not set. Set it in /etc/maran/panel.env and restart the panel.
PanelCertificateNotIssued404No trusted certificate has been issued; the panel is served with its self-signed one.
PanelChallengeWriteFailed500The 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 maran command 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.