# Object storage

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Sentinel writes email attachments and database snapshots to object storage when you configure `[storage]`. It supports Amazon S3, S3-compatible services such as MinIO, and Azure Blob Storage. Without `[storage]`, Sentinel runs normally; only the two features below work differently.

## What uses storage

| Feature | What is stored | Key prefix | Without `[storage]` |
| --- | --- | --- | --- |
| [Email analysis](/docs/sentinel/v2/features/email-analysis/) with `X-Attachments-Upload` | Each attachment of the analyzed message, at `<prefix><UTC date>/<32 hex characters><.ext>` | `[eml] storage_prefix`, default `eml/attachments/` | Attachments come back inline as base64 `content` (up to `X-Attachments-Size-Limit`, default `5000000` bytes). Requests with `X-Attachments-Upload` get `400 VALIDATION_ERROR`. |
| [Snapshots](/docs/sentinel/v2/operations/snapshots/), when `[snapshots] identity` is set | Encrypted `.zip.age` snapshots, manual and scheduled | `[snapshots] storage_prefix`, default `snapshots/` | Snapshots are downloads. Listing, restoring by name, and `[snapshots] schedule` are unavailable. |

Sentinel has no local-filesystem storage and serves no stored files itself. An uploaded attachment is returned as an object URI that your application fetches with its own storage credentials.

With `[storage]` set but no `[snapshots] identity`, snapshots stay downloads and the startup log warns: `[storage] is configured but [snapshots] identity is not: snapshots are downloads, not stored`.

## Amazon S3

Create a private bucket and an IAM user with an access key, then reference the key from secret files or environment variables:

```toml
[storage]
provider = "s3"

[storage.s3]
region            = "eu-central-1"
bucket            = "sentinel-example"
access_key_id     = "${file:/run/secrets/s3_access_key_id}"
secret_access_key = "${file:/run/secrets/s3_secret_access_key}"
```

Without `endpoint`, Sentinel uses `https://s3.<region>.amazonaws.com` with virtual-hosted addressing (`https://<bucket>.s3.<region>.amazonaws.com/<key>`). `region` defaults to `us-east-1`.

Sentinel signs requests with the static key only. It doesn't read the AWS default credential chain: environment variables like `AWS_ACCESS_KEY_ID` apply only when you reference them as `"${AWS_ACCESS_KEY_ID}"`, and instance profiles, IAM roles for service accounts, and temporary session tokens aren't supported.

The key needs these permissions on the bucket. `ListBucket` and `DeleteObject` are used only for stored snapshots (listing and retention):

```json
{
"Version": "2012-10-17",
"Statement": [
{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
  "Resource": "arn:aws:s3:::sentinel-example/*"
},
{
  "Effect": "Allow",
  "Action": "s3:ListBucket",
  "Resource": "arn:aws:s3:::sentinel-example"
}
]
}
```

