Docs / Surfaces / Files

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.

# a directory tree, incremental
safegrd backup --files /srv/uploads
# with exclusions
safegrd backup --files /srv/app --exclude '*.tmp,node_modules/*'
# one archive per backup instead
safegrd backup --files /srv/app --format tar

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 VM's root, in ~/.safegrd/config.yaml, run by the daemon
surfaces:
  - id: vm-root
    type: files
    roots: ["/"]
    excludes: ["/home/*/.cache"]
    schedule: "@daily"

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

safegrd backup --surface vm-root

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

safegrd find etc/nginx/nginx.conf
safegrd restore --path etc/nginx/nginx.conf --target-dir ./out
safegrd restore --path etc/nginx/nginx.conf --version 2 --target-dir ./out
safegrd restore --snapshot <id> --path 'var/www/**' --target-dir ./out
safegrd find --deleted var/www/uploads/

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.

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.

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.

A timeline of one epoch. On 1 October the first run uploads every file, locked until 31 October plus T plus 3 days. Runs from 2 to 31 October upload changed chunks, locked until 31 October plus T. On 1 November a new epoch uploads every file again while October's objects are still locked. At 31 October plus T the later October objects expire, and 3 days after that the first run's objects expire, or later if keep_monthly keeps that snapshot. 1 Oct First run: every file locked to 31 Oct + T + 3 days 2 to 31 Oct Later runs: changed chunks locked to 31 Oct + T 1 Nov New epoch: every file again October's objects are still locked 31 Oct + T Later October objects expire their snapshots expire with them + 3 days First run's objects expire or later, if keep_monthly keeps it
One epoch, with T the longest of 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.

Bars drawn to scale for a 200 GB tree with 2% daily change and 30-day retention. Incremental backups in monthly epochs hold 500 to 650 GB on average. A full archive every day, kept 30 days, holds about 6 TB. Incremental, monthly epochs 500 to 650 GB A full archive every day, kept 30 days about 6 TB 0 3 TB 6 TB
The numbers above, drawn to scale: a 200 GB tree, 2% of it changing a day, 30-day retention. The dashed end of the top bar is the extra full upload at the turn of each month.

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

safegrd check --all --read-data

check confirms three things for each snapshot:

--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.

PropertyRestored?
ContentsYes. Every regular file is checked against the digest sealed at backup time.
PermissionsYes, for files and directories, whatever the restoring shell's umask. A 0700 directory comes back 0700.
Modification timesYes, for files, directories and symlinks. Restoring a one-directory snapshot into a new target gives the target that directory's mode and time.
SymlinksYes, as symlinks pointing where they pointed.
OwnershipOnly 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 linksNo. 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, capabilitiesNo. If a tree depends on them (an SELinux-labeled web root, a binary granted setcap), reapply them after a restore.
setuid, setgid and sticky bitsIncremental 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 filesContents yes, sparseness no. Holes are written out in full.
FIFOs, sockets, device nodesNot 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.

# Supabase Storage, one bucket, one backup
safegrd backup --files s3://avatars \
  --source-endpoint https://PROJECT.storage.supabase.co/storage/v1/s3 \
  --source-region eu-central-1 \
  --source-access-key env:SUPABASE_S3_KEY --source-secret-key env:SUPABASE_S3_SECRET
# as a surface the daemon backs up on its schedule
surfaces:
  - id: avatars
    type: files
    roots: ["s3://avatars"]
    object_store:
      endpoint: https://PROJECT.storage.supabase.co/storage/v1/s3
      region: eu-central-1
      access_key_id: env:SUPABASE_S3_KEY
      secret_access_key: env:SUPABASE_S3_SECRET

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.

safegrd restore --snapshot snap-20261012-030000-a1b2c3 --target s3://avatars \
  --source-endpoint https://PROJECT.storage.supabase.co/storage/v1/s3 \
  --source-region eu-central-1 \
  --source-access-key env:SUPABASE_S3_KEY --source-secret-key env:SUPABASE_S3_SECRET

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.