Vaulthalla Logo

S3 Gateway Setup

Enable the Vaulthalla S3 Gateway service and choose direct listener or managed Nginx S3-domain endpoints for downstream S3 clients.

S3 Gateway Setup

Use this page to enable the S3 Gateway service and choose how downstream S3 clients reach Vaulthalla.

Service Commands

The gateway runtime service is named S3GatewayService. Enabling or disabling it updates Vaulthalla config and restarts only the gateway service.

1vh s3-gateway status2vh s3-gateway enable3vh s3-gateway disable

vh s3-gateway status reports the configured endpoint, readiness, and request counters. Disabling the service does not remove gateway credentials, bucket bindings, or budget policies.

Config

The gateway is disabled by default:

1s3_gateway:2  enabled: false3  host: 0.0.0.04  port: 390005  max_connections: 10246  max_body_size_mb: 51207  require_sigv4: true8  allow_path_style: true9  allow_virtual_hosted_style: true10  default_bucket_mode: local11  default_api_exclusive: true12  default_remote_sync_strategy: cache13  default_remote_conflict_policy: keep_local14  multipart:15    min_part_size_mb: 516    abort_after_days: 717  synthetic_local_request_cost_usd:18    list: "0.00000001"19    head: "0.00000001"20    get: "0.00000001"21    put: "0.00000001"22    delete: "0.00000001"23    copy: "0.00000001"24    downloaded_gb: "0.00000000"25    uploaded_gb: "0.00000000"

synthetic_local_request_cost_usd is used only when a gateway credential has enforce_budget_for_local_requests enabled. It gives local/cache requests a tiny nominal cost for gateway key budgets without creating provider, vault, or global upstream usage.

Direct Listener

Use the direct listener for local clients and development:

1aws configure set s3.addressing_style path2aws --endpoint-url http://127.0.0.1:39000 s3api list-buckets

The default local URL is:

1http://127.0.0.1:39000

Keep SigV4 enabled for real client validation. Downstream clients should generally use path-style addressing, especially when they share configuration with the public S3-domain endpoint.

Managed Nginx S3-Domain Endpoint

Managed Nginx can publish a dedicated public S3 hostname:

1sudo vh setup nginx \2  --domain vaulthalla.example.com \3  --s3-domain s3.vaulthalla.example.com \4  --certbot

For local or lab hosts using Cloudflare DNS-01 certificates:

1sudo vh setup nginx \2  --domain vaulthalla.dev \3  --s3-domain s3.vaulthalla.dev \4  --certbot-dns-cloudflare \5  --cloudflare-credentials /etc/vaulthalla/certbot/cloudflare.ini

The S3 domain proxies requests to the direct gateway listener and preserves the signed URI. It marks requests as path-style-only so the router does not interpret s3.vaulthalla.example.com as a virtual-hosted bucket.

Path-Style And SigV4

Use path-style URLs for downstream clients:

1https://s3.vaulthalla.example.com/archive/reports/report.pdf

That shape maps archive to the gateway bucket and reports/report.pdf to the object key. SigV4 signs the path sent by the client, so reverse proxies must preserve the URI and host behavior expected by the managed S3-domain configuration.

Virtual-hosted style may be accepted by the direct listener when enabled, but path-style is the operational default for public reverse-proxy mode.

Web Console Workflow

Use the browser workflow for interactive setup:

  1. Navigate to Admin -> S3 Gateway.
  2. Check service readiness and endpoint information.
  3. Create a gateway credential.
  4. Copy the secret immediately; the secret access key is shown only once.
  5. Choose user_access, vault_allowlist, or global scope.
  6. For vault_allowlist, choose the key default vault role, select vaults, then add per-vault role or path overrides only for exceptions.
  7. For global, choose the key default vault role; gateway bucket bindings define the vault set.
  8. Create or bind a gateway bucket.
  9. Set gateway key or key/vault budgets.
  10. Copy AWS CLI or MinIO client snippets.
  11. Use budget status and ledger views to troubleshoot AccessDenied or SlowDown responses.

CLI Workflow

Use the CLI for automation and host-local checks:

1vh s3-gateway status2vh s3-gateway enable3vh s3-gateway disable

Credentials:

1vh s3-gateway creds create laptop --json2vh s3-gateway creds list3vh s3-gateway creds revoke VH...4vh s3-gateway creds scope backup show5vh s3-gateway creds scope backup set --scope vault-allowlist6vh s3-gateway creds role assign backup --vault archive --role contributor7vh s3-gateway creds role override add backup --vault archive --pattern "/private/*" --permission download --effect deny8vh s3-gateway creds role override list backup --vault archive9vh s3-gateway creds role revoke backup --vault archive

Boolean scope flags and creds scope allow-vault are CLI/API shorthand. Gateway authorization uses selected vaults, default vault roles, role exceptions, and path overrides.

Buckets:

1vh s3-gateway bucket list2vh s3-gateway bucket bind photos --vault 12 --mode local3vh s3-gateway bucket create-local archive4vh s3-gateway bucket create-remote-cache edge --api-key r2-main --upstream-bucket origin --encrypt5vh s3-gateway bucket backfill archive

Budgets:

1vh s3-gateway budget set-key backup --monthly 5 --mode enforce --currency USD2vh s3-gateway budget set-key-vault backup --vault archive --monthly 2 --mode enforce3vh s3-gateway budget list --key backup4vh s3-gateway budget disable-key backup5vh s3-gateway budget disable-key-vault backup --vault archive6vh s3-gateway budget status --key backup7vh s3-gateway budget ledger --key backup --limit 50