Every key is in [`[storage.s3]`](/docs/sentinel/v2/reference/configuration/#storages3) in the Configuration reference.

## S3-compatible services

For MinIO, RustFS, and other S3-compatible services, set `endpoint` to the service's origin (scheme, host, and port, without a path) and use the region the service expects:

```toml
[storage]
provider = "s3"

[storage.s3]
endpoint          = "https://minio.example.com:9000"
region            = "us-east-1"
bucket            = "sentinel"
access_key_id     = "${S3_ACCESS_KEY_ID}"
secret_access_key = "${S3_SECRET_ACCESS_KEY}"
path_style        = true   # https://minio.example.com:9000/sentinel/<key>
```

`path_style = true` puts the bucket in the path instead of the host name, which most self-hosted services need. Endpoints with an IP address or `localhost` always use path-style URLs. Plain `http://` endpoints work, for example for a service on the same private network.

Requests to every provider go through the outbound proxy from `HTTPS_PROXY` (or `HTTP_PROXY` for `http://` endpoints) unless `NO_PROXY` excludes the host, and trust the CAs in `tls_extra_ca_certs`. See [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/).

## Azure Blob Storage

Create a container, then pass a connection string with either the account key or a shared access signature (SAS):

```toml
[storage]
provider = "azure"

[storage.azure]
connection_string = "${file:/run/secrets/azure_storage_connection_string}"
container         = "sentinel"
```

The connection string has one of these forms:

```text
DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<base64 key>;EndpointSuffix=core.windows.net
BlobEndpoint=https://<account>.blob.core.windows.net;SharedAccessSignature=sv=…&sig=…
```

A SAS needs read, write, delete, and list permissions on the container for stored snapshots; EML uploads need only create and write. Every key is in [`[storage.azure]`](/docs/sentinel/v2/reference/configuration/#storageazure).

For local development with Azurite, write the connection string out with its `BlobEndpoint`. The `UseDevelopmentStorage=true` shortcut isn't supported:

```bash
export AZURE_STORAGE_CONNECTION_STRING='DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02x…;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;'
```

Use Azurite's published development account key in place of `Eby8vdM02x…`, and reference the variable as `connection_string = "${AZURE_STORAGE_CONNECTION_STRING}"`.

## Timeouts and size limits

`[storage] timeout` (default `60s`, `1s`–`10m`) limits each attachment upload and each list or delete request. Snapshot uploads and downloads allow 1 hour each, whatever the timeout says. Every object is sent in a single PUT, so one object can be at most 5 GiB on S3 and about 5000 MiB on Azure. See [`[storage]`](/docs/sentinel/v2/reference/configuration/#storage).

An attachment upload that fails makes the whole `POST /v2/eml` request fail with `502 STORAGE_ERROR`; the cause is in the server log. Attachments larger than `X-Attachments-Size-Limit` are neither uploaded nor returned inline.

Sentinel never deletes uploaded attachments. Add a lifecycle rule to the bucket or container that expires objects under `eml/attachments/` after the time you need them. Stored snapshots are pruned by `[snapshots] keep`.

## Verify it works

`doctor --config-only` checks the `[storage]` keys, for example that the required ones are present and the connection string parses. Run it in a one-off container with the server's mounts:

```bash
docker run --rm \
-v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 doctor --config-only
```

A missing key fails the check:

```text
config
ok    config.file             Loaded sentinel.toml.
FAIL  config.valid (storage)  storage.s3.access_key_id is required with provider = "s3".
                            hint: Fix this setting; the server does not start with it.
```

The full `doctor`, run inside the running container, then tests the connection with its `storage.object` check. It lists at most one key, and writes nothing, under the prefix Sentinel uses: `snapshots/` (`[snapshots] storage_prefix`) when a snapshot identity is set, otherwise `eml/attachments/` (`[eml] storage_prefix`). Startup doesn't contact the storage service.

```bash
docker exec sentinel /usr/local/bin/altcha-sentinel doctor
```

```text
storage
…
ok    storage.object  S3 listed eml/attachments/ in 5.91 ms.
```

A missing bucket or container, a wrong endpoint, or an unreachable service fails the check:

```text
FAIL  storage.object  S3 could not list eml/attachments/: S3 GET eml/attachments/: HTTP 404 Not Found: <?xml …><Error><Code>NoSuchBucket</Code>…
                    hint: Check the [storage] endpoint, credentials and bucket or container.
```

A `403` fails the check too when snapshots are stored, because they need read, write, list, and delete access. When only attachment uploads use the storage, a `403` is a warning: an upload needs only write access, so it may still work. A wrong secret also answers `403` (`SignatureDoesNotMatch`), so read the message. With `provider = "none"`, the check is skipped. Root users run the same check under **Doctor → Run checks** in the admin UI.

To test a real transfer, make a request that uses the storage. With a snapshot identity set, list the stored snapshots as a root user:

```bash
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/snapshots
```

```json
{"data":[{"name":"sentinel-20261118T085128.083Z-manual.zip.age","createdAt":"2026-11-18T08:51:28.083Z","trigger":"manual","size":7128,"encrypted":true}]}
```

An empty `data` list also confirms access. If the storage can't be reached or rejects the credentials, the request fails, and the server log names the cause:

```http
HTTP/1.1 502 Bad Gateway
content-type: application/json

{"code":"STORAGE_ERROR","error":"Snapshot storage request failed.","statusCode":502}
```

```text
ERROR altcha_sentinel::api::snapshots: snapshot storage request failed error="S3 GET snapshots/: HTTP 403 Forbidden: <?xml …><Error><Code>SignatureDoesNotMatch</Code>…"
```

For attachment uploads only, send a message with an attachment to `POST /v2/eml` with `X-Attachments-Upload: 1` and a `restricted` or `full` key:

```bash
curl -u 'key_…:sec_…' \
-H 'Content-Type: message/rfc822' \
-H 'X-Attachments-Upload: 1' \
--data-binary @message.eml \
https://sentinel.example.com/v2/eml
```

Each uploaded attachment has `content: null` and a `contentUri`: the object URI (`s3://<bucket>/<key>` on S3, the blob URL on Azure) followed by `?size=…&type=…&filename=…`. Both headers and the response are described in [Email analysis](/docs/sentinel/v2/features/email-analysis/) and the [API reference](/sentinel-api-docs-v2.html#tag/eml/POST/v2/eml).

## Related

- [`[storage]`](/docs/sentinel/v2/reference/configuration/#storage), [`[storage.s3]`](/docs/sentinel/v2/reference/configuration/#storages3), and [`[storage.azure]`](/docs/sentinel/v2/reference/configuration/#storageazure) in the Configuration reference
- [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/)
- [Email analysis](/docs/sentinel/v2/features/email-analysis/)
- [`STORAGE_ERROR` and `SNAPSHOT_STORAGE_DISABLED`](/docs/sentinel/v2/reference/errors/#upstream-services) in Error codes
- [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/)
