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

# S3

> Upload archives to AWS S3 or any S3-compatible service, with storage classes and optional presigned downloads.

`type: s3` uploads archives to AWS S3 or any S3-compatible service (MinIO, Wasabi, Backblaze B2 with S3 API, Cloudflare R2, and others). snapr uses the AWS SDK directly — no external binaries required.

Your credentials need `s3:PutObject`, `s3:ListBucket`, `s3:DeleteObject` (for retention), and `s3:GetObject` (for downloads through the UI).

## Example

```yaml snapr.yaml theme={null}
storages:
  - type: s3
    name: aws-cold
    bucket: backups
    region: us-east-1
    accessKeyId: env:S3_KEY
    secretAccessKey: env:S3_SECRET
    path: snapr/postgres
    storageClass: STANDARD_IA
```

For a non-AWS provider, set `endpoint`:

```yaml snapr.yaml theme={null}
storages:
  - type: s3
    name: minio
    bucket: backups
    region: us-east-1
    endpoint: https://minio.internal:9000
    accessKeyId: env:MINIO_KEY
    secretAccessKey: env:MINIO_SECRET
```

## Options

| Option            | Type   | Required | Default    | Description                                                                                                                                                                  |
| ----------------- | ------ | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`            | `s3`   | Yes      | —          |                                                                                                                                                                              |
| `name`            | string | Yes      | —          | Identifier; unique within the job.                                                                                                                                           |
| `bucket`          | string | Yes      | —          |                                                                                                                                                                              |
| `region`          | string | Yes      | —          |                                                                                                                                                                              |
| `accessKeyId`     | string | Yes      | —          | Use `env:`.                                                                                                                                                                  |
| `secretAccessKey` | string | Yes      | —          | Use `env:`.                                                                                                                                                                  |
| `endpoint`        | string | No       | —          | Custom endpoint for non-AWS providers. Setting it also enables path-style addressing.                                                                                        |
| `path`            | string | No       | —          | Object key prefix. Archives are stored at `<path>/<jobName>/<archive>`; see [On-disk layout](/configuration/storages/overview#on-disk-layout).                               |
| `includeJobName`  | bool   | No       | `true`     | Include the `<jobName>/` level in the key prefix; see [Storages](/configuration/storages/overview#skipping-the-per-job-subdirectory).                                        |
| `storageClass`    | string | No       | `STANDARD` | One of `STANDARD`, `REDUCED_REDUNDANCY`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER`, `DEEP_ARCHIVE`, `OUTPOSTS`, `GLACIER_IR`, `SNOW`, `EXPRESS_ONEZONE`. |
| `downloadMode`    | string | No       | `proxy`    | `proxy` streams the archive through snapr; `signed` issues a presigned S3 URL and the browser fetches directly.                                                              |
| `signedUrlTTL`    | int    | No       | `900`      | Lifetime of presigned URLs in seconds (60–86400). Only used with `downloadMode: signed`.                                                                                     |

## Download mode

By default snapr proxies download responses through its own HTTP server. Set `downloadMode: signed` to have the API return a presigned S3 GET URL instead — the browser then fetches directly from S3 without going through snapr.

```yaml snapr.yaml theme={null}
storages:
  - type: s3
    name: aws-cold
    bucket: backups
    region: us-east-1
    accessKeyId: env:S3_KEY
    secretAccessKey: env:S3_SECRET
    downloadMode: signed
    signedUrlTTL: 1800
```

Use `signed` when:

* snapr runs on a small instance and would saturate its bandwidth proxying large archives.
* The client and the S3 endpoint share a faster network path than client → snapr → S3.
* You want CDN-style edge delivery (works with S3 Transfer Acceleration or CloudFront origins).

Trade-offs:

* Each signed URL carries short-lived auth in its query parameters. Shorten `signedUrlTTL` (minimum 60 s) if URLs may end up in proxy or access logs.
* The browser must reach the S3 endpoint directly. For private MinIO setups, make sure the endpoint hostname resolves from the user's network and CORS is configured on the bucket.
* For split snapshots, **per-part** downloads still work (each part is its own redirect), but the "Download full archive" option is hidden in the UI — one HTTP redirect cannot represent N parts. Use `downloadMode: proxy` if full-archive streaming matters.

<Note>`downloadMode: signed` is only valid for `type: s3`. The config validator rejects it on other backends.</Note>

## Retention and notes

* Retention deletes the oldest objects under the job's key prefix once more than `retention.last` backup sets exist; see [Storages → Retention](/configuration/storages/overview#retention).
* For non-AWS providers, set `endpoint` to the service URL — path-style addressing is enabled automatically.
* `storageClass` is forwarded as the `x-amz-storage-class` header. Providers that don't recognize the value fall back to their default.

## Related

* [Storages overview](/configuration/storages/overview)
* [S3 as a source](/configuration/sources/s3)