GoAdmio

snapshot

Back up, list, check, restore, and delete restic snapshots of hosting accounts, locally or on remote storage

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


Overview

/go/snapshot keeps point-in-time copies of hosting accounts in restic repositories, one repository per domain. It:

Snapshots are stored on a remote (through rclone) when one is configured, and in /var/snapshot/<domain> otherwise.


Quick start

# Back up one account
/go/snapshot example.com

# List its snapshots
/go/snapshot example.com list

# Restore everything from a date
/go/snapshot example.com restore 2026-11-18

Requirements

Needed for Requirement
Everything restic, and the configuration file in Configuration
Remote storage rclone, with a remote named snapshot in /root/.config/rclone/rclone.conf
--list jq
Restoring MySQL/MariaDB dumps pv
Restoring a single dump file screen

Configuration

The command stops with File /var/go/etc/snapshot.conf not Exists. unless /var/go/etc/snapshot.conf exists. The file can be empty.

RemoteDir="snapshot"
RestoreDir="/"
Setting Default Notes
RemoteDir snapshot Folder on the remote. An empty value, /, or /snapshot all mean snapshot. A leading / is removed. Used only with a remote.
RestoreDir / Where restic writes restored files. / puts files back in their original locations and overwrites existing files.

Where snapshots are stored

Condition Repository location
An rclone remote named [snapshot] exists snapshot:<RemoteDir>/<server-hostname>/<domain>
Otherwise /var/snapshot/<domain>

What is backed up

Server type Backed up How it's detected
MinIO/S3 /s3/<domain> /usr/local/goadmio/minio/minio.conf exists and contains :443 , and /s3 exists.
cPanel /home/<user> /scripts exists. Pass the cPanel username.
GoAdmio (default) /home/<domain>, plus generated dumps and settings The account has a www folder.

Syntax

# Back up
/go/snapshot                            # every account that has snapshots enabled
/go/snapshot all                        # same
/go/snapshot <domain>                   # one account
/go/snapshot <cpanel-user>              # one account on a cPanel server

# Inspect
/go/snapshot list                       # accounts that have snapshots
/go/snapshot <domain> list              # snapshots of one account
/go/snapshot <domain> --list            # same, one line per snapshot: id|tag|unix-time
/go/snapshot check                      # verify every repository, rebuild missing ones

# Restore
/go/snapshot <domain> restore <archive> [--www] [--mail] [--database] [--skip mysql]
/go/snapshot /home/<domain>/<path> <archive>
/go/snapshot /home/<domain>/log/mysql/<db>.sql <archive>
/go/snapshot <user>@<domain> <archive>

# Delete
/go/snapshot <domain> delete

<archive> is a date tag in the form YYYY-MM-DD or a snapshot ID, as shown by list. A date tag restores the latest snapshot that carries that tag.

Form Behavior
No argument, or all Backs up every account with a www folder whose snapshot setting is on. Accounts with it off print Snapshot Backup Disabled <domain>....
<domain> Backs up that account. The per-account snapshot setting is ignored.
list Prints the domains that have snapshot repositories.
<domain> list Prints that domain's snapshots.
<domain> restore <archive> Restores the account (see Restoring an account).
/home/<domain>/<path> <archive> Restores one file or folder. Afterwards runs fix, and for a path under mail also recreates mailboxes from the folders with mail.
/home/<domain>/log/mysql/<db>.sql <archive> Restores one dump file, then imports it into the database <db> in the background and deletes the file.
<user>@<domain> <archive> Restores that mailbox's folder only. It does not register the mailbox or fix ownership.
check For every account, verifies the repository. A missing or unreadable one is purged, recreated, and filled with a new snapshot.
<domain> delete Deletes the domain's whole repository, including every snapshot. Not available on cPanel servers.

[!WARNING] /go/snapshot all restore <archive> restores every account from that archive. Always give a domain.


Options

