# Back up and restore files

> Back up the folders that go with a database, or any folder on a server, and bring files back from any moment.

Source: https://rowsafe.sh/docs/guides/files

Your app stores uploads, CVs or photos in a folder, and the database holds their paths. Restore the database alone and rows point to files that are gone.

**Files** backs up those folders with the database, in the same bucket. It brings back missing files, the files a column points to, chosen paths, or the whole folder, as they were at any moment in the window.

## Protect a folder

**Installer**

After the database setup, the installer looks for upload folders (Laravel's `storage/app`, WordPress's `wp-content/uploads`, `public/uploads`, `media`, Docker volumes named like uploads) and asks:

```text
Does this app store uploads on this server? Rowsafe found /srv/app/storage/app
(2.3 GiB, 19,596 files: Laravel storage (uploaded files)). Back it up with app,
so a restore brings back both? [Y/n]
```

Or name the folder:

```sh
curl -fsSL https://rowsafe.sh | sudo sh -s -- --files /srv/app/storage/app
```

If the agent's user can't read it, the installer gives it **read-only** access to that folder only (a POSIX ACL). Owners and modes stay as they are.

**Dashboard**

Open the database, **Rewind**, then **Files**. Click **Add a folder** and type its path, or use **Find upload folders on the server**.

If it shows **Can't read it all**, root must allow it: run the install command again with `--files` and that folder (shown under **Do it yourself**). **Give Rowsafe read access** appears only for folders root already allowed (say, after their permissions changed).

**CLI**

```sh
rowsafe files add app /srv/app/storage/app --exclude cache,tmp
rowsafe files add app docker:uploads   # a Docker volume, on a server with Docker
rowsafe files app              # the folders, their status and last snapshot
rowsafe files snapshots app    # snapshots, newest first
rowsafe files set app --every 30m
```

On the server itself (`sudo rowsafe`), `files add` also offers to give the agent read access when it can't read the folder.

**Docker**

Mount the volume into the agent under `/rowsafe-files` (read-only is enough for backups):

```yaml title="compose.yml"
services:
  rowsafe-agent:
    volumes:
      - uploads:/rowsafe-files/uploads:ro
```

Run `docker compose up -d rowsafe-agent`, then add `/rowsafe-files/uploads` in the dashboard. **Find upload folders on the server** lists every volume there.

## What Rowsafe does

