snapshot
Back up, list, check, restore, and delete restic snapshots of hosting accounts, locally or on remote storage
- Command:
/go/snapshot - Category: Backup
- Required argument: None. With no argument it backs up every account. What the command does depends on the first argument.
- Output: Progress text.
--listprintsid|tag|timelines. - Last updated: 2026-11-19
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:
- backs up each account's home folder (or its S3 folder on MinIO servers)
- adds database dumps, mailbox settings, subdomain settings, and account settings to every snapshot
- keeps the last 24 hours of snapshots, plus 7 daily, 4 weekly, and 12 monthly ones
- restores a whole account, or only its website files, mail, or databases
- restores a single file, folder, database dump, or mailbox
- lists, verifies, and deletes the repositories
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
- Re-runs itself with
sudoif not root, and logs the call. - Takes the lock, for the modes that use it.
- Cleans restic's cache, then reads
/var/go/etc/snapshot.conf. - Decides where the repository is (remote or
/var/snapshot) and what to back up (MinIO, cPanel, or GoAdmio). - Dispatches on the first argument. See the diagram below.
- 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
- Deletes and recreates
/home/<domain>/logwithinclude,mysql,postgre, andsubdomainfolders. - Writes each subdomain's settings to
log/subdomain/<name>.conf. - Dumps each MariaDB database to
log/mysql/<db>.sqland savesuser|password-hashin<db>.pwd. - Dumps each PostgreSQL database to
log/postgre/<db>.sqland savesuser|passwordin<db>.pwd. - If the account has mail, runs
/go/mailconfto write mailbox settings. - Runs
/go/siteconfto writelog/include/site.conf. - Saves a password line from
/etc/shadowtolog/include/shadow. - Makes sure the repository exists, and recreates it if it can't be read.
- Applies the retention rules (
forget, thenprune). - Creates the snapshot of
/home/<domain>, tagged with today's date. - Deletes everything inside
log. - Stores the current time in the account's
SnapshotStampfield, 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
- Looks up
<archive>first as a tag, then as a snapshot ID. If neither exists, prints the snapshot list and stops. - Runs
restic restoreintoRestoreDir, limited by--www,--mail, or--databaseif given. - If
log/include/site.confwas restored, runscreate <domain>to recreate the account, and hides the account in the panel while the recovery runs. - Recreates subdomains (full restore or
--www). - Recreates mailboxes from the restored mail folders (full restore or
--mail). - Restores the saved system password line.
- 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. - Runs
sslandfix, emptieslog, 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 |