Object storage
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 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, 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:
[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):
{
"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] 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:
[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.
Azure Blob Storage
Create a container, then pass a connection string with either the account key or a shared access signature (SAS):
[storage]
provider = "azure"
[storage.azure]
connection_string = "${file:/run/secrets/azure_storage_connection_string}"
container = "sentinel"The connection string has one of these forms:
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].
For local development with Azurite, write the connection string out with its BlobEndpoint. The UseDevelopmentStorage=true shortcut isn't supported:
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].
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:
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-onlyA missing key fails the check:
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.
docker exec sentinel /usr/local/bin/altcha-sentinel doctorstorage
…
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:
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:
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/snapshots{"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/1.1 502 Bad Gateway
content-type: application/json
{"code":"STORAGE_ERROR","error":"Snapshot storage request failed.","statusCode":502}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:
curl -u 'key_…:sec_…' \
-H 'Content-Type: message/rfc822' \
-H 'X-Attachments-Upload: 1' \
--data-binary @message.eml \
https://sentinel.example.com/v2/emlEach 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 and the API reference.
Related
[storage],[storage.s3], and[storage.azure]in the Configuration reference- Snapshots & backups
- Email analysis
STORAGE_ERRORandSNAPSHOT_STORAGE_DISABLEDin Error codes- Outbound proxy & air-gapped deployments