Skip to content
Maran

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).

bash
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.

bash
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.env that is missing, is the published development key or is malformed, or a missing ReverseProxy__PeerUid (the web server's user ID, which the installer writes).
  • The panel connects to PostgreSQL over its local socket, so check postgresql.service in maran status as well.
  • A healthy panel socket exists at /run/maran-api/api.sock with 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.

  1. 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.
  2. Start PostgreSQL first if it was down: sudo systemctl start postgresql.service.
  3. Clear the start limit and start the panel:
    bash
    sudo systemctl reset-failed maran-api.service
    sudo systemctl restart maran-api.service
    
  4. 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.

bash
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 -t must 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.log and /var/log/maran/nginx-error.log.

Fixes.

  1. Correct the domain, aliases or document root in the panel, or enable the site again, and check the DNS record.
  2. For a reverse-proxy site, start the upstream service.
  3. 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.
  4. 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 -t fails 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, .local and similar, or the panel's own host name) is refused before any request is made.
  • The panel's certificate needs Panel__HostName in /etc/maran/panel.env to be a real name that points at this server. Its challenge is served from /var/lib/maran-acme by 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.

  1. 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.
  2. Set Panel__HostName if it is missing, restart the panel and order again, or re-run the installer if the port 80 block is missing.
  3. Free disk space if AgentBelowFreeSpaceFloor is the error.
  4. Wildcard names and DNS-01 are not supported, so a name like *.example.com cannot 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.

bash
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 in MARAN_AGENT_ALLOW_UID in /etc/maran/agent.env.
  • MARAN_AGENT_FREE_SPACE_FLOOR_MIB in 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).
  • AgentIncompatible means 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.

  1. Restart the agent, then the panel, in that order:
    bash
    sudo systemctl restart maran-agent.service
    sudo systemctl restart maran-api.service
    
  2. If the unit keeps failing, fix what its journal names (for example the floor value) and run sudo systemctl reset-failed maran-agent.service before restarting.
  3. If the versions differ, re-run the installer so both come from the same release.
  4. If it still fails, run sudo /usr/local/sbin/maran collect-diagnostics, read the archive, and send it to whoever is helping you.