Option Applies to Notes
--www restore Restores only /home/<domain>/www and recreates subdomains.
--mail restore Restores only /home/<domain>/mail and recreates the mailboxes.
--database restore Restores only the account's log folder (dumps and saved settings) and re-creates the MySQL/MariaDB and PostgreSQL databases.
--skip mysql restore Creates the MySQL/MariaDB database records but doesn't import the dumps. It has no effect on backups.
--list Any domain Prints `short-id

--www, --mail, and --database can be combined. With none of them, restore restores everything.


Output

Outcome What you get
Backup of all accounts [N/C] Snapshot Backup <domain>... for each account, then restic's output.
Backup of one account Creating Snapshot: <repository>..., then restic's output.
Missing repository Repository Missing: <repository>, System will Initialize new Repository.
Another run in progress Instance (<name>) already running. and exit code 1.
Domain not found Domain <domain> does not exist, or User <user> does not exist on cPanel.
Unknown account SNAPSHOT: Domain Directory /home/<name> not Exists.
Unknown archive Archive <archive> does not exist, followed by the repository's snapshot list.
Restore Restoring Snapshot TAG <archive>... or Restoring Snapshot ID <archive>..., then a section for subdomains, mail, MySQL/MariaDB, and PostgreSQL.

Exit codes

Backups finish normally. These modes always exit with code 1, even on success: list, restoring a single dump, a path, or a mailbox, and --list.

Logging

Every run is appended to /var/log/go/snapshot.log.

Locking

Full runs (all, no argument, check, and cPanel usernames) take the lock file /usr/local/goadmio/lock/backup.lock, which is shared with backup. A lock younger than one hour blocks a second run. An older lock is treated as stale and replaced. Runs for a single domain, path, or mailbox don't take the lock.

Security

[!WARNING] Every repository is encrypted with the same fixed password, GoPanel. Anyone who can read the repository files, for example on the remote storage, can open every snapshot. Snapshots contain site files, database dumps, MariaDB password hashes, PostgreSQL passwords in plain text, and a saved password line (see Notes for maintainers).

The MariaDB root password is also passed on the command line during dumps, so it can be visible in the process list.


Examples

# Back up everything that has snapshots enabled
/go/snapshot all
# Back up one account, then check
/go/snapshot example.com
/go/snapshot example.com list
# Machine-readable list: short-id|tag|unix-time
/go/snapshot example.com --list
# Restore only the website files, from a date
/go/snapshot example.com restore 2026-11-18 --www
# Restore only the databases, from a snapshot ID
/go/snapshot example.com restore 3f9a1c2b --database
# Restore mail but don't import MySQL dumps
/go/snapshot example.com restore 2026-11-18 --mail --skip mysql
# Restore one folder
/go/snapshot /home/example.com/www/uploads 2026-11-18
# Restore one database dump
/go/snapshot /home/example.com/log/mysql/example_db.sql 2026-11-18
# Restore one mailbox folder
/go/snapshot info@example.com 2026-11-18
# Delete all snapshots of one account
/go/snapshot example.com delete

Troubleshooting

Symptom Likely cause Fix
File /var/go/etc/snapshot.conf not Exists. The configuration file is missing. Create it. See Configuration.
Instance (<name>) already running. A full backup or backup is running, or crashed less than an hour ago. Wait. A lock older than one hour is replaced automatically.
Repository Missing: ... System will Initialize new Repository. The repository could not be read. This can be a real absence, a network error, or a wrong password. The command purges and recreates the repository, deleting its history. Check storage and rclone access first.
Domain <domain> does not exist The account has no www folder. Check the domain with the account list.
Snapshot Backup Disabled <domain>... Snapshots are off for that account. all respects this, direct runs don't. Turn the account's snapshot setting on, or run /go/snapshot <domain>.
Archive <archive> does not exist The tag or ID isn't in the repository. Use a value from /go/snapshot <domain> list.
restore did nothing No <archive> was given. The command exits silently. Pass a date tag or a snapshot ID.
Restore overwrote newer files RestoreDir is /, so files return to their original paths. Limit the restore with --www, --mail, or a path. Or set RestoreDir to a scratch folder to inspect first.
jq, pv, restic, or rclone: command not found A requirement is missing. Install it. See Requirements.
MySQL dump still taken with --skip mysql The option works only on restores. See Notes for maintainers.
/home/<domain>/log is empty after a backup The command wipes that folder before and after every backup. Don't keep other files there.
Disk fills up in /var/snapshot No remote is configured, so snapshots stay local. Configure the snapshot rclone remote.
Mailbox restored but doesn't exist in the panel <user>@<domain> restores the folder only. Run /go/snapshot <domain> restore <archive> --mail, or restoremail.

Details

What it does

  1. Re-runs itself with sudo if not root, and logs the call.
  2. Takes the lock, for the modes that use it.
  3. Cleans restic's cache, then reads /var/go/etc/snapshot.conf.
  4. Decides where the repository is (remote or /var/snapshot) and what to back up (MinIO, cPanel, or GoAdmio).
  5. Dispatches on the first argument. See the diagram below.
  6. Removes the lock file.
flowchart TD
    A["snapshot args"] --> B{"First argument"}
    B -- "list" --> L["List accounts that have snapshots"]
    B -- "ends in .sql" --> Q["Restore one database dump"]
    B -- "contains /" --> P["Restore a file or folder"]
    B -- "contains @" --> M["Restore one mailbox folder"]
    B -- "any argument is --list" --> J["Print snapshots as id, tag, time"]
    B -- "none or all" --> ALL["Back up every enabled account"]
    B -- "check" --> C["Verify repositories"]
    B -- "domain or user" --> D{"Second argument"}
    D -- "list" --> D1["List snapshots"]
    D -- "delete" --> D2["Delete repository"]
    D -- "restore" --> D3["Restore account"]
    D -- "none" --> D4["Back up account"]

Backing up a GoAdmio account

  1. Deletes and recreates /home/<domain>/log with include, mysql, postgre, and subdomain folders.
  2. Writes each subdomain's settings to log/subdomain/<name>.conf.
  3. Dumps each MariaDB database to log/mysql/<db>.sql and saves user|password-hash in <db>.pwd.
  4. Dumps each PostgreSQL database to log/postgre/<db>.sql and saves user|password in <db>.pwd.
  5. If the account has mail, runs /go/mailconf to write mailbox settings.
  6. Runs /go/siteconf to write log/include/site.conf.
  7. Saves a password line from /etc/shadow to log/include/shadow.
  8. Makes sure the repository exists, and recreates it if it can't be read.
  9. Applies the retention rules (forget, then prune).
  10. Creates the snapshot of /home/<domain>, tagged with today's date.
  11. Deletes everything inside log.
  12. Stores the current time in the account's SnapshotStamp field, whether or not the backup succeeded.

MinIO and cPanel backups skip steps 1 to 7 and 11 and snapshot the folder as it is.

What a snapshot contains

Item Source
Site files, mail, etc, sqlite, and other folders /home/<domain>
log/include/site.conf Account settings, used by create to recreate the account
log/include/shadow Saved system password line
log/subdomain/<name>.conf Subdomain settings
log/mysql/<db>.sql and .pwd MariaDB dump and user password hash
log/postgre/<db>.sql and .pwd PostgreSQL dump and user password
mail/<user>.conf Mailbox settings from /go/mailconf

Restoring an account

  1. Looks up <archive> first as a tag, then as a snapshot ID. If neither exists, prints the snapshot list and stops.
  2. Runs restic restore into RestoreDir, limited by --www, --mail, or --database if given.
  3. If log/include/site.conf was restored, runs create <domain> to recreate the account, and hides the account in the panel while the recovery runs.
  4. Recreates subdomains (full restore or --www).
  5. Recreates mailboxes from the restored mail folders (full restore or --mail).
  6. Restores the saved system password line.
  7. Deletes the domain's MySQL/MariaDB records, re-creates each database and user, and imports the dump (full restore or --database). Then does the same for PostgreSQL.
  8. Runs ssl and fix, empties log, and shows the account in the panel again.

Retention

Before each backup, restic forgets snapshots that are older than 24 hours and not covered by: 7 daily, 4 weekly, or 12 monthly snapshots. It then prunes the repository. Snapshots taken on the same day share the same tag.

Notes for maintainers

Issue Why it matters Suggested fix
Repository password is hard-coded as GoPanel Anyone with repository access can read every snapshot. Use a random per-server secret stored in a root-only file.
A failed restic snapshots leads to rclone purge and a new init (in BACKUP and CHECK) A transient network, lock, or password error deletes the whole history. Local repositories are purged too. Re-initialize only when restic reports that the repository doesn't exist (recent versions exit with code 10). Never purge on other errors.
$Username is never set, so grep "$Username:" /etc/shadow | head -n 1 takes the first line of /etc/shadow Normally that is root's password hash, saved into every account's snapshot. Restore then appends that line to /etc/shadow. Look up the username from the Site table, skip when empty, and match with ^$Username:.
--skip mysql is checked inside BACKUP, which only receives the domain The option never works on backups. Pass the original arguments to BACKUP, or read the option once at the top.
PHPVersion="${Row[4]}" uses an array that doesn't exist Every subdomain's PHP version is saved empty. Use $PHPVersion.
The lock file is deleted at the end of every run, and by list, restore errors, and similar paths A single-domain run, which never took the lock, removes a running full backup's lock. Remove the lock only in the instance that created it (the existing trap is enough).
Several modes exit 1 after success Callers treat success as failure. Use exit 0 on success.
forget and prune run before the new backup Old snapshots are removed even if the new backup then fails. Pruning on every run is slow. Back up first, and prune only after success or on a schedule.
restic's exit status is never checked SnapshotStamp is updated and the run looks successful after a failed backup. Check each restic command and stop on failure.
rm -rf /home/<domain>/log before and after Wipes anything else stored there, and leaves dumps in the account's home while backing up. Stage dumps in a root-only temporary folder outside the account.
all restore <archive> restores every domain One typo restores the whole server, overwriting files. Require a domain, or ask for confirmation.
Restored .conf files are loaded with source Anything written in them runs as root during a restore. Parse them as data instead of sourcing them.
MariaDB root password on the command line; PostgreSQL passwords saved in plain text Visible in ps and readable by anyone who opens a snapshot. Use a credentials file or socket authentication, and store hashes where possible.
Domain used directly in SQL and unquoted in commands A quote or space in a value breaks the command and can be abused. Validate the domain against ^[a-z0-9.-]+$ and quote every variable.
<user>@<domain> restores files only Ownership isn't fixed and the mailbox isn't registered. Fix ownership, and recreate the mailbox with mail --action create.
OS and Parallel are set but never used Dead code. Remove them.

See also

Command Description
recover Restore a deleted account from its latest snapshot
backup Create a backup for all GoAdmio accounts (local and remote)
domain Change the primary domain of a hosting account
create Create a GoAdmio account from the command line
restoremail Recreate mail accounts from folders on disk
mail Create an email address in GoAdmio via the command line
fix Fix GoAdmio file and folder permissions
ssl Install an SSL certificate for a domain in GoAdmio