Config file reference
Every key that ~/.safegrd/config.yaml accepts is listed below. Commands read the
file named by --config, or ~/.safegrd/config.yaml when you leave it out.
The file must be readable by its owner only (0600). A command refuses a file with wider permissions.
safegrd daemon install writes the file's full path into the service definition, so
the service finds it from any working directory.
Run safegrd config validate to check the file's syntax and structure without
running anything. Run safegrd doctor to check that credentials resolve and the
storage sink is reachable.
This page is checked against the CLI on every build. The build fails if a key exists and is not listed here, or if a key listed here does not exist.
config.yaml, top to bottom. A surface takes storage and defaults unless it sets its own.
Here is a complete file for one database and one folder, and what config validate prints for it:
server:
url: https://safegrd.dev
node:
id: node-c97be882
name: prod-app-01
storage:
type: s3
bucket: acme-backups
region: eu-central-1
worm_mode: COMPLIANCE
retention_days: 14
encryption:
public_key: age1ajk3ed465rhu7qmtm9cu6jf6fcle6j4j3ttxwpd0sjd3mqsdgslstgy2sg
key_path: keys/daemon.key
defaults:
schedule: "@daily"
surfaces:
- id: shop
type: postgres
schedule: "at 02:00"
credential: {from: env, name: SHOP_DB}
- id: uploads
type: files
roots: [/srv/app/uploads]
$ safegrd config validate
Config validation
[PASS] Config Permissions : 0600 verified at /home/app/.safegrd/config.yaml
[PASS] Encryption Public Key : valid Age public key (age1ajk3ed46...)
[PASS] Storage Configuration : S3 bucket acme-backups configured
[PASS] defaults.schedule : "@daily" runs every 24h
[PASS] Surface shop schedule : "at 02:00" runs every 24h
[PASS] Surface shop (postgres) : configured
[PASS] Surface uploads (files) : 1 root path(s) specified
All critical checks passed.
credential: {from: env, name: SHOP_DB}, the database URL comes from the SHOP_DB environment variable, so the password is not in the file.server and node
safegrd init and safegrd enroll write these. You rarely need to edit them.
| Key | What it does |
|---|---|
server.url | The address of SafeGrd's server. Default https://safegrd.dev. The CLI contacts it only when server.token is set. You can also set SAFEGRD_SERVER_URL. |
server.token | The host's token from enroll (sg_tok_…). Without a token the host runs standalone. It still backs up, prints that it is standalone, and reports nothing to SafeGrd. You can also set SAFEGRD_SERVER_TOKEN. |
node.id | The id the host reports under. Its snapshots go in the bucket under <prefix>/<node.id>/. enroll sets it. |
node.name | The name enroll registers the host under. The console shows it. |
node.project | The project the host was enrolled into. If the project has a bucket set in the console, the host's backups go there. The CLI then refuses a storage.bucket that names a different bucket, and a secret_access_key when SafeGrd holds the bucket's key. If the project has no bucket, the bucket named here becomes the project's bucket. SafeGrd keeps a fingerprint of its key, not the key itself. |
storage
Where snapshots are written. A surface can replace the whole block with a storage block of its own.
| Key | What it does |
|---|---|
storage.type | s3, local, sftp (an SFTP server) or hosted. With hosted, snapshots go to SafeGrd's locked bucket through URLs that SafeGrd's server signs for each request (Hosted storage). Default local. |
storage.bucket | The S3 bucket. You can also set SAFEGRD_STORAGE_BUCKET. |
storage.region | The bucket's region. You can also set SAFEGRD_S3_REGION, which is read before AWS_REGION. |
storage.endpoint | An S3-compatible endpoint, such as MinIO, Backblaze B2, Wasabi or DigitalOcean Spaces. Leave it out on AWS. You can also set SAFEGRD_S3_ENDPOINT. |
storage.prefix | The key prefix inside the bucket. init writes safegrd/snapshots. To restore on another machine, use the same value there. |
storage.node_id | The folder under prefix. Defaults to node.id. Set it only to read another host's snapshots. |
storage.retention_days | How many days each snapshot is locked under Object Lock. It applies to every surface without a retention_days of its own. Default 14. A lock cannot be shortened once it is set, so choose the number with care (Storage and retention). |
storage.expire_after_lock | Off by default. Set it to true and, once a day, the daemon deletes the snapshots in your bucket whose Object Lock ended more than a day ago by the bucket's clock. It keeps each surface's newest min_keep snapshots, and the last known-good snapshot before an open anomaly. The bucket credentials need s3:DeleteObjectVersion and s3:GetObjectRetention (Storage and retention). |
storage.min_keep | How many of each surface's newest snapshots pruning keeps, whatever their locks say. Default 3. safegrd prune --min-keep sets it for one run. |
storage.worm_mode | COMPLIANCE (the default): nobody can delete a snapshot before its lock date. GOVERNANCE: a user or role with the bypass permission can. NONE: for a sink with no Object Lock. Write the value exactly as shown, in upper case. sftp storage accepts only NONE. |
storage.storage_class | The S3 storage class for each archive: STANDARD (the default), STANDARD_IA or GLACIER_IR. The manifest is always STANDARD. Each drill reads one copy and pays that class's retrieval price (details). |
storage.local_path | The directory for type: local. Default ./safegrd-storage. |
storage.sftp.host | The SSH server for type: sftp (An SFTP server). |
storage.sftp.port | Its SSH port. Default 22. |
storage.sftp.user | The account that writes the backups. |
storage.sftp.path | The directory on the server that backups go in, either absolute or relative to the account's login directory. To restore on another machine, use the same value there. |
storage.sftp.password | The account's password. Takes env:VAR or file:/path. |
storage.sftp.private_key | The account's private key, usually file:/path/to/key. The CLI cannot read a key that has a passphrase. |
storage.sftp.known_hosts | The full path to an OpenSSH known_hosts file that lists the server. The CLI refuses a server the file does not list, or lists with a different key. |
storage.sftp.host_key | Use this in place of known_hosts: the server's host key fingerprint, as ssh-keygen -lf prints it (SHA256:...). |
storage.access_key_id | The S3 access key. Instead of writing it here, you can set SAFEGRD_S3_ACCESS_KEY (or AWS_ACCESS_KEY_ID), or have SafeGrd hold the bucket credential. |
storage.secret_access_key | The S3 secret key. Instead of writing it here, you can set SAFEGRD_S3_SECRET_KEY (or AWS_SECRET_ACCESS_KEY). |
storage.force_path_style | Use path-style bucket addressing. MinIO needs it. |
storage.layout | hosted, with type: s3, reads SafeGrd's hosted storage bucket directly with that bucket's key. SafeGrd uses it for its own recovery. list, restore and verify work, and a backup is refused. To restore hosted backups without SafeGrd, keep a copy in your own bucket with safegrd export (runbooks). |
storage.iam_role_arn | An IAM role the CLI assumes through STS to reach the bucket, in place of static keys. |
copies
Every backup can also be written to up to two more S3 buckets. Each entry is a full storage block with a name (A second bucket). If the project names buckets in the console, those replace this list.
| Key | What it does |
|---|---|
copies[].name | The copy's name: 1 to 32 lowercase letters, digits and dashes. --from-bucket and the console refer to the copy by this name. |
copies[].type | s3. It is the only kind of copy. |
copies[].worm_mode | Required: COMPLIANCE, GOVERNANCE or NONE. A copy does not inherit the first bucket's lock mode. |
copies[].retention_days | How many days each backup is locked in this bucket, counted from when it was taken. Defaults to the surface's. |
copies[].expire_after_lock | Once a day, the daemon deletes backups from this bucket whose lock has ended. It keeps the bucket's min_keep newest (default 3). Off unless you set it here. The first bucket's setting does not carry over. |
copies[].bucket | The bucket, with region, endpoint, prefix, storage_class, force_path_style, access_key_id and secret_access_key as in storage. The two keys take env:VAR or file:/path. A copy cannot use the same bucket and prefix as the first bucket. |
encryption
| Key | What it does |
|---|---|
encryption.public_key | The Age recipient every snapshot is encrypted to (age1…). You can also set SAFEGRD_PUBLIC_KEY. |
encryption.key_path | The identity file that decrypts the snapshots, kept at mode 0600. The private key itself is never written into config.yaml. You can supply it with SAFEGRD_PRIVATE_KEY instead. |
encryption.custody | How the key is managed. try, enroll and init write it. safegrd is a SafeGrd-managed key: SafeGrd keeps it sealed and releases it only to your enrolled hosts. local is a customer-managed key: only you can decrypt these backups. With safegrd, enrolling again sends the key so that SafeGrd holds it for the new host. If this is empty, the key was put on the host by hand, and the CLI never sends it. |
daemon
Settings for the daemon (Daemon).
| Key | What it does |
|---|---|
daemon.interval | How often the daemon looks for due work. Default 5m. |
daemon.state_dir | Where the daemon keeps its state and locks. Default ~/.safegrd. Do not put it on a network filesystem. |
daemon.metrics_addr | The address where the resident daemon serves Prometheus metrics at /metrics, such as 127.0.0.1:9847. daemon run --once does not serve them (the metrics). |
daemon.ping_url | A Healthchecks.io or Cronitor check URL. The daemon pings it after every pass over the surfaces, --once included. It pings the URL itself, or URL/fail when the pass could not run. Takes env:VAR or file:/path. |
daemon.updates | console (the default) or off. With console, the daemon downloads each new release and checks its signature. It installs the release when an owner or admin clicks Update in the console. From the console you can also send the host back to the release it ran before. Only hosts set up with install.sh update this way (Updates from the console). |
daemon.export_to.bucket | A bucket you own. When it is set, the daemon runs safegrd export --to-bucket on daemon.export_to.schedule, after that pass's backups. It copies every snapshot, still encrypted and with its lock date, and skips what is already there. The console shows on the host when the last copy was made. Set this or daemon.export_to.dir, not both (Keep a copy of hosted backups). |
daemon.export_to.endpoint | The bucket's S3 endpoint (--to-endpoint). Leave it out on AWS. |
daemon.export_to.region | The bucket's region (--to-region). Default us-east-1. |
daemon.export_to.prefix | The key prefix in the bucket (--to-prefix). Default safegrd/snapshots, which is the prefix the runbook's recovery config uses. |
daemon.export_to.worm_mode | The bucket's Object Lock mode (--to-worm-mode): COMPLIANCE (the default), GOVERNANCE, or NONE for a bucket without Object Lock. A bucket without Object Lock refuses a locked copy, and the export stops before it copies anything. |
daemon.export_to.access_key_id | An access key that can list and write to the bucket. Takes env:VAR or file:/path. Set it together with secret_access_key, or leave both out to use the standard AWS environment, as the command does. |
daemon.export_to.secret_access_key | Its secret. Takes env:VAR or file:/path. |
daemon.export_to.force_path_style | true for MinIO. It puts the bucket's name in the path instead of the host name. |
daemon.export_to.dir | A local directory to copy to, instead of a bucket (--to-dir). Runbook 4 restores from it. |
daemon.export_to.schedule | How often the copy runs, written like a surface schedule: @daily (the default), 6h, 0 3 * * *. If a run fails, the daemon prints the error to stderr and tries again an hour later. A failed copy does not stop the backups. |
daemon.updates_url | A mirror the daemon downloads releases from, in place of https://github.com/safegrd/cli/releases/download. It has to serve <url>/v<version>/<file>. Releases from a mirror get the same signature check. |
defaults
What every surface inherits unless it sets its own.
| Key | What it does |
|---|---|
defaults.schedule | @hourly, @daily, @weekly, or an interval such as 6h. The shortest interval is one hour, so a schedule cannot fill the bucket with locked objects. |
defaults.timezone | Accepted, not acted on. Schedules run as intervals from the last success, not by wall-clock time. |
defaults.keep_daily | Lock the first backup of each UTC day for this many days (GFS). |
defaults.keep_weekly | Lock the first backup of each ISO week for this many weeks (GFS). |
defaults.keep_monthly | Lock the first backup of each month for this many months. |
surfaces[]
One entry for each surface the daemon backs up. Each entry appears on its own in the console and counts as one surface on your plan.
| Key | What it does |
|---|---|
surfaces[].id | A stable identifier. If you change it, SafeGrd sees a new surface. |
surfaces[].type | postgres, mysql, mongodb, sqlite, files, email or laravel. |
surfaces[].name | The name shown in the console. Defaults to the id. |
surfaces[].schedule | Overrides defaults.schedule. Takes an interval, a time of day (at 02:00) or a cron line (schedules). |
surfaces[].skip_if_unchanged | With true, an incremental run that finds nothing changed since the last backup writes no new one. The console shows the surface as unchanged since that backup, instead of Overdue. Works with your own bucket and local storage only (details). |
surfaces[].clock | The clock that a time of day or cron line in schedule, and blackout, follow: utc (the default) or local. |
surfaces[].blackout | Times of day when no scheduled backup starts, such as ["22:00-02:00"]. They are read in UTC unless you set clock: local. A backup that falls due waits for the window to end (details). |
surfaces[].retention_days | Overrides storage.retention_days for this surface. |
surfaces[].keep_daily | Overrides defaults.keep_daily. |
surfaces[].keep_weekly | Overrides defaults.keep_weekly. |
surfaces[].keep_monthly | Overrides defaults.keep_monthly. |
surfaces[].pre_backup | A shell command the daemon runs before each backup of this surface, for example to flush a cache or pause a writer. It has 10 minutes. If it fails, no backup is taken, and the hook's own output in the daemon's log says why. The daemon sets SAFEGRD_SURFACE_ID and SAFEGRD_SURFACE_TYPE for it. |
surfaces[].post_backup | A shell command the daemon runs after every attempt, whether it succeeded or not, so you can resume whatever pre_backup paused. SAFEGRD_BACKUP_STATUS is success or failed, and SAFEGRD_SNAPSHOT_ID names the snapshot. If the command fails, the failure is reported and the backup stands. |
surfaces[].pre_backup_on_error | What happens when pre_backup fails. skip (the default) takes no backup. retry runs the hook again after 10 seconds, then after 20, and skips if it still fails. continue takes the backup anyway and logs a warning. |
surfaces[].ping_url | A Healthchecks.io or Cronitor check URL for this surface. The daemon pings URL/start before each backup, URL after it, and URL/fail after one that failed or was not recorded. The body is one line saying what happened. Takes env:VAR or file:/path. A failed ping is logged as a warning and changes nothing else. |
surfaces[].post_drill | A shell command the daemon runs after each Fire Drill of this surface. SAFEGRD_DRILL_STATUS is passed, shallow, failed or blocked, and SAFEGRD_SNAPSHOT_ID names the snapshot. SAFEGRD_SANDBOX_URL is set while the sandbox still holds the restore. If the command fails, the failure is logged and nothing else changes. |
surfaces[].database_url | A database surface's connection URL. Write it out, or use env:VAR or file:/path to keep it out of this file, which is how init --database-url writes it. If the host should not keep the password in a variable or a file, use credential. A SQLite surface gives its file here, as sqlite:///var/lib/app/app.db. There is no path key. |
surfaces[].credential.from | Where a database or mailbox surface's credential comes from. For a database it is the whole connection URL, and for a mailbox the password. With safegrd, SafeGrd holds it encrypted and gives it only to this host when the surface backs up. Nothing is set on the host, and it is never written to this file. With env, command or file, it stays on this host, as described below. A credential has one source. The CLI refuses a credential block together with a database_url. If the variable, command or file it names cannot be read, that surface fails, and the CLI does not fall back to anything else. |
surfaces[].credential.name | With from: env, the environment variable that holds it. Under a service, set it in the service's environment (details). |
surfaces[].credential.run | With from: command, a command that prints the secret, such as a secret manager's CLI. It runs under /bin/sh for up to 30 seconds. If it fails, that surface fails (details). |
surfaces[].credential.path | With from: file, a file whose contents are the secret, such as a mounted secret. |
surfaces[].roots | The directories a files surface backs up. A laravel surface takes one: the app's root, where artisan and .env are (Laravel). |
surfaces[].excludes | Glob patterns for what a files surface leaves out. On a laravel surface they are paths from the app's root, such as storage/app/exports. |
surfaces[].migrations_table | The table where a laravel surface's app records its migrations, if config/database.php names one other than migrations. The drill checks that table. |
surfaces[].format | How a files or database surface is stored: repo (incremental, each run uploads only what changed) or tar (one archive per backup). Unset means repo. A mailbox is always one archive. For a surface added in the console, the Backup type you chose there is written here. See incremental file backups and databases. |
surfaces[].erasures | The tables, as schema.table, whose deleted rows are deleted again when you restore an older backup. It adds a trigger to each table and a safegrd schema to the database. For PostgreSQL, with local storage, your own bucket or hosted storage. See the erasure record. |
surfaces[].change_log | Makes a PostgreSQL surface skip reading tables that nothing has written to since its last run. It adds a trigger to each table and a safegrd schema to the database. See the change log. |
surfaces[].roles_without_passwords | Backs up the roles a PostgreSQL surface's schema names without their password hashes. By default the hashes are included. A surface SafeGrd backs up for you has no such switch. See roles, owners and grants. |
surfaces[].recovery_doc_sealed | Encrypts the recovery document written beside each snapshot to the surface's recipient. By default it is plain text, so you can read it without SafeGrd. It holds no secret. See the recovery document. |
surfaces[].compression | How hard the surface's backups are compressed, from zstd:1 (fastest) to zstd:19 (smallest). Every level writes the same format, so a restore needs no setting. Default: zstd's own default, about zstd:3. |
surfaces[].parallel | How many connections an incremental PostgreSQL or MySQL backup reads tables over at once, all in one snapshot. For an incremental MongoDB backup, how many collections it reads at once. A restore or a sandbox drill loads tables over as many connections, capped by the server's free connections (for MongoDB, insertion workers per collection). Such a restore is not one transaction. If it fails, drop the target and restore again. MySQL reads in parallel only with the FLUSH_TABLES or RELOAD privilege. Without it, the backup reads over one connection and says why. A full backup (one archive) reads and restores one table at a time. Default 4. For PostgreSQL, 1 loads the restore in one transaction. |
surfaces[].one_filesystem | With format: repo, stay on each root's filesystem. Default yes when a root is /, no otherwise. |
surfaces[].watch.url | With a watch: block, a PostgreSQL, MySQL or MongoDB surface checks the backups another tool writes, such as Coolify's, instead of backing up a database. Set this to s3://bucket/prefix or a directory on the host. Set the surface's schedule to how often that tool writes (PostgreSQL, MySQL, MongoDB). |
surfaces[].watch.endpoint | The bucket's S3 URL, for a store other than AWS S3 (Cloudflare R2, Backblaze B2, MinIO). |
surfaces[].watch.region | The bucket's region, as the store shows it. |
surfaces[].watch.access_key | An access key id that can list and read the prefix, as env:VAR or file:/path. It needs no write or delete permission. |
surfaces[].watch.secret_key | Its secret access key, as env:VAR or file:/path. |
surfaces[].watch.match | A glob that a backup's file name must match, such as pg-dump-*.dmp, for when the location holds other files too. |
surfaces[].object_store.endpoint | When a files surface's one root is s3://bucket/prefix, it reads that bucket over the S3 API (details). This is the store's S3 URL. For Supabase Storage it is https://PROJECT.storage.supabase.co/storage/v1/s3. Leave it empty for AWS S3. |
surfaces[].object_store.region | The bucket's region, as the store shows it. |
surfaces[].object_store.access_key_id | The store's access key id, as env:VAR or file:/path. |
surfaces[].object_store.secret_access_key | The store's secret access key, as env:VAR or file:/path. It opens every bucket in the store, so it is never written into the config itself. |
surfaces[].host | A mailbox's IMAP server. Default imap.gmail.com. |
surfaces[].port | Its TLS port. Default 993. |
surfaces[].username | The mailbox login. |
surfaces[].folders | The folders to back up. Default: all but spam and trash. |
surfaces[].ca_file | A PEM bundle to trust for the mail server's certificate, on top of the system roots. Use it for a server behind a private CA. Default: SAFEGRD_EMAIL_CA_FILE, if set. |
surfaces[].storage | A whole storage block for this surface alone, with the same keys as above. |
surfaces[].copies | Which of the copies this surface writes to, by name. Leave it out to write to all of them, or set [] for none. |
surfaces[].encryption | An encryption block for this surface alone, to encrypt it to a different key. |
surfaces[].drill.sandbox_url | An empty database of the same engine that this surface's Fire Drills restore into. The drill refuses one that holds tables, and empties it afterwards. Without it, on a plan with sandbox drills, a Postgres surface restores into a throwaway cluster that the daemon starts from the host's PostgreSQL server, if one is installed. Otherwise drills run in memory. |
surfaces[].drill.source | primary (the default) drills the surface's own bucket. rotate drills the next of its buckets each time, so every copy is restored in turn. |
surfaces[].drill.checks[].name | The name the drill record and the console show for one of your own checks. The check runs against the sandbox after each drill that restores into a database. If a check fails, the drill fails (details). |
surfaces[].drill.checks[].sql | A query, run in a read-only transaction. The first column of its first row is compared with expect. |
surfaces[].drill.checks[].expect | The value the query must return, or a comparison: "0", "true", "> 0", ">= 1000", "!= 0". Numbers compare as numbers. |
surfaces[].drill.checks[].command | Use in place of sql: a command run through sh -c, with SAFEGRD_SANDBOX_URL, SAFEGRD_SNAPSHOT_ID and SAFEGRD_SNAPSHOT_CREATED_AT (when the backup was taken, RFC 3339 UTC) set. The check passes if it exits 0. |
surfaces[].drill.checks[].timeout_seconds | How long the check may run. Default 60 for a query, 300 for a command. |
surfaces[].drill.keep_failed_sandbox | Set it to keep the sandbox for 24 hours when a drill restores the snapshot and then fails a check (the digest or the row counts). The drill prints where the sandbox is, without the password. A sandbox_url database holds back the next drill until the 24 hours are up, and the first drill after that empties it. A throwaway cluster keeps running, and the daemon removes it after the 24 hours. A restore that fails is rolled back, so there is nothing to keep. The drill's record says the sandbox was kept. Default false. |
surfaces[].wal.window_days | How many days back a surface's point-in-time archive can restore to. Its base backups and bundles are locked for that long (PostgreSQL, MySQL, MongoDB). The wal: block turns WAL archiving on, and wal: {} keeps every default. Default 7. |
surfaces[].wal.base_every_days | How often the daemon takes a base backup. For PostgreSQL that is pg_basebackup. For MySQL and MongoDB it is a mysqldump or mongodump that records its position in the log. A restore replays every WAL file since its base, so more frequent bases make a busy database restore faster. Default 7. |
surfaces[].wal.incremental_every_days | How often the daemon takes an incremental base backup between full ones. It holds only the blocks changed since the newest full, and is locked until that full is. Needs PostgreSQL 17 or newer with summarize_wal = on. Otherwise the daemon says why and waits for the next full base. Default 0, full bases only. |
surfaces[].wal.bundle_mb | Once a day, the daemon locks the unlocked WAL into one bundle. It does so sooner once the WAL passes this many MiB. Default 1024. |
surfaces[].wal.drill_every_days | How often the daemon drills the archive. A PostgreSQL archive goes into a throwaway cluster on the host, run by a PostgreSQL server of the same major version. A MySQL or MongoDB archive goes into the surface's drill.sandbox_url. The drill restores to the newest restore point, counting each table, and also to the end of the archive. A drill that fails or cannot run is tried again a day later. Default 7. |
surfaces[].wal.interval_seconds | For a SQLite surface, how often the resident daemon copies the database's newly committed WAL frames. A restore gets to within this many seconds of the moment you ask for (details). Default 1. For a MySQL or MongoDB surface, how often the daemon pushes what the binary log or oplog committed since the last push. Default 5. |
surfaces[].wal.server_id | For a MySQL surface, the replica id the daemon gives the server when it reads the binary log. Set it if the id derived from the surface id is already a replica's own server_id. Default: derived from the surface id. |
surfaces[].wal.checkpoint_mb | For a SQLite surface, the WAL size at which the daemon checkpoints the database. While the daemon follows the WAL, the application's own checkpoints cannot shrink it past what the daemon has copied. Default 4. |
surfaces[].wal.spool | For PostgreSQL. When on, archive_command returns once a WAL file is copied into the spool and synced, and the daemon uploads from the spool (details). Default off. |
surfaces[].wal.spool_dir | Where the spool lives. The user PostgreSQL runs as writes there, and the daemon's user reads and deletes there. Default wal-spool in the state directory. |
surfaces[].wal.parallel | How many spooled WAL files the daemon uploads at once, and how many a restore fetches ahead. Default 4. |
surfaces[].wal.queue_max | The most WAL that can wait on the host for the archive, such as 8GB. Past that, the oldest is dropped without being archived, so pg_wal cannot fill the disk. wal status lists what was dropped, and SafeGrd sends an alert. Default: no limit. |