Backups and restore
Copies this page as Markdown with context, so an AI can walk you through your case step by step.
Backups are compressed and encrypted on your server. Only encrypted bytes ever reach ganyant.
What you can back up
| Type | Tool used | Keys in agent.toml |
|---|---|---|
| PostgreSQL | pg_dump --format=custom | dsn (or database with local authentication) |
| MySQL / MariaDB | mysqldump --single-transaction | database and defaults_file |
| MongoDB | mongodump --archive | uri (defaults to mongodb://127.0.0.1) |
| SQLite | sqlite3 .backup (consistent copy even while the app is writing) | path |
| Folder | tar | path |
Requirements per type
The agent uses each database’s official tools, which must be installed on the same server:
| Type | Install (Debian/Ubuntu) | Minimum permissions |
|---|---|---|
| PostgreSQL | apt install postgresql-client (same major version as the server or newer) | A role with CONNECT and SELECT on the database, or pg_read_all_data on PostgreSQL 14+ |
| MySQL / MariaDB | apt install mysql-client or mariadb-client | SELECT, SHOW VIEW, TRIGGER, LOCK TABLES, EVENT, plus PROCESS on MySQL 8 |
| MongoDB | MongoDB Database Tools | The backup role |
| SQLite | apt install sqlite3 | Read access to the file for the ganyant user |
| Folder | Included with the system | Read access to the folder for the ganyant user |
On Windows, the tool must be on the system PATH (for example C:\Program Files\PostgreSQL\16\bin). The agent runs as SYSTEM, so it can read local files.
Set up a job
- In Dashboard → Backups, create the job: name, type, server, frequency and retention.
- On the server, add a
[backup.NAME]section to/etc/ganyant/agent.tomlwith the same name as the job. - Restart the agent (
sudo systemctl restart ganyant-agent) and test the job withsudo ganyant-agent backup NAME --manual. If it works, the snapshot appears in the dashboard.
Examples
[vault]
passphrase = "the-passphrase-the-installer-generated"
# PostgreSQL
[backup.shop_prod]
dsn = "postgresql://backup:PASSWORD@127.0.0.1:5432/shop_prod"
# MySQL / MariaDB: the password goes in a separate file (see below)
[backup.wordpress]
database = "wordpress"
defaults_file = "/etc/ganyant/mysql.cnf"
# MongoDB, with the URI in a service environment variable
[backup.app]
uri = "env:MONGO_URI"
# SQLite
[backup.app_db]
path = "/srv/app/data.db"
# Folder
[backup.uploads]
path = "/var/www/uploads"MySQL credentials file, so the password never shows up on the command line:
# /etc/ganyant/mysql.cnf
[client]
user = backup
password = PASSWORD
host = 127.0.0.1
sudo chown ganyant:ganyant /etc/ganyant/mysql.cnf && sudo chmod 600 /etc/ganyant/mysql.cnfAny value can be read from an environment variable with the env: prefix. How to define variables for the service in Install the agent.
The agent checks jobs every 60 seconds and runs the ones that are due at low CPU and disk priority (nice and ionice), so they never compete with your application. The dump is streamed: you do not need free space equal to the database size, only room for the temporary encrypted file.
How each snapshot is protected
- Dump of the database or folder.
- Compression with Zstd (level 9).
- Encryption with XChaCha20-Poly1305 (libsodium secretstream), with a 256-bit key derived via Argon2id from your passphrase and a random salt per snapshot.
- BLAKE2b-256 hash of the whole encrypted file.
- Direct upload to Cloudflare R2 with a presigned URL valid for 15 minutes and limited to the exact declared size.
Keep your encryption passphrase in a password manager. The installer generates a random one and writes it to agent.toml. Without it nobody can decrypt your backups, including us. If you reinstall the server, copy the same passphrase into the new agent.toml to be able to restore older snapshots.
Restore
restore downloads the snapshot, verifies the BLAKE2b hash, decrypts and decompresses it, and writes the dump to the file you pass with --to. Then load it with each database’s own tool:
# the latest snapshot, or the one current at a given date
sudo ganyant-agent restore shop_prod --at latest --to ./shop_prod.dump
sudo ganyant-agent restore shop_prod --at "2026-11-14 03:00" --to ./shop_prod.dump
# PostgreSQL (custom format)
pg_restore --clean --if-exists --no-owner --dbname shop_prod ./shop_prod.dump
# MySQL / MariaDB (plain SQL)
sudo ganyant-agent restore wordpress --at latest --to ./wordpress.sql
mysql --defaults-extra-file=/etc/ganyant/mysql.cnf wordpress < ./wordpress.sql
# MongoDB
sudo ganyant-agent restore app --at latest --to ./app.archive
mongorestore --archive=./app.archive --drop
# SQLite: the restored file is the database
sudo ganyant-agent restore app_db --at latest --to ./data.db
# Folder: restored as a .tar
sudo ganyant-agent restore uploads --at latest --to ./uploads.tar
mkdir -p /srv/restore && tar -xf ./uploads.tar -C /srv/restoreIf the file was tampered with or is incomplete, verification fails and nothing is written. We recommend testing a restore in a separate environment at least once: a backup you have never restored is an assumption.
Decrypt a downloaded file
From the dashboard you can download any snapshot (.gya). To decrypt it on another machine with the agent installed (it asks for the passphrase):
ganyant-agent decrypt snapshot.gya --out shop_prod.dumpRetention and storage
Expired snapshots are deleted from storage automatically. Used space is shown in the dashboard; if you reach your plan’s limit, new backups are rejected before upload and you get an alert. A failed backup also triggers an alert with the error, on the channels you have configured.
Your own storage (Agency)
On Agency you can connect AWS S3, Wasabi, MinIO or your own R2. Credentials are stored encrypted with AES-256-GCM and those snapshots do not count toward ganyant storage.