From 0a2370c0242d17a3aa6998254ce97c0e428d7b2c Mon Sep 17 00:00:00 2001 From: houseme Date: Mon, 27 Jul 2026 19:57:22 +0800 Subject: [PATCH] docs: clarify outbound allowlist scope (#5336) --- README.md | 6 +++++- docs/operations/outbound-connection-policy.md | 17 ++++++++--------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 715624e18..59c1a8ca7 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,11 @@ Notes: - For ARN `arn:rustfs:sqs::primary:webhook`, use instance-scoped env vars with `_PRIMARY`. - If queue dir is omitted, default is `/opt/rustfs/events`; ensure it is writable by the container runtime user. - `RUSTFS_NOTIFY_WEBHOOK_SKIP_TLS_VERIFY_PRIMARY` defaults to `false`; enabling it skips webhook TLS certificate verification, allows MITM attacks, and emits a startup warning. Prefer `RUSTFS_NOTIFY_WEBHOOK_CLIENT_CA_PRIMARY` for private CAs. -- Since `1.0.0-beta.11`, webhook endpoints on private or container networks (Docker Compose service names, `host.docker.internal`, RFC 1918 addresses) are blocked unless their exact `scheme://host:port` origin is listed in `RUSTFS_OUTBOUND_ALLOW_ORIGINS` (comma-separated; the origin only, without the path). See [Outbound Connection Policy](docs/operations/outbound-connection-policy.md). +- Since `1.0.0-beta.11`, webhook endpoints on private or container networks + (`Docker Compose service names`, `host.docker.internal`, RFC 1918 addresses) are + blocked unless their exact `scheme://host:port` origin is listed in + `RUSTFS_OUTBOUND_ALLOW_ORIGINS` (the origin only, without the path). See + [Outbound Connection Policy](docs/operations/outbound-connection-policy.md). **NOTE**: We recommend reviewing the `docker-compose.yml` file before running. It defines several services including Grafana, Prometheus, and Jaeger, which are helpful for RustFS observability. If you wish to start Redis or Nginx containers, you can specify the corresponding profiles. diff --git a/docs/operations/outbound-connection-policy.md b/docs/operations/outbound-connection-policy.md index 691bd6508..d64770149 100644 --- a/docs/operations/outbound-connection-policy.md +++ b/docs/operations/outbound-connection-policy.md @@ -2,7 +2,7 @@ This document describes the outbound connection policy that RustFS applies to server-initiated HTTP(S) requests, and the `RUSTFS_OUTBOUND_ALLOW_ORIGINS` -allowlist operators use to reach endpoints on private or container networks. +allowlist operators can use to reach endpoints on private or container networks. It is written for operators who upgraded to `1.0.0-beta.11` (or later) and found that event-notification webhooks, audit webhooks, or other outbound integrations @@ -12,10 +12,10 @@ names, `host.docker.internal`, or RFC 1918 addresses. ## Background: what the policy protects Several RustFS subsystems open connections to operator-configured URLs. To close -a server-side request forgery (SSRF) class of problem, RustFS validates every -such destination and re-checks the addresses returned by DNS on each new -connection, so a hostname cannot be rebound to a restricted address after it is -first accepted. +a server-side request forgery (SSRF) class of problem, RustFS validates every such +destination and re-checks the addresses returned by DNS on each new connection, +so a hostname cannot be rebound to a restricted address after it is first +accepted. The policy governs the outbound clients used by: @@ -26,8 +26,7 @@ The policy governs the outbound clients used by: - Keystone auth URLs. The webhook and audit outbound clients also **disable proxies and do not follow -redirects**, so the destination must be reachable directly at the configured -URL. +redirects**, so the destination must be reachable directly at the configured URL. ## What changed in beta.11 @@ -39,7 +38,7 @@ URL. | Proxies / redirects for outbound clients | Followed | Disabled | Before beta.11 a webhook endpoint whose hostname happened to resolve to a -private address was accepted. Beta.11 fails that resolution closed unless the +private address was accepted. Beta.11 fails that resolution check unless the exact origin is on the allowlist. This is why a Compose setup that delivered events on beta.10 can go silent after the upgrade even though the configuration is unchanged. @@ -50,7 +49,7 @@ is unchanged. - Uploads and audited API calls succeed. - No HTTP POST reaches the internal webhook receiver. - The target may appear offline or fail activation when its endpoint resolves to - a loopback, private, shared, or reserved address. +a loopback, private, shared, or reserved address. - Startup or target validation reports `webhook endpoint is not allowed: ...` with a reason such as `private address` or `loopback host`.