Skip to content
Maran

How it works

Recovery and diagnostics

Regain access to the panel when the administrator password or authenticator is lost, check server health, and collect a redacted support bundle.

The maran command is for the moment the panel's own sign-in cannot be used. It is installed with the panel, adds no service, port or network call, and works only from a shell on the server itself.

CommandUse it when
maran admin-reset-passwordAn administrator lost their password or their authenticator, and the panel cannot mail a reset.
maran statusYou need to know which services are running and what the panel reports about itself, even with the panel down.
maran collect-diagnosticsYou need to send a support bundle to someone who is helping you.

Run it as root

The command works only as root, because it can issue a credential for an administrator. Run it with its full path so it works whatever PATH your sudo keeps:

bash
sudo /usr/local/sbin/maran status

A user who is not root gets a one-line refusal and nothing else.

Reset an administrator's password

bash
sudo /usr/local/sbin/maran admin-reset-password admin@example.com

Give the administrator's email address or username. The command then:

  1. Accepts only an administrator whose login is active. A customer, a suspended administrator or an invited login that was never accepted is refused with a clear message. Customers reset their password by email in the customer area.
  2. Cancels any reset link issued earlier, so at most one link is ever live.
  3. Lifts a lockout from failed sign-ins and signs the account out of every session.
  4. Prints a reset link once, on your terminal. It is valid for one hour and works once. It is never written to a log or to the audit record, and the command refuses to print it into a pipe or a file unless you add --allow-non-terminal.

Open the link in a browser and choose a new password. If the panel has no public address configured, the command prints a path beginning with / and says so; put your panel's address in front of it.

Every use is recorded in the panel's audit log and in the server's authentication log (authpriv), naming the account and whether two-factor was cleared. The operator name comes from SUDO_USER and is a claim, not proof.

If no administrator exists at all, the command says so and points you to the first-run setup page instead of creating one.

When the authenticator is lost too

bash
sudo /usr/local/sbin/maran admin-reset-password admin@example.com --clear-two-factor

This also removes the administrator's two-factor enrolment, so the next sign-in needs only the new password. Use it only when the authenticator really is lost, because it lowers that account's protection until the administrator enrols again. Sign in and turn two-factor back on straight away. Without the flag, two-factor is never touched.

When correct two-factor codes are refused

Authenticator codes are computed from the time, so a server whose clock has drifted refuses every correct code. The panel watches the clock: when its latest check found the clock not synchronised with a time source, a refused code says so ("The server's clock is not synchronised…") instead of only "That code is not valid". The dashboard lists "Server clock not synchronised" under Needs attention, the Monitoring page shows a Clock card with the reason, and the operator is mailed when the clock has stayed unsynchronised for ten checks and again when it recovers.

The panel never sets the time itself. Turn on a time synchronisation service and let it reach a time server:

bash
sudo timedatectl set-ntp true             # Debian and Ubuntu: systemd-timesyncd
sudo systemctl enable --now chronyd       # AlmaLinux and Rocky Linux: chrony
timedatectl                               # look for "System clock synchronized: yes"

The panel reads the kernel's own verdict. The kernel stops calling the clock synchronised once its estimate of the possible error passes sixteen seconds, so a clock that is off by a few seconds but still counts as synchronised is not reported.

Change your own password

Anyone signed in to the panel, administrator or customer, can change their own password without the e-mail reset link. Open the menu under your name, choose Profile and security, and use the Password card: Current password, New password and Confirm password, then Change password.

  • The new password must be at least as long as the minimum the security policy sets for resets and invitations; a shorter one is refused. The message currently always names 12 characters, whatever the policy's minimum is (issue #300).
  • A wrong current password is refused with 400 CurrentPasswordIncorrect, "The current password is not correct." It counts towards the account lockout exactly as a failed sign-in does, and while the account is locked every attempt gets the same answer.
  • On success the panel says "Your password has been changed. Every other device has been signed out." The device you changed it on stays signed in; every other session ends.

The endpoint is POST /api/v1/auth/change-password, and it shares the sign-in rate limit. Every change and every refusal is written to the audit log as "Password changed", never with either password. The other error codes are listed under API error codes.

