From 3ef04b72fb7ec6fbdc792e1b493a4b962ac2c87b Mon Sep 17 00:00:00 2001 From: mattthew Date: Fri, 17 Jul 2026 15:42:07 -0400 Subject: [PATCH] docs: document Zero --security token and whitelist flags Zero now supports the --security superflag (token, whitelist) to authenticate its administrative HTTP endpoints (/state, /assign, /removeNode, /moveTablet). Document the flag on the dgraph zero CLI page, add zero to the Security superflag table, and add a "Zero admin endpoints" section to Admin Endpoint Security describing the two-tier protection: /removeNode and /moveTablet are loopback-only by default, while /state and /assign are enforced once a token or whitelist is set. Applied to both docs/ (next) and the served v25.3 version. Co-Authored-By: Claude Fable 5 --- .../admin/security/admin-endpoint-security.md | 28 +++++++++++++++++++ docusaurus-docs/docs/cli/superflags.md | 6 ++-- docusaurus-docs/docs/cli/zero.md | 23 +++++++++++++++ .../admin/security/admin-endpoint-security.md | 28 +++++++++++++++++++ .../version-v25.3/cli/superflags.md | 6 ++-- .../version-v25.3/cli/zero.md | 23 +++++++++++++++ 6 files changed, 110 insertions(+), 4 deletions(-) diff --git a/docusaurus-docs/docs/admin/security/admin-endpoint-security.md b/docusaurus-docs/docs/admin/security/admin-endpoint-security.md index 629fb10d..7ff5c017 100644 --- a/docusaurus-docs/docs/admin/security/admin-endpoint-security.md +++ b/docusaurus-docs/docs/admin/security/admin-endpoint-security.md @@ -103,3 +103,31 @@ See the [Token Authentication](#token-authentication) section above for setup in For enterprise-grade access control, see [Enable ACL](../../installation/configuration/enable-acl) and [User Management and Access Control](../admin-tasks/user-management-access-control). +## Zero admin endpoints + +Dgraph Zero exposes its own administrative endpoints over its HTTP port (default `6080`): + +* `/state` - cluster topology and tablet placement +* `/assign` - allocate UIDs, transaction timestamps, and namespace IDs +* `/removeNode` - remove a node from a Raft group +* `/moveTablet` - move a predicate (tablet) between groups + +These endpoints drive cluster membership and coordination. Zero's HTTP port is an internal control-plane port and should not be reachable from untrusted networks. Restrict access to it with firewall rules or network policies, alongside the authentication described below. + +Zero authenticates callers with the same `--security` superflag `token` and `whitelist` options used by Alpha: + +* **Token authentication** - Set `--security "token="` on Zero. Callers must then pass the token in the `X-Dgraph-AuthToken` header. +* **IP whitelisting** - Set `--security "whitelist=..."` on Zero to allow specific source IPs, IP ranges, CIDR blocks, or hostnames. Loopback is always allowed. + +Protection applies in two tiers: + +* The destructive endpoints (`/removeNode`, `/moveTablet`) are always guarded. With neither a token nor a whitelist configured, only loopback callers are allowed, so a remote caller cannot disrupt the control plane by default. +* The informational and allocation endpoints (`/state`, `/assign`) are enforced only once a `token` or `whitelist` is configured, so existing tooling that reads them over HTTP is unaffected until you opt in. + +```sh +# Require a token, and allow an internal subnet to reach all admin endpoints +dgraph zero --security "whitelist=10.0.0.0/8;token=" +``` + +To disable the Zero admin HTTP endpoints entirely, set `--limit "disable-admin-http=true"`. The `/health` endpoint stays available. + diff --git a/docusaurus-docs/docs/cli/superflags.md b/docusaurus-docs/docs/cli/superflags.md index b82a89a8..1a9d679f 100644 --- a/docusaurus-docs/docs/cli/superflags.md +++ b/docusaurus-docs/docs/cli/superflags.md @@ -126,8 +126,10 @@ The `--security` superflag configures security settings: | Option | Type | Applies to | Description | |--------|------|------------|-------------| -| `token` | string | `alpha` | Authentication token | -| `whitelist` | string | `alpha` | A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames for administration | +| `token` | string | `alpha`, `zero` | Authentication token. When set, admin requests must present it in the `X-Dgraph-AuthToken` header | +| `whitelist` | string | `alpha`, `zero` | A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames for administration | + +On Zero, `--security` protects the administrative endpoints exposed over the HTTP port (`/state`, `/assign`, `/removeNode`, `/moveTablet`). See [Admin Endpoint Security](../admin/security/admin-endpoint-security#zero-admin-endpoints). ## Telemetry Superflag diff --git a/docusaurus-docs/docs/cli/zero.md b/docusaurus-docs/docs/cli/zero.md index 93fa9f62..30389295 100644 --- a/docusaurus-docs/docs/cli/zero.md +++ b/docusaurus-docs/docs/cli/zero.md @@ -33,10 +33,29 @@ Zero uses several [superflags](superflags) for advanced configuration: - `--audit` - Audit logging configuration - `--limit` - UID lease and admin endpoint settings - `--raft` - Raft consensus options +- `--security` - Authentication token and IP whitelist for the admin HTTP endpoints - `--telemetry` - Telemetry and crash reporting - `--tls` - TLS configuration - `--trace` - Distributed tracing +## Securing the admin HTTP endpoints + +Zero exposes administrative endpoints over its HTTP port (default `6080`): `/state`, `/assign`, `/removeNode`, and `/moveTablet`. These control cluster membership and coordination, so the HTTP port is an internal control-plane port and should not be reachable from untrusted networks. + +Use the `--security` superflag to authenticate callers of these endpoints: + +```bash +# Require a token in the X-Dgraph-AuthToken header +dgraph zero --security "token=" + +# Allow specific source IPs, IP ranges, CIDR blocks, or hostnames (loopback is always allowed) +dgraph zero --security "whitelist=10.0.0.0/8,192.168.1.1" +``` + +The destructive endpoints (`/removeNode`, `/moveTablet`) are restricted to loopback by default; set a `whitelist` or `token` to reach them from another host. The `/state` and `/assign` endpoints are enforced only once a `token` or `whitelist` is configured. To turn the admin HTTP endpoints off entirely, set `--limit "disable-admin-http=true"`. + +See [Admin Endpoint Security](../admin/security/admin-endpoint-security#zero-admin-endpoints) for details. + ## Full Reference ```shell @@ -74,6 +93,10 @@ Flags: (default "idx=1; learner=false;") --rebalance_interval duration Interval for trying a predicate move. (default 8m0s) --replicas int How many Dgraph Alpha replicas to run per data shard group. The count includes the original shard. (default 1) + --security string Security options + token=; If set, all requests to Zero's administrative HTTP endpoints must present this token in the X-Dgraph-AuthToken header. + whitelist=; A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames that are allowed to reach Zero's administrative HTTP endpoints (loopback is always allowed). e.g. --security "whitelist=127.0.0.1,192.168.0.0/16,host.docker.internal". + (default "token=; whitelist=;") --survive string Choose between "process" or "filesystem". If set to "process", there would be no data loss in case of process crash, but the behavior would be nondeterministic in case of filesystem crash. If set to "filesystem", blocking sync would be called after every write, hence guaranteeing no data loss in case of hard reboot. diff --git a/docusaurus-docs/docs_versioned_docs/version-v25.3/admin/security/admin-endpoint-security.md b/docusaurus-docs/docs_versioned_docs/version-v25.3/admin/security/admin-endpoint-security.md index 629fb10d..7ff5c017 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v25.3/admin/security/admin-endpoint-security.md +++ b/docusaurus-docs/docs_versioned_docs/version-v25.3/admin/security/admin-endpoint-security.md @@ -103,3 +103,31 @@ See the [Token Authentication](#token-authentication) section above for setup in For enterprise-grade access control, see [Enable ACL](../../installation/configuration/enable-acl) and [User Management and Access Control](../admin-tasks/user-management-access-control). +## Zero admin endpoints + +Dgraph Zero exposes its own administrative endpoints over its HTTP port (default `6080`): + +* `/state` - cluster topology and tablet placement +* `/assign` - allocate UIDs, transaction timestamps, and namespace IDs +* `/removeNode` - remove a node from a Raft group +* `/moveTablet` - move a predicate (tablet) between groups + +These endpoints drive cluster membership and coordination. Zero's HTTP port is an internal control-plane port and should not be reachable from untrusted networks. Restrict access to it with firewall rules or network policies, alongside the authentication described below. + +Zero authenticates callers with the same `--security` superflag `token` and `whitelist` options used by Alpha: + +* **Token authentication** - Set `--security "token="` on Zero. Callers must then pass the token in the `X-Dgraph-AuthToken` header. +* **IP whitelisting** - Set `--security "whitelist=..."` on Zero to allow specific source IPs, IP ranges, CIDR blocks, or hostnames. Loopback is always allowed. + +Protection applies in two tiers: + +* The destructive endpoints (`/removeNode`, `/moveTablet`) are always guarded. With neither a token nor a whitelist configured, only loopback callers are allowed, so a remote caller cannot disrupt the control plane by default. +* The informational and allocation endpoints (`/state`, `/assign`) are enforced only once a `token` or `whitelist` is configured, so existing tooling that reads them over HTTP is unaffected until you opt in. + +```sh +# Require a token, and allow an internal subnet to reach all admin endpoints +dgraph zero --security "whitelist=10.0.0.0/8;token=" +``` + +To disable the Zero admin HTTP endpoints entirely, set `--limit "disable-admin-http=true"`. The `/health` endpoint stays available. + diff --git a/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/superflags.md b/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/superflags.md index b82a89a8..1a9d679f 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/superflags.md +++ b/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/superflags.md @@ -126,8 +126,10 @@ The `--security` superflag configures security settings: | Option | Type | Applies to | Description | |--------|------|------------|-------------| -| `token` | string | `alpha` | Authentication token | -| `whitelist` | string | `alpha` | A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames for administration | +| `token` | string | `alpha`, `zero` | Authentication token. When set, admin requests must present it in the `X-Dgraph-AuthToken` header | +| `whitelist` | string | `alpha`, `zero` | A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames for administration | + +On Zero, `--security` protects the administrative endpoints exposed over the HTTP port (`/state`, `/assign`, `/removeNode`, `/moveTablet`). See [Admin Endpoint Security](../admin/security/admin-endpoint-security#zero-admin-endpoints). ## Telemetry Superflag diff --git a/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/zero.md b/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/zero.md index 93fa9f62..30389295 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/zero.md +++ b/docusaurus-docs/docs_versioned_docs/version-v25.3/cli/zero.md @@ -33,10 +33,29 @@ Zero uses several [superflags](superflags) for advanced configuration: - `--audit` - Audit logging configuration - `--limit` - UID lease and admin endpoint settings - `--raft` - Raft consensus options +- `--security` - Authentication token and IP whitelist for the admin HTTP endpoints - `--telemetry` - Telemetry and crash reporting - `--tls` - TLS configuration - `--trace` - Distributed tracing +## Securing the admin HTTP endpoints + +Zero exposes administrative endpoints over its HTTP port (default `6080`): `/state`, `/assign`, `/removeNode`, and `/moveTablet`. These control cluster membership and coordination, so the HTTP port is an internal control-plane port and should not be reachable from untrusted networks. + +Use the `--security` superflag to authenticate callers of these endpoints: + +```bash +# Require a token in the X-Dgraph-AuthToken header +dgraph zero --security "token=" + +# Allow specific source IPs, IP ranges, CIDR blocks, or hostnames (loopback is always allowed) +dgraph zero --security "whitelist=10.0.0.0/8,192.168.1.1" +``` + +The destructive endpoints (`/removeNode`, `/moveTablet`) are restricted to loopback by default; set a `whitelist` or `token` to reach them from another host. The `/state` and `/assign` endpoints are enforced only once a `token` or `whitelist` is configured. To turn the admin HTTP endpoints off entirely, set `--limit "disable-admin-http=true"`. + +See [Admin Endpoint Security](../admin/security/admin-endpoint-security#zero-admin-endpoints) for details. + ## Full Reference ```shell @@ -74,6 +93,10 @@ Flags: (default "idx=1; learner=false;") --rebalance_interval duration Interval for trying a predicate move. (default 8m0s) --replicas int How many Dgraph Alpha replicas to run per data shard group. The count includes the original shard. (default 1) + --security string Security options + token=; If set, all requests to Zero's administrative HTTP endpoints must present this token in the X-Dgraph-AuthToken header. + whitelist=; A comma separated list of IP addresses, IP ranges, CIDR blocks, or hostnames that are allowed to reach Zero's administrative HTTP endpoints (loopback is always allowed). e.g. --security "whitelist=127.0.0.1,192.168.0.0/16,host.docker.internal". + (default "token=; whitelist=;") --survive string Choose between "process" or "filesystem". If set to "process", there would be no data loss in case of process crash, but the behavior would be nondeterministic in case of filesystem crash. If set to "filesystem", blocking sync would be called after every write, hence guaranteeing no data loss in case of hard reboot.