GoAdmio

maria

Back up MariaDB with full and incremental snapshots stored in restic on local disk or an rclone remote (such as S3), and list, restore, or mount them on demand

On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also


Overview

/go/maria backs up every MariaDB database on the server at once, using mariadb-backup and restic. It:

This command backs up the database server only. For hosting accounts (files, mail, settings), use backup or snapshot.


Quick start

# 1. Turn on scheduled backups (creates /var/go/etc/maria.conf)
/go/maria start

# 2. Take a backup now
/go/maria

# 3. See your snapshots
/go/maria list

Syntax

/go/maria [action] [snapshot] [--force]
Form Behavior
/go/maria Take a full backup if none exists, otherwise an incremental backup.
/go/maria start Create /var/go/etc/maria.conf with the default schedule, if it doesn't exist.
/go/maria stop Disable scheduled backups by renaming maria.conf to maria.bak.
/go/maria list List the snapshots in the backup destination.
/go/maria refresh Delete the local full and incremental backups, then take a new full backup.
/go/maria restore [snapshot] [--force] Restore a snapshot into /var/lib/mysql and restart MariaDB.
/go/maria connect [snapshot] Restore a snapshot into a separate data directory and start a second MariaDB instance on port 3307.

[snapshot] is either a tag or a restic snapshot ID. See Snapshot tags.

The command needs the server hostname to contain at least two dots (for example server.example.com). Otherwise it stops immediately.


Options

Actions and flags

Argument Used with Default Notes
start — — Does nothing if maria.conf already exists.
stop — — Replaces any earlier maria.bak.
list — — Same as restic snapshots on the destination.
refresh — — Forces a new full backup. The local backup chain is deleted first.
restore — — Fails if /var/lib/mysql already contains data, unless you pass --force.
connect — — Erases the data directory of the earlier connect instance and ends anything listening on port 3307.
<snapshot> restore, connect Backup files already in Dir A tag or snapshot ID. If omitted, the backup files already on disk are used.
--force restore Off Stops MariaDB and deletes everything in /var/lib/mysql before restoring.

Settings file: /var/go/etc/maria.conf

All backup actions need this file. start creates it.

Setting Default Notes
Cron "0 12,16,20 * * *" Written by start. Backups run at 12:00, 16:00, and 20:00 daily. The script itself does not read this value.
Dir /maria Local working folder for the backup files. If you set it, the folder must already exist.
RemoteDir maria Folder in the remote destination. A leading / is removed.

Example:

Cron="0 12,16,20 * * *"
Dir="/maria"
RemoteDir="maria"

Backup destination

The destination is chosen automatically from /root/.config/rclone/rclone.conf:

rclone remote found Destination
[maria] maria:<RemoteDir>/<hostname>
[backup] (and no [maria]) backup:<RemoteDir>/<hostname>
Neither /backup/maria on this server (no hostname subfolder)

Output

The command prints short progress lines. There is no JSON output.

Message Meaning
Taking Full Backup... No full backup exists locally, so one is being taken.
Restic Full Backup: <destination>... The full backup is being sent to the destination.
Taking Incremental Backup... A full backup already exists, so only changes since it are being taken.
Restic Incremental Backup: <destination>... The incremental backup is being sent to the destination.
Restoring Restic TAG <tag>... The snapshot argument matched a tag.
Restoring Restic ID <id>... The snapshot argument matched a snapshot ID.
Restoring MariaDB Backup... The backup files are being prepared and copied back.
mariadb --port=3307 Printed by connect. Run it to open the second instance.
Instance (maria) already running. Another run started less than an hour ago.
Invalid Server Hostname <hostname>, ... The hostname has fewer than two dots.
File /var/go/etc/maria.conf not Exists. Scheduled backups were never started (or were stopped).
Folder <Dir> not Exists. Dir in maria.conf points to a missing folder.
Directory /var/lib/mysql is not empty. restore refused to overwrite existing data.
Archive <snapshot> does not exist No tag or ID matched. The snapshot list is printed after it.

[!NOTE] Most actions end with exit status 1, even when they work (start, stop, list, restore, connect, and full backups). Only an incremental backup ends with 0. In scripts, read the output instead of relying on the exit status.

Security

[!WARNING] Restic encrypts snapshots with a fixed password built into the script. That password is the same on every server, so the encryption does not protect your data from anyone who can read the repository and knows the default. Restrict access to the remote bucket or to /backup/maria. The MariaDB root password is also passed to mariadb-backup on its command line, so it is briefly visible in the process list while a backup runs.


Examples

# Take a backup (full the first time, incremental afterwards)
/go/maria
# Start over with a fresh full backup, for example after switching destination
/go/maria refresh
# List the available snapshots
/go/maria list
# Restore the latest snapshot taken at 20:00 over the live databases
/go/maria restore 20 --force
# Restore a specific snapshot by its ID
/go/maria restore a1b2c3d4 --force
# Inspect the 12:00 snapshot without touching live data
/go/maria connect 12
mariadb --port=3307
# Stop scheduled backups
/go/maria stop

Troubleshooting

