> ## Documentation Index
> Fetch the complete documentation index at: https://snapr.seshuk.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Where snapr uploads archives: supported backends, shared fields, on-disk layout, retention, and the listing cache.

A storage is a destination for finished archives. The `storages` key on a job is an array — the job uploads every archive to **all** configured storages. Use `defaultStorage` on the job to mark which storage the UI surfaces first.

## Supported types

| Type     | Description                         |
| -------- | ----------------------------------- |
| `local`  | Local filesystem path               |
| `s3`     | AWS S3 or any S3-compatible service |
| `sftp`   | SFTP server (password or SSH key)   |
| `webdav` | WebDAV server                       |
| `bunny`  | bunny.net Storage Zone              |

## Shared fields

Every storage entry, regardless of type, supports these fields:

| Option           | Type   | Required | Default | Description                                                                            |
| ---------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------- |
| `name`           | string | Yes      | —       | Identifier used in `defaultStorage`, logs, and the UI. Must be unique within a job.    |
| `type`           | string | Yes      | —       | One of `local`, `s3`, `sftp`, `webdav`, `bunny`.                                       |
| `path`           | string | Yes\*    | —       | Base directory or key prefix on the backend. Required for `local`, optional elsewhere. |
| `includeJobName` | bool   | No       | `true`  | Append a `<job-name>/` subdirectory under `path`.                                      |

```yaml snapr.yaml theme={null}
storages:
  - name: local-disk
    type: local
    path: /var/backups
  - name: offsite
    type: s3
    # ...
defaultStorage: offsite
```

## On-disk layout

snapr writes every snapshot under a per-job subdirectory inside the storage's `path`:

```
<storage.path>/
  <job-name>/
    <job-name>-20260509-030000.tar.gz
    <job-name>-20260510-030000.tar.gz.enc
```

The layout is identical on every backend (local disk, S3, SFTP, WebDAV, and bunny.net). It lets snapr filter by job natively — S3 uses `Prefix`, the others list one directory — instead of scanning the whole `path` and filtering by name. Sharing one storage across many jobs stays cheap.

Split snapshots get an extra wrapper directory; see [Splitter](/configuration/splitter).

### Skipping the per-job subdirectory

Set `includeJobName: false` on a storage to drop the `<job-name>/` level and write snapshots directly under `path`:

```yaml snapr.yaml theme={null}
storages:
  - name: offsite
    type: s3
    bucket: backups
    path: db
    includeJobName: false
```

```
db/
  myjob-20260509-030000.tar.gz
```

`includeJobName` defaults to `true`, so existing configs keep the per-job subdirectory. Every backend supports it.

<Warning>
  Only set `includeJobName: false` when a single job owns the `path`. Sharing one `path` across jobs without the per-job
  level mixes their snapshots together.
</Warning>

## Retention

Retention is configured on the **job** (`retention.last`), not on the storage, but snapr applies it independently on each storage after every run:

1. snapr lists the backup sets for the job on that storage.
2. Sets are sorted by last-modified time, newest first.
3. The newest `retention.last` sets are kept; everything older is deleted.

A split snapshot counts as **one** set — its wrapper directory is deleted as a unit. Failed deletions are logged and retried on the next sweep; one failing storage never blocks retention on the others. See [Jobs](/configuration/jobs) for the `retention` option itself.

## Listing cache

The backups list returned to the UI is cached per `(job, storage)` pair for **5 minutes**. snapr invalidates the cache immediately after every upload, delete, and retention sweep, so its own changes show up right away. Files placed or removed manually (outside snapr) appear up to 5 minutes later.

## Storage types

<Columns cols={2}>
  <Card title="Local" icon="hard-drive" href="/configuration/storages/local">
    Write archives to a directory on the host or a mounted volume.
  </Card>

  <Card title="S3" icon="aws" href="/configuration/storages/s3">
    AWS S3 or any S3-compatible service such as MinIO, Wasabi, or R2.
  </Card>

  <Card title="SFTP" icon="server" href="/configuration/storages/sftp">
    Upload over SSH with password or private-key authentication.
  </Card>

  <Card title="WebDAV" icon="globe" href="/configuration/storages/webdav">
    Nextcloud, OwnCloud, or any generic WebDAV endpoint.
  </Card>

  <Card title="bunny.net" icon="cloud" href="/configuration/storages/bunny">
    bunny.net Storage Zone with optional signed Pull Zone downloads.
  </Card>
</Columns>