Files and directory trees
You can back up any directory tree on a host. Each run uploads only what changed, and you can restore any version of any file on its own.
SafeGrd backs up a symlink as a symlink and does not follow it. A link that points outside the tree cannot pull the rest of the filesystem into your backup. FIFOs, sockets and device nodes are left out, and the backup lists each one.
Incremental backups
SafeGrd cuts each file into chunks of about 1 MiB, by content. A one-byte edit stores one chunk, and an insert does not shift the chunks after it. Chunks are compressed, encrypted on the host and gathered into packs of about 32 MiB. The packs are the objects in storage.
If a file's size, times and inode have not changed since the last run, SafeGrd does not read
it again. Every seventh run reads every file anyway. To do that now, pass --rescan.
Runs are grouped into monthly epochs. The first run of each UTC month uploads every file once. Every later run that month uploads only the chunks the month does not already hold, plus a few kilobytes of metadata. Months share nothing, so each object is locked once, when it is written, and no lock is ever extended.
A new epoch also starts when a host's cache is gone (a rebuilt host), when you increase
retention, or when you pass --new-epoch.
A root of / stays on one filesystem and leaves out /proc,
/sys, /dev, /run, /tmp,
/var/tmp, swap files and SafeGrd's own cache. A surface can list several roots,
as long as none is inside another.
Set exclusions with the surface's excludes, or with Leave out in the
console. Each run tells you how many entries were left out and which patterns matched them.
Back up a surface now
A surface backs up on its schedule. To take a backup now, run backup --surface. It
goes into the same history the daemon writes. backup --files backs up a directory
that is not a surface, as a separate history.
Find and restore one file
find lists every kept version of a file. A version is one content. It was first
seen in the snapshot that first held those bytes, and last seen in the last snapshot that did.
So a file that stayed the same for months is one version. A change of permissions alone does
not make a new version. When you restore a version, it gets that snapshot's permissions.
etc/nginx/nginx.conf (vm-root) # FIRST SEEN LAST SEEN SIZE SHA-256 SNAPSHOTS 3 2026-10-02 02:00 (current) 2.1 KiB 9f1c2a7b0d3e 2 2 2026-09-14 02:00 2026-10-01 02:00 2.0 KiB 4b8e11c0aa52 18 (2 epochs) 1 2026-09-01 02:00 2026-09-13 02:00 1.9 KiB 77d0e3f5b2c1 13
Versions are numbered from the oldest and printed newest first. Pass the number to
restore --version. With one --path and no --version or
--snapshot, restore takes the newest version.
Each snapshot is a point in time you can restore to, so the surface's schedule decides how far
apart they are. A daily surface gives you one point per day. To get a file as it was on a given
day, pick the version whose first-seen and last-seen dates bracket that day. Or pass that day's
snapshot id with --path.
- A directory pattern selects everything below it.
*,?and**work as wildcards. --deletedlists only the files the newest snapshot no longer holds, with the last snapshot that held each one.--jsonprints the same histories for scripts.
Paths you give to find and --path are relative to /. A
snapshot of one directory restores that directory's contents into the target, the same as an
archive of it does. A snapshot of /, or of several roots, restores each entry at
its path from /, under the target.
Restoring one file reads that file's chunks and the snapshot's metadata, and nothing else from
the tree. find and every restore run on the host that has the private key, and
decrypt there. Runbook 5 walks through it on a recovery
machine.
If the host's organization has other hosts, find searches the surfaces this host
has the key for, and tells you how many others it did not search. --surface <id>
searches one surface. With a SafeGrd-managed key, it fetches that surface's key for the search.
What is locked, and for how long
Each epoch gets two lock dates when it opens. Let T be the longest of
retention_days, keep_daily and keep_weekly, in days.
- Objects written by the month's first run are locked until the end of the month plus T,
plus 3 days. If the first run's own retention (the monthly copy, with
keep_monthly) ends later, that date plus 3 days applies instead. - Objects written by every later run are locked until the end of the month plus T.
A snapshot is kept at most as long as the objects it uses. So when a backup prints Locked until and a date, every byte it needs is locked until that date. Once the later objects expire, the month's first snapshot (the monthly copy) still restores from its own objects.
retention_days, keep_daily and keep_weekly. Not to scale. Each object gets its lock date once, when it is written.What it holds
Storage holds the kept monthly copies and about two months of changes. At the turn of each month it also holds one more full upload, while last month's objects are still locked.
A 200 GB tree with 2% daily change and 30-day retention holds about 500 to 650 GB on average. Daily archives of the same tree would hold about 6 TB. On hosted storage, the console warns you a week before the month turns if that upload will take you past 80% of your plan.
What the storage's holder can see
File names, contents, directory structure and which content repeats are encrypted on your host. Whoever holds the storage (you, or SafeGrd on hosted storage) can see the size of each pack and how many packs each run wrote. That shows how much changed. A single-archive backup shows only each archive's size.
Check a repository
check confirms three things for each snapshot:
- Every pack it names is in storage and agrees with its index.
- Every directory listing decodes.
- The content digest, recomputed from those, matches the one recorded at backup time.
--read-data also opens every chunk.
List, copy and prune
safegrd list shows incremental snapshots in their own table. For each one it gives
the month (epoch) it belongs to, whether its run opened the month or followed it, the size of
the whole tree it holds, and the bytes its run uploaded.
safegrd export copies a repository a whole month at a time, because a snapshot
needs every object of its month. restore --from reads the copy.
In your own bucket, safegrd prune deletes a month's expired objects once every
snapshot that could use them is past its retention. It never deletes from the month that holds
the surface's newest snapshot.
Restoring an incremental snapshot needs CLI v0.0.10 or later. An older CLI does
not see these snapshots. Run safegrd --version to see which you have.
What a restore brings back
This applies to CLI releases after v0.0.2. Earlier releases restore every
directory as 0755 and do not refuse a symlink in the target. Run safegrd --version
to see which you have.
| Property | Restored? |
|---|---|
| Contents | Yes. Every regular file is checked against the digest sealed at backup time. |
| Permissions | Yes, for files and directories, whatever the restoring shell's umask. A 0700 directory comes back 0700. |
| Modification times | Yes, for files, directories and symlinks. Restoring a one-directory snapshot into a new target gives the target that directory's mode and time. |
| Symlinks | Yes, as symlinks pointing where they pointed. |
| Ownership | Only when safegrd restore runs as root. Otherwise files belong to whoever ran it, and the restore tells you. Snapshots taken before 24 September 2026 did not record owners. |
| Hard links | No. Each linked name comes back as its own copy, so a tree full of hard links restores larger than it was. |
| Extended attributes, ACLs, SELinux labels, capabilities | No. If a tree depends on them (an SELinux-labeled web root, a binary granted setcap), reapply them after a restore. |
| setuid, setgid and sticky bits | Incremental backups: the sticky bit always, setuid and setgid when safegrd restore runs as root and puts the owner back. A 1777 directory comes back 1777. Backups with format: tar: no, only the permission bits. |
| Sparse files | Contents yes, sparseness no. Holes are written out in full. |
| FIFOs, sockets, device nodes | Not backed up. The backup lists each one it leaves out. |
When it finishes, safegrd restore prints what it restored and what it could
not: ownership when it did not run as root, and the properties above that are never
restored, so you know what to reapply.
The target must be empty or not exist yet. A restore first writes everything into a staging directory inside the target and checks every file against its SHA-256. Only when every file matches does it move them into place. If one does not match, nothing is left in the target, and the restore names the file.
What a Fire Drill checks
A drill restores an incremental snapshot whole into a scratch directory on the host, and checks every file against its SHA-256. It then reads the restored files back, recomputes the snapshot's content digest from them, and compares it with the digest SafeGrd recorded at backup time. The scratch directory is removed afterwards.
A single archive is checked in memory, and nothing is written to disk. Every entry has to match the manifest sealed inside the archive: names, types, symlink targets, the file count and byte volume, and a SHA-256 for every file.
To rehearse your team's own restore procedure, see the recovery runbooks.
A bucket as a surface
A files surface can read a bucket over the S3 API instead of a directory on the host. Use it for Supabase Storage, whose own backups leave out the uploaded files, or for any S3-compatible store.
Every object under the prefix is backed up as a file at its key. The content type the store
reported is sealed in the manifest. The archive restores into a directory like any other files
snapshot, or back into a bucket, and a Fire Drill checks it the same way. The keys reach every
bucket the store has, so pass them as env:VAR or file:/path.
A bucket is backed up as one archive per backup, because the incremental repository walks a filesystem. Each backup reads every object twice: once to hash it for the manifest and once to stream it. A store that meters egress bills two reads of the prefix per run.
On Supabase, the endpoint and region are on the project's Storage settings page, under S3 connection, and you create the keys there. A key reaches every bucket in the project and skips row-level security, so keep it on the host that backs up.
Supabase's folders are .emptyFolderPlaceholder objects, and they are backed up like
any file. Supabase lists what its storage.objects table holds. A row with no file
behind it (written by SQL, or restored before its file was uploaded) answers 404. The backup
stops at that row and names it, so it does not record a file it did not read.
Restore into a bucket
restore --target s3://bucket/prefix uploads a files snapshot into a bucket. It
takes the same --source-* flags as the backup. Each file goes to
prefix/path with the content type the backup recorded, so a PDF is served as
application/pdf again.
- Each file's SHA-256 is checked against the sealed manifest while it uploads. A file that differs is not written.
- Objects already at a key are replaced. Restore into a new prefix first to compare, then into the original one.
- A snapshot that holds symlinks is refused before anything is written, because a bucket has
no object for a link. Restore that one with
--target-dir.
A bucket SafeGrd backs up
If you have no server of your own, add the bucket in the console: Add surface, Back up on SafeGrd, then A bucket (Supabase Storage, S3). Give it the endpoint, bucket, prefix, region and an S3 key. A bucket counts as one surface.
SafeGrd holds this bucket's key, encrypted, and uses it only on the machine it starts for each backup. Every use is in the key access log. The machine reads the bucket the way the CLI does above and writes one archive per backup to hosted storage. Drills read it back on your plan's schedule.
When you add the bucket, SafeGrd's server lists it once, so a refused key shows up then. To replace the key, use Credential on the surface.
If you added a Supabase project with its sign-in, its Storage needs no key. SafeGrd backs up every bucket from one sign-in, as one surface.
One archive per backup
To store each backup as one encrypted tar, use --format tar, or
format: tar on a surface. The manifest is sealed inside the tar, so SafeGrd's
servers never see your file names. A tar backup takes one root. Every backup uploads the whole
tree, and a restore reads the whole archive.
Snapshots taken this way restore the same way whatever the default is. On hosted storage, you can download one from the console as a single file.