Docs / Surfaces

Surfaces

A surface is one thing you back up: a database, a file tree or a mailbox. Each Fire Drill tests one surface. Every surface goes through the same steps. The data is streamed, compressed with zstandard, encrypted to your age public key and written to locked storage. Only the first step (how the data is read) and the last (how a drill checks it) change from one kind of surface to the next.

The stream is encrypted on the host that read it, so no plaintext crosses a third-party network. It is not written to disk either, with one exception. A SQLite surface is first copied to a temporary file on the same host, readable only by its owner (SQLite). The file is deleted as soon as it is uploaded.

Every surface goes through the same steps on your host: it is read with the surface's own tools from one snapshot, compressed with zstandard and encrypted to your age public key. The encrypted bytes go from your host to storage locked under Object Lock. SafeGrd receives a record of each run, not the data. your host Read the surface its own tools, one snapshot Compress zstandard Encrypt to your age public key encrypted bytes Storage locked under Object Lock SafeGrd a record of each run
The steps inside the dashed line run on your host. Storage only ever receives encrypted bytes, and SafeGrd receives a record of each run (when it ran, sizes, row counts), not the data.

The surfaces

SurfaceWhat is capturedThe host needs
PostgreSQLSchema from pg_dump, rows over binary COPY, one snapshotpg_dump at least as new as the server
MySQL and MariaDBmysqldump --single-transactionThe MySQL client
MongoDBmongodump --archiveThe MongoDB Database Tools
SQLiteOne committed state, through VACUUM INTONothing
FilesA directory tree, incremental: each run uploads only what changedRead access to the tree
EmailEvery message of an IMAP mailbox, as RFC 5322The mailbox's password or app password
WordPressThe site's database and files in one snapshot, from a plugin. Each backup uploads what changed.The SafeGrd Backup plugin. No host to set up.
LaravelThe app's database, .env and storage/app in one snapshot. Each backup uploads what changed.The CLI on the app's host, reading its .env

If you need something that is not in the table, such as Microsoft 365 mail, MSSQL, Redis, ClickHouse, Elasticsearch, Windows hosts or Kubernetes volumes, request a surface.

What a Fire Drill proves, per surface

Every Fire Drill downloads the snapshot from your bucket and decrypts it with your key. What it checks after that depends on the surface.

SurfaceWhat the drill checks
PostgreSQLThe table count and every table's row count match the manifest, each table's binary COPY stream is readable, and the extensions are present. By default the drill runs in memory, with no database running anywhere. That checks the data but never runs the schema. To prove the schema loads, run a sandbox drill: with --sandbox-target, the snapshot is restored into a scratch database you name and counted there. The daemon does the same for a surface with drill.sandbox_url. On a plan with sandbox drills, a surface without one restores into a throwaway cluster that the daemon starts from the host's PostgreSQL server (Daemon).
MySQL and MariaDBThe dump ends with its completion line. Every table the manifest names is in it, with exactly the recorded number of rows. In memory, that checks the data. A sandbox drill (--sandbox-target mysql://… or drill.sandbox_url) loads the dump into an empty database, counts every table, and empties the sandbox again.
MongoDBEvery collection and view in the archive reached its end. Each collection's documents match the checksum mongodump wrote and the count in the manifest. A sandbox drill restores into an empty database with mongorestore, counts every collection, and drops them again.
SQLiteA real restore on every drill. The database file is written out and opened by the SQLite engine. It has to pass PRAGMA integrity_check, and every table's row count has to match the manifest. The file is deleted afterwards.
FilesThe whole snapshot is restored into a scratch directory, and every file has to match its SHA-256. The digest recomputed from the restored files has to match the one recorded at backup time. A --format tar archive is checked in memory against the manifest sealed inside it.
EmailThe message count matches the manifest, every message parses as RFC 5322 mail, and every message's SHA-256 matches. Nothing is written to disk.
LaravelThe database passes its engine's drill and every file matches its SHA-256. The .env in the snapshot holds an APP_KEY that Laravel's cipher accepts, and the dumped migrations table agrees with the migration files.

A drill does not replace a rehearsed restore, which shows that a person can get the data back. A drill shows that every snapshot reads back whole, without anyone having to remember to check.

Running several surfaces on one host

To back up more than one thing from a host, list the surfaces in the config file. The daemon runs each on its schedule.

surfaces:
  - id: "app-primary"
    type: "postgres"
    schedule: "@daily"
    credential:
      from: env
      name: "APP_DATABASE_URL"
  - id: "user-uploads"
    type: "files"
    schedule: "6h"
    roots: ["/var/www/uploads"]

Each entry registers as its own node and counts as one surface against your plan quota. Keep each id stable, because state, locks and snapshot history are keyed on it. A config with no surfaces: list still loads as one implicit Postgres surface, so an existing install needs no edit. The full shape is in Daemon.

Adding a surface to a host that is already running

The host's config is the one list of what it backs up, so you add a new surface there. You can do it from the console or by hand.

In the console, click Add surface on the host's row under Nodes, and give the surface's name, its schedule and where its credential comes from. Nothing changes on the host until you run safegrd claim there:

safegrd claim

safegrd claim adds the surfaces named for that host to its config. It only adds. A surface the config already has is left as it is, and the previous file is kept as config.yaml.bak. Running it again adds nothing. If SafeGrd holds the credential, you type it once in the console and it is never written to the file.

By hand, add an entry under surfaces:, as above.

Either way, a running daemon reads the changed config at the start of its next pass and backs up the new surfaces then. To start one straight away, click Back up now on the surface's row. With no daemon running, safegrd daemon run --once takes the first backups.