Symptom Likely cause Fix
Instance (maria) already running. A backup started less than an hour ago and hasn't finished. Wait. If nothing is running, delete /usr/local/goadmio/lock/maria.lock. A lock older than an hour is ignored automatically.
Invalid Server Hostname The hostname has fewer than two dots. Set a full hostname with hostname.
File /var/go/etc/maria.conf not Exists. Backups were never enabled, or stop was run. Run /go/maria start.
Folder <Dir> not Exists. Dir in maria.conf points to a missing folder. Create the folder, or fix Dir.
Backups land on local disk, not the remote No [maria] or [backup] remote in rclone.conf. Add a remote with one of those names, then run /go/maria refresh.
Incremental runs fail after changing the remote The restic repository is only created during a full backup, and the new destination has none. Run /go/maria refresh.
Directory /var/lib/mysql is not empty. restore won't overwrite live data by default. Add --force if you are sure. This deletes the current databases.
Archive <snapshot> does not exist The argument is not a known tag or snapshot ID. Run /go/maria list and copy a tag or ID.
Restoring a tag gave older data than expected A tag is the hour of the day, and restic uses the newest snapshot with that tag. Use the snapshot ID from list for an exact point in time.
Disk fills up Local backup files stay on disk, and with local storage the restic repository is on disk too. Use a remote, or free space with clean.
Script reports failure though the output looks fine Most actions exit with status 1. Check the output messages, not the exit status.

Details

What a backup run does

flowchart TD
    A["maria"] --> B{"Lock younger than 1 hour?"}
    B -- "Yes" --> X1["Instance already running, exit"]
    B -- "No" --> C{"Hostname has 2+ dots<br/>and maria.conf exists?"}
    C -- "No" --> X2["Error, exit"]
    C -- "Yes" --> D{"Full backup exists locally?"}
    D -- "No" --> E["mariadb-backup full + compress"]
    E --> F["restic init, forget, prune"]
    F --> G["restic backup, tagged with the hour"]
    D -- "Yes" --> H["mariadb-backup incremental<br/>against the full backup"]
    H --> G
    G --> I["Release lock"]
  1. Writes the command and its arguments to /var/log/go/maria.log.
  2. Takes a lock in /usr/local/goadmio/lock/maria.lock. The lock is released when the command ends, even if you press Ctrl+C.
  3. Checks the hostname, reads maria.conf, and picks the destination.
  4. Raises the open-files limit and enables io_uring, which mariadb-backup uses.
  5. Takes the backup (see below) and sends the whole Dir folder to restic, tagged with the current hour.

Full backup

Taken when <Dir>/<hostname>/full/mysql doesn't exist locally, such as on the first run or after refresh. After the backup, it:

Incremental backup

Taken on every later run. The previous incremental backup is deleted, and the new one is taken against the full backup, not against the previous incremental. So each incremental grows until the next full backup, but a restore needs only the full backup plus the latest incremental.

Retention

Rule Keeps
--keep-within 24h Every snapshot from the last 24 hours
--keep-daily 7 One snapshot per day for 7 days
--keep-weekly 4 One snapshot per week for 4 weeks
--keep-monthly 12 One snapshot per month for 12 months

[!NOTE] Old snapshots are removed only when a full backup is taken (the first run, or after refresh). Incremental runs never prune. If you rarely run refresh, snapshots keep accumulating. Running /go/maria refresh now and then (for example monthly) keeps the repository tidy and resets the growing incremental.

Snapshot tags

Each snapshot is tagged with the hour (00 to 23) at which it was taken. With the default schedule, the tags in use are 12, 16, and 20.

When you pass a snapshot to restore or connect, the command first looks for a matching tag and restores the latest snapshot that has it. If there is no tag match, it tries the argument as a snapshot ID.

How restore works

  1. If --force was passed, stops MariaDB and deletes /var/lib/mysql/*.
  2. If /var/lib/mysql still holds data, prints Directory /var/lib/mysql is not empty. and stops.
  3. If a snapshot was given, deletes the local Dir folder and restores the snapshot into it. Without a snapshot, the backup files already in Dir are used.
  4. Stops MariaDB, then decompresses and prepares the full backup. If an incremental backup exists, it is decompressed and applied on top.
  5. Copies the result into /var/lib/mysql, fixes ownership, and restarts MariaDB.

How connect works

connect follows the same steps as restore, with these differences:

The second instance keeps running until you stop it. To discard it, end the process on port 3307.


See also

Command Description
backup Back up one or all GoAdmio accounts to local disk or remote storage, manually or on a schedule
snapshot Back up, list, check, restore, and delete restic snapshots of hosting accounts, locally or on remote storage
restore Restore accounts, databases, SSL certificates, or folders from local or remote GoAdmio backups
mysqlbackup Back up MariaDB/MySQL to a remote server via rsync
cron Rebuild GoAdmio's cron jobs, server-wide or for one domain, and restart or stop the cron service
s3 Mount an S3 bucket on a GoAdmio server
installmariadb Install or upgrade MariaDB from the official repositories (default version 12.3, or a version you choose) and apply basic hardening
my Regenerate the MariaDB configuration file with settings tuned to the server's RAM, CPU, and database usage, then restart MariaDB