- **Snapshots every 15 minutes** (5 minutes to daily, in **Settings**) and **one at every Mark**, so a Mark covers database and files.
- **Only changes are stored**, deduplicated and compressed. The first snapshot of a large folder takes a while.
- **Same storage** as the database (your bucket or [Rowsafe Storage](https://rowsafe.sh/docs/guides/rowsafe-storage)), under `<prefix>/<name>/files` (`/rowsafe/app/files` by default), with [restic](https://restic.net).
- **Encrypted on the server** with a key derived from your backup passphrase. No second secret to keep.
- **Kept for the database's recovery window** (at least 7 days): every snapshot for two days, one an hour for a week, then one a day. Mark snapshots are all kept for the window.
- **Low priority**: low CPU and disk priority, at most two cores, one filesystem.
- **Files Proof, weekly**: reads back part of the stored data (all of it over a year) and checks a few unchanged files byte for byte.
- **Pulse** warns when a folder falls behind, can't be read or is missing, with **Back up files now** and **Give Rowsafe read access**.

## Restore files

In **Rewind**, then **Files**, click **Restore files**:

1. **When.** A time, a Mark, or the latest snapshot. Rowsafe shows which snapshot it uses ("Files from 14:00, the nearest snapshot, 4 minutes before").
2. **Which files.**

   | Choice                                  | What comes back                                                                                                                        |
   | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
   | **Only the files that are missing now** | Files deleted since. Nothing that exists is overwritten.                                                                               |
   | **The files a table column points to**  | The files named in a column, like `applications.cv_path`. Paths like `cvs/a.pdf`, `/var/www/storage/app/cvs/a.pdf` or a URL all match. |
   | **Specific files or folders**           | Paths you list, or pick in **Browse**.                                                                                                 |
   | **The whole folder, exactly as it was** | Newer files are removed and changed ones replaced. The current folder is kept 7 days: **Undo** puts it back.                           |

   **More options**, **Also replace files that changed since** puts back older versions of changed files. Current versions are snapshotted first.
3. **See what would come back**, like "Would bring back 1,204 files (310 MB), 18,389 already there".
4. **Bring back 1,204 files.** A whole-folder restore asks you to type the database's name.

**With the CLI**

```sh
rowsafe files restore app --at "14:04"                                         # missing files only
rowsafe files restore app --at "14:04" --column app:public.applications.cv_path
rowsafe files restore app --mark before-import --whole-folder
rowsafe files restore app --snapshot 3f2a9c1e --into /srv/restored           # another folder, nothing live touched
rowsafe files undo app
```

`--into` restores the whole snapshot (or `--path`) into a new or empty folder and leaves the protected one as it is. It works on [a server running Rowsafe on its own](https://rowsafe.sh/docs/guides/no-account-server#files-and-docker-volumes) for now.

### Where the files go

The agent restores into a private staging folder, then puts files in place:

- **Itself**, if its user may write into the folder.
- **As the folder's owner**, through the files helper (`rowsafe-files-helper.service`), for folders root allowed at install ([below](#permissions-on-the-server)).
- **Otherwise they wait** in `/var/lib/rowsafe/files-restored/<id>` (in Docker, the agent's state volume), and Rowsafe says so. The folder isn't touched.

**What the files helper refuses**

The helper doesn't trust what the agent staged. It takes its own copy (20 GB at most at once) and:

- puts back only plain files and folders: no links, devices or FIFOs, no set-user-ID or set-group-ID bits, nothing into `.ssh`, `.gnupg` or `.config/systemd`;
- writes as the folder's owner with that user's group, never as root, and never through a symbolic link;
- refuses a folder that isn't exactly one root allowed, now owned by another user, is or holds a home folder, is owned or writable by the agent's user (or any folder on the way or inside), system and database folders, and folders owned by root;
- runs at most one put-back every 2 minutes.

## A server's own files

Any folder or Docker volume on a server, with or without a database on it: app files, configs, a static site. Open the server's page, then **Files**, and **Add a folder** or **Find folders on the server**. It works like a database's files, except:

- **Kept 30 days** by default; change it under **Keep snapshots** (7 days to a year).
- **No Marks**, and no **files a table column points to**.
- A whole-folder restore asks you to type the **server's hostname**.
- Stored in the server's storage under `<prefix>/<server ID>/files`, encrypted with its passphrase.
- A folder belongs to the server or to one of its databases, never both.
- Not on Rowsafe Cloud servers.

Root allows reading and putting files back the same way ([below](#permissions-on-the-server)). Rowsafe doesn't snapshot whole servers or disks.

**With the CLI**

Every `rowsafe files` command takes `--server` instead of a database's name:

```sh
rowsafe files add --server web1 /srv/app/storage
rowsafe files add --server web1 /var/lib/docker/volumes/app_media/_data   # a Docker volume
rowsafe files --server web1                                               # status
rowsafe files restore --server web1 --at "14:04"
rowsafe files set --server web1 --keep-days 60
```

On the server itself (`sudo rowsafe`), `--server` alone means this server, and it is the default when the server has no database: `sudo rowsafe files add --server docker:app_media`.

**With the API or an AI agent**

`/v1/hosts/{ref}/files` has the same routes as a database's `/v1/databases/{ref}/files`. AI agents: `files_status` and `backup_files` with `server`, and `request_change` with `restore_server_files` or `undo_server_files_restore` ([MCP](https://rowsafe.sh/docs/reference/mcp)).

## Browse a snapshot

**Browse** lists a folder's latest snapshot, marks files deleted since, and searches by name. Pick files and **Restore selected**.

Only names, sizes and times reach Rowsafe, never contents. To keep names on your server, turn off **Show file names in Rowsafe** in **Settings**. Restores still work.

## Permissions on the server

|                                       | How it is allowed                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Read a folder you protect             | `--files PATH` (or yes at the installer's question): read-only access to that folder with an ACL. Existing ACL masks stay. |
| Put restored files back               | `--allow-files` with `--files PATH` (or yes at the question): as the folder's owner, only when someone asks and confirms.  |
| A folder added later in the dashboard | Run the install command again with `--files` and that folder. Nothing is allowed in advance.                               |

- Root's list is `/etc/rowsafe/files-allowed`: one `PATH UID` line per folder. Only those exact folders count, only while that uid owns them. No defaults.
- If a folder's owner changes, run the install command again with `--files` and that folder. `--no-allow-files` turns it all off.
- The dashboard shows what's allowed on each server under **On db-1**.
- The helper runs in its own sandboxed unit (started by `rowsafe-files-helper.path`) and may write only into listed folders. The restart helper doesn't get its rights.
- To put back more than 20 GB at once, root adds a drop-in: `Environment=ROWSAFE_FILES_MAX_BYTES=...`.

## Every engine

Folders work the same next to MySQL, MariaDB, MongoDB, ClickHouse, Redis and Valkey. **The files a table column points to** reads PostgreSQL tables, so it's PostgreSQL only. Engine data folders (`/var/lib/mysql`, `/var/lib/mongodb`, `/var/lib/clickhouse`) are never accepted.

## Limits

- Files come back **as they were at a snapshot**: at most one interval (15 minutes by default) before your moment, or exactly at a Mark. The database can be closer to the moment than the files.
- A snapshot is **not atomic**: a file written during it may be old or new.
- **Unreadable files are left out**, and the folder shows it.
- **Symbolic links aren't put back** by the files helper, and set-user-ID and set-group-ID bits are dropped.
- **Home folders are never written to** by the helper (a folder that is, holds or sits inside a home), except a service account's home without a login shell. Use a folder elsewhere, or let files wait next to it.
- **One filesystem per folder**: mounts inside aren't followed. Protect them separately.
- **The column restore** matches paths by their end: two missing files of the same name in different folders both come back.
- In Docker, restored files **wait in the agent's state volume** unless the volume is read-write and writable by the agent's user.
- Removing a folder stops its snapshots; stored ones age out with the window.

## Restore by hand

The files are a standard restic repository. With restic 0.17+, the bucket settings and your passphrase:

```sh
export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
export RESTIC_REPOSITORY=s3:https://<endpoint>/<bucket>/rowsafe/app/files
export RESTIC_PASSWORD=$(printf 'rowsafe-files-v1:%s' app | openssl dgst -sha256 -hmac "$ROWSAFE_REPO_CIPHER_PASS" -r | cut -d' ' -f1)
restic snapshots --tag rowsafe
restic restore <snapshot>:/srv/app/storage/app --target /tmp/restored --include /cvs/a.pdf
```

Replace `app` with the database's name in Rowsafe (for a server's own folders, the server's ID, in both places) and the path with your folder. Add `-o s3.region=auto` for R2 and `-o s3.bucket-lookup=path` for path-style stores.
