How it works
Troubleshooting
Playbooks for the four commonest failures: the panel does not start, a site answers 502 or 404, a certificate is not issued, and the agent is unreachable.
Each playbook below has the same three parts: the symptoms you see, the checks that tell the
causes apart, and the fixes. Run every command on the server itself, as root. Two tools help in
all four cases: maran status shows which services are running even when the panel is down, and
maran collect-diagnostics writes a redacted archive for whoever is helping you (both are described
under Recovery and diagnostics).
sudo /usr/local/sbin/maran status
The services are maran-api (the panel), maran-agent (the root daemon that does the privileged
work), postgresql and nginx; maran-ftps is listed too once file transfer is turned on. Their
logs are in the systemd journal.
The panel will not start
Symptoms. The browser cannot open the panel on port 8443, or opens it and every call answers 502.
maran status shows maran-api.service as failed or activating, or the Panel section says its own
report is unavailable.
Checks.
sudo systemctl status maran-api.service --no-pager
sudo journalctl -u maran-api.service -n 50 --no-pager
ls -l /run/maran-api/api.sock
- The journal names the reason when the panel refuses to start: an encryption or signing key in
/etc/maran/panel.envthat is missing, is the published development key or is malformed, or a missingReverseProxy__PeerUid(the web server's user ID, which the installer writes). - The panel connects to PostgreSQL over its local socket, so check
postgresql.serviceinmaran statusas well. - A healthy panel socket exists at
/run/maran-api/api.sockwith mode 660. Absent means the panel never bound it; a different mode or group means nginx cannot open it and every call answers 502. - The unit gives up after five starts within sixty seconds. If the journal shows that, look earlier in the journal for the cause; the last line will not name it.
Fixes.
- Fix what the journal names, for example the offending line in
/etc/maran/panel.env. Never replace the encryption key by hand unless the panel's refusal message tells you to: it makes stored secrets unreadable. - Start PostgreSQL first if it was down:
sudo systemctl start postgresql.service. - Clear the start limit and start the panel:bash
sudo systemctl reset-failed maran-api.service sudo systemctl restart maran-api.service - If the files themselves are damaged, re-run the installer: it is safe to repeat (see Installation). To get back into the panel when only the sign-in is the problem, see Recovery and diagnostics.
A site answers 502 or 404
Symptoms. A hosted site returns 502 Bad Gateway or 404 Not Found, while the panel itself
works.
Checks.
sudo nginx -t
sudo systemctl status nginx.service --no-pager
ls /etc/maran/nginx/sites/
ls -l /run/maran-php/
sudo tail -n 50 /var/log/maran/sites/<account>/*.log
nginx -tmust pass. Every site has its own configuration file in/etc/maran/nginx/sites/, included through/etc/nginx/conf.d/maran-sites.conf. A site with no file there is a site nginx does not know, so its name answers with another site or the default.- A 502 on a PHP site means nginx could not reach the site's PHP pool: its socket is in
/run/maran-php. A 502 on a reverse-proxy site means the upstream service you pointed it at is not running or not listening. - A 404 means nginx answered but found nothing: the domain is not one of the site's domain names or aliases, the site is suspended or disabled, the DNS name points to a different server, or the document root has no index file. See Websites and PHP.
- The site's own access and error logs are in
/var/log/maran/sites/<account>/, outside the customer's home; the panel also streams them in the site's page. The panel's web server logs are/var/log/maran/nginx-access.logand/var/log/maran/nginx-error.log.
Fixes.
- Correct the domain, aliases or document root in the panel, or enable the site again, and check the DNS record.
- For a reverse-proxy site, start the upstream service.
- For a missing PHP socket or a site written by an earlier release, restart the panel:
sudo systemctl restart maran-api.service. On start it asks the agent to bring every PHP site's pool and web server configuration back in line. - A configuration write is checked with the web server's own validator and rolled back if it fails,
so a site cannot normally break the others. If
nginx -tfails on a file that is not Maran's, fix that file first: it stops reloads for every site.
A certificate is not issued
Symptoms. Ordering a certificate for a site, or a trusted one for the panel, fails. The error is
one of AcmeValidationFailed, AcmeValidationTimedOut, AcmeAuthorityUnreachable,
AcmeChallengeWriteFailed, PanelHostNameNotConfigured, PanelChallengeWriteFailed or
AgentBelowFreeSpaceFloor (all listed in API error codes).
Checks.
- Certificates use the ACME HTTP-01 challenge, so the authority must reach your server over plain
HTTP on port 80. The domain must resolve to this server and nothing may block port 80,
neither a firewall in front of the machine nor the server's own ruleset:bash
sudo nft list ruleset curl -I http://example.com/.well-known/acme-challenge/test
A 404 from the second command is fine: it proves port 80 answers for that name. - A site challenge is served from the site's own document root, so the site must exist, be
enabled and answer on the name you ordered. A name the panel reserves (an IP address,
localhost,.localand similar, or the panel's own host name) is refused before any request is made. - The panel's certificate needs
Panel__HostNamein/etc/maran/panel.envto be a real name that points at this server. Its challenge is served from/var/lib/maran-acmeby the port 80 block of the panel's web server configuration; a server installed before that block existed needs the installer re-run. See Panel certificate. - Free space:
df -h. Below the free-space floor (1 GiB unless changed) writes are refused.
Fixes.
- Point the DNS record at this server and open port 80, then order again. A failed order replaces nothing: the certificate already in use stays in place.
- Set
Panel__HostNameif it is missing, restart the panel and order again, or re-run the installer if the port 80 block is missing. - Free disk space if
AgentBelowFreeSpaceFlooris the error. - Wildcard names and DNS-01 are not supported, so a name like
*.example.comcannot be ordered. How ordering and renewal work is on SSL certificates.
The agent is unreachable
Symptoms. Actions that change the server (creating an account or a site, a certificate order, a
backup) fail with an agent error such as AgentIncompatible, while pages that only read panel data
still load. The panel's health report shows the agent as unavailable, and maran status shows
maran-agent.service as not active.
Checks.
sudo systemctl status maran-agent.service --no-pager
sudo journalctl -u maran-agent.service -n 50 --no-pager
ls -l /run/maran/agent.sock
cat /etc/maran/agent.env
- The agent listens on a unix socket,
/run/maran/agent.sock, which should be mode 660, owned by root, in the panel's group. Nothing else may connect, and the agent accepts only the user ID inMARAN_AGENT_ALLOW_UIDin/etc/maran/agent.env. MARAN_AGENT_FREE_SPACE_FLOOR_MIBin the same file must be a whole number from 1: anything else makes the agent refuse to start (see the free-space floor in Recovery and diagnostics).AgentIncompatiblemeans the panel and the agent are at different versions, for instance during an update. They must be updated together.- The panel starts without the agent and only logs a warning, so the panel being up says nothing about the agent.
Fixes.
- Restart the agent, then the panel, in that order:bash
sudo systemctl restart maran-agent.service sudo systemctl restart maran-api.service - If the unit keeps failing, fix what its journal names (for example the floor value) and run
sudo systemctl reset-failed maran-agent.servicebefore restarting. - If the versions differ, re-run the installer so both come from the same release.
- If it still fails, run
sudo /usr/local/sbin/maran collect-diagnostics, read the archive, and send it to whoever is helping you.