Check server health

bash
sudo /usr/local/sbin/maran status

The first section shows whether the panel, the agent, PostgreSQL and the web server are active and enabled (file transfer is included once an administrator has turned it on). The second is the panel's own report: database reachability, the agent connection, pending migrations, the version, how many administrators exist and whether the first-run setup window is still open. If the second section fails, the first is still shown. The exit status is 0 when everything is healthy and 1 otherwise. The output contains no secrets.

Free-space floor

The agent keeps a free-space floor: the space, in MiB, that must still be available on a filesystem before it starts work that writes there. It is 1 GiB unless you change it in /etc/maran/agent.env:

bash
MARAN_AGENT_FREE_SPACE_FLOOR_MIB=1024

The installer writes 1024 and keeps your value when it is re-run. The unit passes it to the agent as --free-space-floor-mib; without the flag the agent applies the same 1024. It must be a whole number from 1. Zero or any other value makes the agent refuse to start, since an unreadable floor should not be treated as zero. Only root can change it; nothing the panel sends carries a floor.

While less than the floor is available on the filesystem the operation would write into, these are refused before anything is written:

  • creating an account,
  • taking a backup,
  • restoring a backup,
  • accepting an upload.

The refusal is the error AgentBelowFreeSpaceFloor (HTTP 503), shown in your language as "The server is nearly out of disk space…", in the response and as the failure of a backup or restore task. A filesystem that cannot be measured is refused too. Suspending, deleting and every read keep working, so you can free space from the panel.

The floor is checked before the work starts and the space is not reserved. Another writer can still fill the disk afterwards, and the write paths keep their own all-or-nothing handling for that case.

The approaching floor alert

The panel mails the operator when the root filesystem has had less than twice the floor available for ten consecutive checks, so the warning arrives before the refusals begin. A second mail says when free space is clear of the floor again. If the account homes live on a separate filesystem, the refusal still follows that filesystem, but there is no earlier alert, because the alert watches the root filesystem only.

Collect a support bundle

bash
sudo /usr/local/sbin/maran collect-diagnostics

This writes maran-diagnostics-<time>-<id>.tar.gz into /root, readable by root only. Choose another directory with --out DIR (an absolute path, owned by root and not writable by others), or leave the logs out with --no-logs.

What it contains:

  • the service report from maran status, which includes the database and migration facts;
  • the operating system release, the panel's systemd units and the state of its services;
  • the two Maran web server configuration files;
  • the NAMES of the panel's settings, never their values;
  • the panel certificate's subject, issuer and validity dates;
  • the firewall ruleset;
  • unless --no-logs, the last seven days of the panel, agent and web server journal (capped in size) and the end of the panel's own top-level log files.

What it never reads: customers' files and home directories, the sites' own logs, backups, database dumps, private keys, and the values in panel.env.

Known secrets and common secret shapes are removed from every text, then the finished archive is unpacked and scanned again. If that scan finds anything, the archive is deleted and the command fails instead of leaving you a bundle you might send.

Review it before you send it. Redaction removes what this server is known to hold, and it cannot be proven complete. IP addresses, host names and customer domain names are not removed. Extract the archive, read it, and send it only to people you trust with that information.

Read the logs, and change how much is written

The panel and the server agent write to the systemd journal: read them with journalctl -u maran-api and journalctl -u maran-agent. journald bounds their size. Files under /var/log/maran are rotated by policies the installer puts in /etc/logrotate.d/: the install log monthly (twelve kept), the panel's own web server logs daily (thirty kept), the sites' web server logs daily (fourteen kept) and the FTPS log weekly (four kept). Re-run the installer on an older server to get the install log's policy.

Change the panel's log level without a restart. Monitoring → Panel log level shows the level the panel is logging at and lets an administrator choose Verbose, Debug, Information (the normal level), Warning, Error or Fatal. The change applies to the next line written, is kept across restarts, and is recorded in the audit log with the level before and after. Raise it while you investigate a problem, then set it back. No level makes the panel write a password, a key or a token. The server agent's own level cannot be changed this way yet.