How it works
Panel backup and restore
Back up the panel itself, its database, encryption keys, licence and configuration, into one encrypted archive, and restore it on a clean server.
Account backups carry your customers' files and databases. They do not include the panel itself:
its own database (administrators, accounts, plans, sites, schedules, the audit journal), the key
every stored secret is encrypted with, the licence and /etc/maran. Without the key, a new server
cannot read the secrets in a copied database. maran panel-backup and maran panel-restore cover
this.
Both work only as root, like the rest of the maran command. Run by hand they add no service, port
or network call. The optional schedule described below adds a systemd timer and, only if you
configure it, one outbound HTTPS upload.
The passphrase file
The archive is encrypted with a passphrase you choose, read from a file. Create it once:
sudo install -m 0600 /dev/null /root/maran-backup.passphrase
sudo editor /root/maran-backup.passphrase
The file must be a regular file (not a symlink), owned by root, mode 0600 or 0400, and hold
one line of at least 20 characters. Anything else is refused before anything is written. The
passphrase is never passed on the command line or in the environment.
Keep a copy of the passphrase somewhere other than the server and other than where the archives go. Without it, nobody can open an archive, including you.
Take a backup
sudo /usr/local/sbin/maran panel-backup --passphrase-file /root/maran-backup.passphrase
It writes maran-panel-backup-<UTC time>-<pid>.tar.gpg, mode 0600, into /root and prints its
path. --out DIR chooses another directory: an absolute path, owned by root and not writable by
group or others. The panel keeps running while the backup is taken. A failed run leaves no
partial file behind.
Copy the archive off the server. Whoever holds the archive and the passphrase holds the panel.
What the archive contains
| Part | Restored by panel-restore |
|---|---|
| The panel database, every schema | yes |
Security__EncryptionKey and Jwt__SigningKey from /etc/maran/panel.env | yes |
/var/lib/maran/licence.json | yes |
The rest of /etc/maran and /var/lib/maran (the panel's TLS key, rendered configs, ACME material) | no, inside the archive for manual use |
Everything else in panel.env (the host name, ssh ports, the web server's uid) describes the server
it is on, so a restore keeps what the new install wrote.
The archive is encrypted with gpg (AES-256) with integrity protection. A changed or truncated archive is refused and never restored.
Restore onto a clean server
- Install Maran on the new server, the same release as the backup or a newer one. Do not create an administrator in the browser.
- Copy the archive to the new server, owned by root, and recreate the passphrase file there.
- Restore:bash
sudo /usr/local/sbin/maran panel-restore --passphrase-file /root/maran-backup.passphrase \ --replace-this-panel /root/maran-panel-backup-20261101T120000Z-4242.tar.gpg - Sign in with an administrator of the old panel. Every session from the old server has ended.
- Restore customers' files, sites and databases from the account backups. A panel backup holds the panel's records of them, not their contents.
The order a restore follows
- Decrypt and check the archive and its format version.
- Check the two keys in the archived
panel.env. - Stop the panel.
- Replace the database in one transaction.
- Write the two keys into this server's
panel.env. - Put the licence back.
- Apply this release's migrations.
- Start the panel.
If the database replacement fails, its transaction rolls back and the database stays as the install left it. If anything fails after the panel has been stopped, the panel is started again.
What it refuses
- running without
--replace-this-panel, because a restore replaces this panel's database and keys; - a passphrase file that fails the rules above;
- an archive that is not an absolute path, not a regular file, or not owned by root;
- a server with no
/etc/maran/panel.env(install Maran first); - a wrong passphrase or a damaged archive, before anything changes;
- an archive format this release does not restore;
- a second backup or restore while one is already running.
Nothing from the archive is executed. Only the named files are taken out of it, and the keys are checked before they are written.
Schedule it, keep a few, send a copy off the server
Scheduling, retention and the S3 upload are not in 1.0.0-beta.4. They arrive with the next release.
On 1.0.0-beta.4, run maran panel-backup from root's crontab and copy the file with your own
tooling.
From the next release the installer puts the timer and its service on the server but never turns them on. You write a settings file first:
sudo install -d -m 0700 /etc/maran-backup
sudo install -m 0600 /dev/null /etc/maran-backup/passphrase
sudo editor /etc/maran-backup/passphrase
sudo install -m 0600 /usr/local/maran/cli/panel-backup.conf.example /etc/maran/panel-backup.conf
sudo editor /etc/maran/panel-backup.conf
sudo /usr/local/sbin/maran panel-backup-schedule enable
/etc/maran/panel-backup.conf is data, not a shell script: one KEY=VALUE per line, no quotes, no
spaces, an unknown or repeated key is refused. It must be owned by root with mode 0600. It holds
no secret. It only names the files that do:
| Key | Meaning |
|---|---|
PASSPHRASE_FILE | Required. The passphrase file, with the same rules as above. |
OUT_DIR | Where archives are written. Default /var/backups/maran-panel, which the installer creates for root only. Another directory must exist first (root-owned, mode 0700). |
KEEP | How many archives to keep, 1 to 365. Default 14. |
SCHEDULE | When to run, as a systemd calendar time such as *-*-* 02:30:00 (the default, every day) or Sun *-*-* 03:00:00; hourly, daily, weekly and monthly also work. The timer adds up to 15 minutes of random delay. |
S3_ENDPOINT, S3_BUCKET, S3_REGION, S3_ACCESS_KEY_ID_FILE, S3_SECRET_FILE, S3_PREFIX | Optional upload. Set all of them except S3_PREFIX (an optional folder in the bucket), or none. The two credential files hold one value each. |
Keep the passphrase file and the S3 credential files outside /root and /home, for example in
/etc/maran-backup (root-owned, mode 0700, each file 0600). The scheduled job cannot see those
two trees, and enable refuses a path under them. Do not keep them under /etc/maran either: that
directory is inside the archive, and a passphrase stored in the archive it protects protects
nothing.
enable checks the file and the schedule, then starts the timer. If anything is wrong it names the
first problem and changes nothing. Afterwards:
sudo /usr/local/sbin/maran panel-backup-schedule status
sudo /usr/local/sbin/maran panel-backup-schedule disable
status shows whether the timer is enabled and active, its next and last run, and how the last run
ended. disable stops the timer and leaves your settings and every archive where they are.
Each run is the same backup as the manual one, taken by the timer as root. A machine that was off at the scheduled time takes its backup when it next starts. Then, in this order:
- Retention. Only after the new archive exists, the newest
KEEPare kept. Older ones are removed fromOUT_DIR, and only files whose whole name ismaran-panel-backup-<UTC time>-<pid>.tar.gpgand that are regular files. Anything else in the directory is left alone. Retention never touches copies in S3. - Upload, only if
S3_ENDPOINTis set. The already-encrypted.tar.gpgfile is sent over HTTPS (TLS 1.2 or newer, no redirects, certificates always checked), and the upload counts as done only when the stored object has the same size as the local file. A network error or a 5xx is tried three times, ten seconds apart. The credentials are never put on a command line or in the log.
If retention or the upload fails, the archive stays on the server and the run is reported as failed
(systemctl status maran-panel-backup.service). Each run also leaves one line in the system journal
under the maran-cli tag, with the outcome and nothing else. Uninstalling Maran removes the timer
and never the archives.
To restore from an off-site copy, download the .tar.gpg file to the new server, owned by root, and
follow Restore onto a clean server. The passphrase is still the one
that encrypted it.
Limitations
- Retention, the schedule and the upload work from the next release, as described above. The upload speaks the S3 API to an endpoint you name, over HTTPS only. There is no command that fetches an archive back from S3: download it with your own tooling.
- Restoring an archive from a newer release onto an older install is not refused by the command. Install the same release or a newer one first.
- A licence bound to the old server may need to be re-issued for the new one.
- The panel's TLS certificate, rendered configs and ACME material are not put back automatically; take them from the archive by hand if you need them.
- If the server loses power during a backup, the unencrypted staging copy stays in a root-only directory until the next run of either command clears it.