From 8aae9275ea634b0bf134ac5757cafbcb102764a0 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:20:37 -0500 Subject: [PATCH 01/16] docs: add root login disable and debug_user documentation Add comprehensive documentation for the Preview feature that allows disabling root login for compliance requirements. - Update 'The root access rule' section to note the new optional --disallow-root-login flag - Add 'Disabling root login (Preview)' subsection explaining the feature and prerequisites - Add 'Using debug_user for diagnostics (Preview)' subsection documenting the debug_user privileged user - Add complete 'Disable root login and use debug_user' procedure with 6 steps, security best practices, and troubleshooting Related to v26.1 PRs cockroachdb/cockroach#155216, cockroachdb/cockroach#158961, cockroachdb/cockroach#158963 --- .../security-reference/authentication.md | 191 +++++++++++++++++- 1 file changed, 187 insertions(+), 4 deletions(-) diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index 82638080061..01ce76623d6 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -78,18 +78,54 @@ Each rule definition contains up to 6 values. - `reject`: server unconditionally rejects connection without performing authentication. - `trust`: server unconditionally allows connection without performing authentication. -## The unstated, unchangeable `root` access rule +## The `root` access rule -The `root` SQL user can always authenticate using username/password or certificate, as if the first rule of the configuration were: +{{site.data.alerts.callout_info}} +**Preview Feature**: As of v26.1, you can optionally disable root login using the `--disallow-root-login` flag on `cockroach start`. This feature is in [Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#feature-availability-phases) and requires additional setup. +{{site.data.alerts.end}} + +By default, the `root` SQL user can always authenticate using username/password or certificate, as if the first rule of the configuration were: ``` # TYPE DATABASE USER ADDRESS METHOD host all root all root ``` -This rule is not displayed in the configuration, and cannot be overridden. +This rule is not displayed in the configuration, and cannot be overridden through HBA configuration alone. This ensures that access to the cluster can always be recovered, but it also means that access with root credentials cannot be restricted by IP range at the authentication configuration level. +### Disabling root login (Preview) + +New in v26.1: For compliance requirements, you can disable root user login using the `--disallow-root-login` flag when starting nodes. When this flag is set: + +- Root user cannot authenticate via SQL or RPC connections +- Any certificate with "root" in the CommonName or SubjectAlternativeName is rejected +- Error messages indicate root login has been disallowed + +{{site.data.alerts.callout_danger}} +**Important Prerequisites**: + +- Before disabling root, you must set up the `debug_user` for troubleshooting operations. See [Using debug_user for diagnostics](#using-debug-user-for-diagnostics). +- Ensure no cluster or client certificates contain "root" in their SAN (Subject Alternative Name) fields, as these will be blocked. +- The cluster does not validate that `debug_user` is configured before allowing root to be disabled. + +{{site.data.alerts.end}} + +For setup instructions, see [Disable root login and use debug_user](#disable-root-login-and-use-debug-user). + +### Using debug_user for diagnostics (Preview) + +New in v26.1: The `debug_user` is a special privileged user designed for collecting debug information when root is disabled. Unlike root, `debug_user`: + +- Must be explicitly enabled using the `--allow-debug-user` flag on `cockroach start` +- Is disabled by default for security +- Must be manually created using `CREATE USER debug_user` +- Requires a certificate with "debug_user" in CommonName or SubjectAlternativeName +- Has privileged access to `serverpb` admin and status endpoints required for debug zip collection +- Can be audited using `SHOW USERS` + +The `debug_user` is not subject to the `--disallow-root-login` flag and provides a secure, auditable alternative for diagnostic operations. + CockroachDB {{ site.data.products.advanced }} or CockroachDB {{ site.data.products.core }} customers can and should enforce network protections, preventing access attempts from any sources other than a valid ones such as application servers or a secure operations jumpbox. ## Default behavior @@ -129,4 +165,151 @@ CockroachDB {{ site.data.products.cloud }} uses a service user named `managed-sq ``` # TYPE DATABASE USER ADDRESS METHOD host all managed-sql-prober all cert -``` \ No newline at end of file +``` + +## Disable root login and use debug_user + +This procedure shows how to configure a cluster to disable root login for compliance requirements while maintaining debugging capabilities. + +### Before you begin + +- You must have an existing CockroachDB cluster +- You must have root access to create the `debug_user` +- You must have access to the CA key to generate certificates + +### Step 1: Create debug_user + +1. Connect to the cluster as root: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --certs-dir=certs + ~~~ + +1. Create the debug_user: + + {% include_cached copy-clipboard.html %} + ~~~ sql + CREATE USER debug_user; + ~~~ + +1. Grant admin privileges (optional, but recommended for full debug access): + + {% include_cached copy-clipboard.html %} + ~~~ sql + GRANT admin TO debug_user; + ~~~ + +### Step 2: Generate debug_user certificate + +{% include_cached copy-clipboard.html %} +~~~ shell +cockroach cert create-client debug_user \ + --certs-dir=certs \ + --ca-key=my-safe-directory/ca.key +~~~ + +This creates `client.debug_user.crt` and `client.debug_user.key` in the specified certs directory. + +### Step 3: Test debug_user access + +Before disabling root, verify that debug_user can collect debug information: + +{% include_cached copy-clipboard.html %} +~~~ shell +cockroach debug zip test-debug.zip \ + --certs-dir=certs \ + --user=debug_user +~~~ + +If successful, you should see debug information being collected. + +### Step 4: Enable debug_user on all nodes + +Perform a rolling restart of all nodes with the `--allow-debug-user` flag: + +{% include_cached copy-clipboard.html %} +~~~ shell +cockroach start \ + --certs-dir=certs \ + --allow-debug-user \ + [other existing flags...] +~~~ + +### Step 5: Disable root login + +After all nodes have been restarted with `--allow-debug-user`, perform another rolling restart with the `--disallow-root-login` flag: + +{% include_cached copy-clipboard.html %} +~~~ shell +cockroach start \ + --certs-dir=certs \ + --disallow-root-login \ + --allow-debug-user \ + [other existing flags...] +~~~ + +### Step 6: Verify configuration + +1. Verify root is blocked: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --certs-dir=certs --user=root + ~~~ + + ~~~ + ERROR: certificate authentication failed for user "root" + ~~~ + +1. Verify debug_user works: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --certs-dir=certs --user=debug_user -e "SELECT current_user();" + ~~~ + + ~~~ + current_user + ---------------- + debug_user + ~~~ + +1. Verify debug zip collection: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach debug zip production-debug.zip \ + --certs-dir=certs \ + --user=debug_user + ~~~ + +### Security best practices + +- Only enable `--allow-debug-user` when debugging is actively needed +- Monitor `debug_user` activity through audit logs +- Consider disabling `debug_user` (removing `--allow-debug-user` flag) when not in use +- Rotate `debug_user` certificates regularly +- Ensure `debug_user` certificate files have appropriate permissions (mode 0700) + +### Troubleshooting + +**Error: "failed to perform RPC, as root login has been disallowed"** + +- Root login is disabled. Use `debug_user` or another administrative user. + +**Error: "failed to perform RPC, as debug_user login is not allowed"** + +- The `--allow-debug-user` flag is not set on the server. Restart the node with this flag. + +**Error: "certificate authentication failed for user 'debug_user'"** + +- Either the `debug_user` certificate is invalid or `--allow-debug-user` is not set. +- Verify the certificate has "debug_user" in CommonName or SubjectAlternativeName. + +### See also + +- [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) +- [`cockroach cert create-client`]({% link {{ page.version.version }}/cockroach-cert.md %}#subcommands) +- [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) +- [CREATE USER]({% link {{ page.version.version }}/create-user.md %}) \ No newline at end of file From 96b417fc3f31761e46d8c7a20cc14cc834a68f9b Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:20:42 -0500 Subject: [PATCH 02/16] docs: add --allow-debug-user and --disallow-root-login flags Add documentation for two new Preview security flags to cockroach start: - --allow-debug-user: Enables authentication for debug_user - --disallow-root-login: Disables root user authentication Also add example showing how to start a cluster with root login disabled for compliance requirements. Related to v26.1 PRs cockroachdb/cockroach#155216, cockroachdb/cockroach#158963 --- src/current/v26.1/cockroach-start.md | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/current/v26.1/cockroach-start.md b/src/current/v26.1/cockroach-start.md index 831f0a9e449..3399db52dba 100644 --- a/src/current/v26.1/cockroach-start.md +++ b/src/current/v26.1/cockroach-start.md @@ -103,6 +103,8 @@ Flag | Description `--insecure` | **Note:** The `--insecure` flag is intended for **non-production testing only**.

Run in insecure mode, skipping all TLS encryption and authentication. If this flag is not set, the `--certs-dir` flag must point to valid certificates.

**Note the following risks:** An insecure cluster is open to any client that can access any node's IP addresses; client connections must also be made insecurely; any user, even `root`, can log in without providing a password; any user, connecting as `root`, can read or write any data in your cluster; there is no network encryption or authentication, and thus no confidentiality.

**Default:** `false` `--accept-sql-without-tls` | This flag (in [preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %})) allows you to connect to the cluster using a SQL user's password without [validating the client's certificate]({% link {{ page.version.version }}/authentication.md %}#client-authentication). When connecting using the built-in SQL client, [use the `--insecure` flag with the `cockroach sql` command]({% link {{ page.version.version }}/cockroach-sql.md %}#client-connection). `--cert-principal-map` | A comma-separated list of `cert-principal:db-principal` mappings used to map the certificate principals to IP addresses, DNS names, and SQL users. This allows the use of certificates generated by Certificate Authorities that place restrictions on the contents of the `commonName` field. For usage information, see [Create Security Certificates using Openssl]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}#examples). +`--allow-debug-user` | New in v26.1: Enables authentication for the `debug_user` privileged user. By default, `debug_user` cannot authenticate. When this flag is set, clients with a valid `debug_user` certificate can authenticate for both SQL and RPC connections. This flag is intended for debugging and troubleshooting purposes and should only be enabled when necessary.

This is a [Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#feature-availability-phases) feature.

**Default:** `false` +`--disallow-root-login` | New in v26.1: Disables authentication for the `root` user. When this flag is set, clients presenting certificates with "root" in the CommonName or SubjectAlternativeName will be rejected for both SQL and RPC connections. This addresses compliance requirements by allowing the [unstated, unchangeable root access rule]({% link {{ page.version.version }}/security-reference/authentication.md %}#the-root-access-rule) to be restricted.

{{site.data.alerts.callout_danger}}Important: Before setting this flag, you must set up `debug_user` for diagnostic operations. The cluster does not validate that `debug_user` is configured. Ensure no cluster or client certificates contain "root" in their SAN fields.{{site.data.alerts.end}}

This is a [Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#feature-availability-phases) feature.

**Default:** `false` `--enterprise-encryption` | This optional flag specifies the encryption options for one of the stores on the node. If multiple stores exist, the flag must be specified for each store.

This flag takes a number of options. For a complete list of options, and usage instructions, see [Encryption at Rest]({% link {{ page.version.version }}/encryption.md %}). `--external-io-disable-http` | This optional flag disables external HTTP(S) access (as well as custom HTTP(S) endpoints) when performing bulk operations (e.g, [`BACKUP`]({% link {{ page.version.version }}/backup.md %})). This can be used in environments where you cannot run a full proxy server.

If you want to run a proxy server, you can start CockroachDB while specifying the `HTTP(S)_PROXY` environment variable. `--external-io-disable-implicit-credentials` | This optional flag disables the use of implicit credentials when accessing external cloud storage services for bulk operations (e.g, [`BACKUP`]({% link {{ page.version.version }}/backup.md %})). @@ -723,6 +725,34 @@ Note the use of port `26258` (the value for `listen-addr`, not `sql-addr`) in th Clusters using this configuration with client certificate authentication may also wish to use [split client CA certificates]({% link {{ page.version.version }}/create-security-certificates-custom-ca.md %}#split-ca-certificates). +### Start a cluster with root login disabled (Preview) + +For compliance requirements, you can disable root login and use `debug_user` for diagnostic operations. + +{{site.data.alerts.callout_info}} +This example assumes you have already created the `debug_user` and generated its certificate. See [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user) for complete setup instructions. +{{site.data.alerts.end}} + +Start each node with both the `--disallow-root-login` and `--allow-debug-user` flags: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach start \ +--certs-dir=certs \ +--advertise-addr= \ +--join= \ +--disallow-root-login \ +--allow-debug-user \ +--cache=.25 \ +--max-sql-memory=.25 +~~~ + +In this configuration: + +- Root user cannot authenticate via SQL or RPC +- `debug_user` can authenticate with a valid certificate +- Other users authenticate normally + ## See also - [Initialize a Cluster]({% link {{ page.version.version }}/cockroach-init.md %}) From 6a140f48b701ebe5e9e8e1eb0063fe4776c81c62 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:23:11 -0500 Subject: [PATCH 03/16] docs: document --user flag for debug zip Add documentation for the --user flag behavior change in v26.1: - Previously always used root regardless of flag value - Now uses specified user (e.g., debug_user) when root is disabled Also add example showing how to collect debug zip with debug_user when root login is disabled. Related to v26.1 PR cockroachdb/cockroach#158961 --- src/current/v26.1/cockroach-debug-zip.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index 6bdf18b4627..ab09bdb8a4c 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/src/current/v26.1/cockroach-debug-zip.md @@ -130,6 +130,7 @@ Flag | Description `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general). `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.

**Env Variable:** `COCKROACH_HOST`
**Default:** `localhost:26257` `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` +`--user` | The SQL user that will be used to connect to the cluster. This user must have appropriate permissions to access debug information.

New in v26.1: Previously, `cockroach debug zip` always used the `root` user regardless of this flag's value. Now, you can specify a different user such as `debug_user` when `root` login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL ### Logging @@ -282,6 +283,24 @@ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host=2 } ~~~ +### Generate a debug zip with debug_user (Preview) + +New in v26.1: When root login is disabled using the [`--disallow-root-login`]({% link {{ page.version.version }}/cockroach-start.md %}#security) flag, you can collect debug information using `debug_user`: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach debug zip debug.zip \ +--certs-dir=certs \ +--host= \ +--user=debug_user +~~~ + +For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). + +{{site.data.alerts.callout_info}} +Secure examples assume you have the appropriate certificates in the certificate directory. The `debug_user` must have a certificate with "debug_user" in the CommonName or SubjectAlternativeName. See [`cockroach cert`]({% link {{ page.version.version }}/cockroach-cert.md %}) for more information. +{{site.data.alerts.end}} + ## See also - [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) From 14af50cfd19394614fa8981b07d9c95a0f3ddcd9 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:23:47 -0500 Subject: [PATCH 04/16] docs: document --user flag for debug tsdump Add documentation for the --user flag (new in v26.1): - Previously always used root user - Now uses specified user (e.g., debug_user) when root is disabled Also add example showing how to generate tsdump with debug_user when root login is disabled. Related to v26.1 PR cockroachdb/cockroach#158961 --- src/current/v26.1/cockroach-debug-tsdump.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index 528fb4ddf1b..0e1853bf66a 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/src/current/v26.1/cockroach-debug-tsdump.md @@ -60,6 +60,7 @@ Flag | Description `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general). `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.

**Env Variable:** `COCKROACH_HOST`
**Default:** `localhost:26257` `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` +`--user` | New in v26.1: The SQL user that will be used to connect to the cluster. Previously, `cockroach debug tsdump` always used the `root` user. Now, you can specify a different user such as `debug_user` when root login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL ### Logging @@ -180,6 +181,20 @@ For a secure cluster: $ cockroach debug tsdump --format=raw --metrics-list-file=metrics.txt --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob ~~~ +### Generate a tsdump with debug_user (Preview) + +New in v26.1: When root login is disabled, you can generate a tsdump using `debug_user`: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach debug tsdump \ +--format=raw \ +--certs-dir=certs \ +--user=debug_user > tsdump.gob +~~~ + +For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). + ## See also - [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) From f81efd4cd2b650226acb49c60ab371e564d985e0 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:24:14 -0500 Subject: [PATCH 05/16] docs: add debug_user certificate creation example Add example showing how to create a client certificate for debug_user, including prerequisites and setup requirements. Related to v26.1 PRs cockroachdb/cockroach#155216, cockroachdb/cockroach#158963 --- src/current/v26.1/cockroach-cert.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/current/v26.1/cockroach-cert.md b/src/current/v26.1/cockroach-cert.md index a9f1b678439..1ef0ee675ff 100644 --- a/src/current/v26.1/cockroach-cert.md +++ b/src/current/v26.1/cockroach-cert.md @@ -332,6 +332,33 @@ total 40 -rw------- 1 maxroach maxroach 1.6K Jul 10 14:17 node.key ~~~ +### Create a debug_user client certificate (Preview) + +New in v26.1: To use the `debug_user` for diagnostic operations when root is disabled: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach cert create-client debug_user \ +--certs-dir=certs \ +--ca-key=my-safe-directory/ca.key +~~~ + +This creates the following files: + +- `client.debug_user.crt` +- `client.debug_user.key` + +The certificate will contain "debug_user" in the CommonName field, which is required for `debug_user` authentication. + +{{site.data.alerts.callout_info}} +Before using this certificate, you must: + +1. Create the `debug_user` SQL user: `CREATE USER debug_user;` +1. Enable debug_user authentication by starting nodes with the [`--allow-debug-user`]({% link {{ page.version.version }}/cockroach-start.md %}#security) flag + +For complete setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). +{{site.data.alerts.end}} + ### List certificates and keys {% include_cached copy-clipboard.html %} From d606a00665ca22eb72e9d511cee95725bf3fb832 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Tue, 17 Feb 2026 01:24:36 -0500 Subject: [PATCH 06/16] docs: add debug_user creation example Add example showing how to create the debug_user for diagnostic operations when root login is disabled. Related to v26.1 PRs cockroachdb/cockroach#155216, cockroachdb/cockroach#158963 --- src/current/v26.1/create-user.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index 6c30538f42a..9e17eb1e6bf 100644 --- a/src/current/v26.1/create-user.md +++ b/src/current/v26.1/create-user.md @@ -314,6 +314,24 @@ with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} (11 rows) ~~~ +### Create debug_user for diagnostics (Preview) + +New in v26.1: The `debug_user` is a special privileged user for collecting diagnostic information when preferred over using the root user, or when root login is disabled. + +{% include_cached copy-clipboard.html %} +~~~ sql +> CREATE USER debug_user; +~~~ + +Optionally, grant admin privileges: + +{% include_cached copy-clipboard.html %} +~~~ sql +> GRANT admin TO debug_user; +~~~ + +For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). + ## See also - [Authorization]({% link {{ page.version.version }}/authorization.md %}) From a95814d1ff11301504a2c9d5c6395113baadccef Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 00:57:23 -0500 Subject: [PATCH 07/16] Fix anchor links --- .gitignore | 1 + src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md | 2 +- src/current/v26.1/cockroach-cert.md | 2 +- src/current/v26.1/cockroach-debug-tsdump.md | 2 +- src/current/v26.1/cockroach-debug-zip.md | 2 +- src/current/v26.1/cockroach-start.md | 2 +- src/current/v26.1/create-user.md | 2 +- src/current/v26.1/security-reference/authentication.md | 4 ++-- 8 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 2c53a248a72..587442e9879 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ node_modules /src/*/vendor/ spec_30_enriched.json .bundle/config +src/current/changes.md diff --git a/src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md b/src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md index 2f6e40ff280..a8062f5217d 100644 --- a/src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md +++ b/src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md @@ -6,7 +6,7 @@ Release Date: December 11, 2025

Security updates

-- A new, optional flag for `cockroach start` restricts the `root` user from logging in to the system via both SQL and RPC connections. This change affects the [unstated, unchangeable root access rule]({% link v26.1/security-reference/authentication.md %}#the-unstated-unchangeable-root-access-rule) and addresses compliance requirements. It is currently available in [Limited Access]({% link v26.1/cockroachdb-feature-availability.md %}#feature-availability-phases). +- A new, optional flag for `cockroach start` restricts the `root` user from logging in to the system via both SQL and RPC connections. This change affects the [root access rule]({% link v26.1/security-reference/authentication.md %}#the-root-access-rule) and addresses compliance requirements. It is currently available in [Limited Access]({% link v26.1/cockroachdb-feature-availability.md %}#feature-availability-phases). - A new `debug_user` certificate has also been introduced for privileged RPC access to collect [debug zip]({% link v26.1/cockroach-debug-zip.md %}) information, which would otherwise be unavailable when `root` is restricted. `debug_user` must be created manually with the `CREATE USER` command and can be audited using `SHOW USERS`. It has privileged access to the `serverpb` admin and status endpoints required for debug zip collection. - Ensure that none of the certificates used by the cluster or SQL/RPC clients have "root" in the SAN (Subject Alternative Name) fields, as the flag will block access to those clients. diff --git a/src/current/v26.1/cockroach-cert.md b/src/current/v26.1/cockroach-cert.md index 1ef0ee675ff..2321b6a0ed9 100644 --- a/src/current/v26.1/cockroach-cert.md +++ b/src/current/v26.1/cockroach-cert.md @@ -356,7 +356,7 @@ Before using this certificate, you must: 1. Create the `debug_user` SQL user: `CREATE USER debug_user;` 1. Enable debug_user authentication by starting nodes with the [`--allow-debug-user`]({% link {{ page.version.version }}/cockroach-start.md %}#security) flag -For complete setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). +For complete setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). {{site.data.alerts.end}} ### List certificates and keys diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index 2e58bdb8540..69c3a69e29a 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/src/current/v26.1/cockroach-debug-tsdump.md @@ -194,7 +194,7 @@ $ cockroach debug tsdump \ --user=debug_user > tsdump.gob ~~~ -For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). +For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). ## See also diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index 2a705d8ad1e..d6f20d03b92 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/src/current/v26.1/cockroach-debug-zip.md @@ -296,7 +296,7 @@ $ cockroach debug zip debug.zip \ --user=debug_user ~~~ -For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). +For setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). {{site.data.alerts.callout_info}} Secure examples assume you have the appropriate certificates in the certificate directory. The `debug_user` must have a certificate with "debug_user" in the CommonName or SubjectAlternativeName. See [`cockroach cert`]({% link {{ page.version.version }}/cockroach-cert.md %}) for more information. diff --git a/src/current/v26.1/cockroach-start.md b/src/current/v26.1/cockroach-start.md index 3399db52dba..42f9e038ea1 100644 --- a/src/current/v26.1/cockroach-start.md +++ b/src/current/v26.1/cockroach-start.md @@ -730,7 +730,7 @@ Clusters using this configuration with client certificate authentication may als For compliance requirements, you can disable root login and use `debug_user` for diagnostic operations. {{site.data.alerts.callout_info}} -This example assumes you have already created the `debug_user` and generated its certificate. See [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user) for complete setup instructions. +This example assumes you have already created the `debug_user` and generated its certificate. See [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user) for complete setup instructions. {{site.data.alerts.end}} Start each node with both the `--disallow-root-login` and `--allow-debug-user` flags: diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index 9e17eb1e6bf..2ebceacb263 100644 --- a/src/current/v26.1/create-user.md +++ b/src/current/v26.1/create-user.md @@ -330,7 +330,7 @@ Optionally, grant admin privileges: > GRANT admin TO debug_user; ~~~ -For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug-user). +For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). ## See also diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index 01ce76623d6..05a7b0b8be8 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -105,13 +105,13 @@ This ensures that access to the cluster can always be recovered, but it also mea {{site.data.alerts.callout_danger}} **Important Prerequisites**: -- Before disabling root, you must set up the `debug_user` for troubleshooting operations. See [Using debug_user for diagnostics](#using-debug-user-for-diagnostics). +- Before disabling root, you must set up the `debug_user` for troubleshooting operations. See [Using debug_user for diagnostics](#using-debug_user-for-diagnostics). - Ensure no cluster or client certificates contain "root" in their SAN (Subject Alternative Name) fields, as these will be blocked. - The cluster does not validate that `debug_user` is configured before allowing root to be disabled. {{site.data.alerts.end}} -For setup instructions, see [Disable root login and use debug_user](#disable-root-login-and-use-debug-user). +For setup instructions, see [Disable root login and use debug_user](#disable-root-login-and-use-debug_user). ### Using debug_user for diagnostics (Preview) From 0be9eb2c21690b5a2eb88dc5e3139e1214ae2f41 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 01:15:30 -0500 Subject: [PATCH 08/16] docs: clarify debug_user privilege requirements Based on engineering review feedback (aa-joshi, souravcrl): - Change 'Connect as root' to 'Connect as a user with admin privileges' to acknowledge any admin user can create debug_user - Change privilege grants from 'optional' to required for debug zip - Add two options: admin role OR specific system privileges - Document specific privileges: VIEWACTIVITY, VIEWACTIVITYREDACTED, VIEWCLUSTERMETADATA, VIEWCLUSTERSETTING, VIEWSYSTEMTABLE, REPAIRCLUSTER - Clarify that tsdump does NOT require any SQL privileges Updated files: - authentication.md Step 1 - create-user.md debug_user example --- src/current/v26.1/create-user.md | 18 ++++++++++++++- .../security-reference/authentication.md | 22 +++++++++++++++++-- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index 2ebceacb263..e2eb0a74d24 100644 --- a/src/current/v26.1/create-user.md +++ b/src/current/v26.1/create-user.md @@ -323,13 +323,29 @@ with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} > CREATE USER debug_user; ~~~ -Optionally, grant admin privileges: +Grant privileges for debug operations. You can either grant the `admin` role (simplest): {% include_cached copy-clipboard.html %} ~~~ sql > GRANT admin TO debug_user; ~~~ +Or grant specific system privileges required for debug zip collection: + +{% include_cached copy-clipboard.html %} +~~~ sql +> GRANT SYSTEM VIEWACTIVITY TO debug_user; +> GRANT SYSTEM VIEWACTIVITYREDACTED TO debug_user; +> GRANT SYSTEM VIEWCLUSTERMETADATA TO debug_user; +> GRANT SYSTEM VIEWCLUSTERSETTING TO debug_user; +> GRANT SYSTEM VIEWSYSTEMTABLE TO debug_user; +> GRANT SYSTEM REPAIRCLUSTER TO debug_user; +~~~ + +{{site.data.alerts.callout_info}} +**Note**: `cockroach debug tsdump` does not require any SQL privileges. Only debug zip collection requires the privileges above. +{{site.data.alerts.end}} + For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). ## See also diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index 05a7b0b8be8..c92f713a0d4 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -179,7 +179,7 @@ This procedure shows how to configure a cluster to disable root login for compli ### Step 1: Create debug_user -1. Connect to the cluster as root: +1. Connect to the cluster as a user with admin privileges (such as `root`): {% include_cached copy-clipboard.html %} ~~~ shell @@ -193,13 +193,31 @@ This procedure shows how to configure a cluster to disable root login for compli CREATE USER debug_user; ~~~ -1. Grant admin privileges (optional, but recommended for full debug access): +1. Grant privileges for debug operations. + + **Option 1**: Grant the `admin` role (simplest approach): {% include_cached copy-clipboard.html %} ~~~ sql GRANT admin TO debug_user; ~~~ + **Option 2**: Grant specific system privileges required for debug zip collection: + + {% include_cached copy-clipboard.html %} + ~~~ sql + GRANT SYSTEM VIEWACTIVITY TO debug_user; + GRANT SYSTEM VIEWACTIVITYREDACTED TO debug_user; + GRANT SYSTEM VIEWCLUSTERMETADATA TO debug_user; + GRANT SYSTEM VIEWCLUSTERSETTING TO debug_user; + GRANT SYSTEM VIEWSYSTEMTABLE TO debug_user; + GRANT SYSTEM REPAIRCLUSTER TO debug_user; + ~~~ + + {{site.data.alerts.callout_info}} + **Note**: `cockroach debug tsdump` does not require any SQL privileges. Only debug zip collection requires the privileges above. + {{site.data.alerts.end}} + ### Step 2: Generate debug_user certificate {% include_cached copy-clipboard.html %} From 3e007a3958ad5de913bd20dff2ac6541c9977219 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 01:21:46 -0500 Subject: [PATCH 09/16] docs: remove duplicate --user flag entry in tsdump Remove incorrect duplicate --user flag that said 'Valid values are root and debug_user' which was too restrictive. The correct entry at line 63 already documents this flag with the v26.1 changes. --- src/current/v26.1/cockroach-debug-tsdump.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index 69c3a69e29a..325306d5f14 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/src/current/v26.1/cockroach-debug-tsdump.md @@ -62,7 +62,6 @@ Flag | Description `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` `--user` | New in v26.1: The SQL user that will be used to connect to the cluster. Previously, `cockroach debug tsdump` always used the `root` user. Now, you can specify a different user such as `debug_user` when root login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL -`--user` | The SQL user that will own the client session. Valid values are `root` and `debug_user`.

**Default:** `root` ### Logging From 27423dd5a820778464345e90d0d9fdeef1eac769 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 01:23:37 -0500 Subject: [PATCH 10/16] docs: remove duplicate --user flag entry in debug zip Remove incorrect duplicate --user flag that said 'Valid values are root and debug_user' which was too restrictive. The correct entry at line 133 already documents this flag with the v26.1 changes. --- src/current/v26.1/cockroach-debug-zip.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index d6f20d03b92..e8038b727c2 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/src/current/v26.1/cockroach-debug-zip.md @@ -132,7 +132,6 @@ Flag | Description `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` `--user` | The SQL user that will be used to connect to the cluster. This user must have appropriate permissions to access debug information.

New in v26.1: Previously, `cockroach debug zip` always used the `root` user regardless of this flag's value. Now, you can specify a different user such as `debug_user` when `root` login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL -`--user` | The SQL user that will own the client session. Valid values are `root` and `debug_user`.

**Default:** `root` ### Logging From db838fd64b2e593a6054d83ccf4cc531a2878def Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 01:31:42 -0500 Subject: [PATCH 11/16] docs: clarify only root/debug_user valid for debug commands Clarify that debug zip and tsdump require privileged RPC access to serverpb endpoints, which only root and debug_user have. Other users (even with admin SQL role) cannot run these commands because RPC privilege is hardcoded in pkg/rpc/auth.go for only: root, node (system use), and debug_user. Updated --user flag descriptions in both files to specify: - Valid users are root (if not disabled) or debug_user (if enabled) - User must have privileged RPC access --- src/current/v26.1/cockroach-debug-tsdump.md | 2 +- src/current/v26.1/cockroach-debug-zip.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index 325306d5f14..6d386a3404c 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/src/current/v26.1/cockroach-debug-tsdump.md @@ -60,7 +60,7 @@ Flag | Description `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general). `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.

**Env Variable:** `COCKROACH_HOST`
**Default:** `localhost:26257` `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` -`--user` | New in v26.1: The SQL user that will be used to connect to the cluster. Previously, `cockroach debug tsdump` always used the `root` user. Now, you can specify a different user such as `debug_user` when root login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` +`--user` | New in v26.1: The SQL user that will be used to connect to the cluster. This user must have privileged RPC access to serverpb endpoints. Valid users are `root` (if not disabled) or `debug_user` (if enabled). Previously, `cockroach debug tsdump` always used the `root` user.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL ### Logging diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index e8038b727c2..c3297ba9b92 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/src/current/v26.1/cockroach-debug-zip.md @@ -130,7 +130,7 @@ Flag | Description `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general). `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.

**Env Variable:** `COCKROACH_HOST`
**Default:** `localhost:26257` `--insecure` | Use an insecure connection.

**Env Variable:** `COCKROACH_INSECURE`
**Default:** `false` -`--user` | The SQL user that will be used to connect to the cluster. This user must have appropriate permissions to access debug information.

New in v26.1: Previously, `cockroach debug zip` always used the `root` user regardless of this flag's value. Now, you can specify a different user such as `debug_user` when `root` login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` +`--user` | The SQL user that will be used to connect to the cluster. This user must have privileged RPC access to serverpb endpoints. Valid users are `root` (if not disabled) or `debug_user` (if enabled).

New in v26.1: Previously, `cockroach debug zip` always used the `root` user regardless of this flag's value. Now, you can specify `debug_user` when `root` login is disabled.

**Env Variable:** `COCKROACH_USER`
**Default:** `root` `--url` | A [connection URL]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`]({% link {{ page.version.version }}/connection-parameters.md %}#convert-a-url-for-different-drivers).

**Env Variable:** `COCKROACH_URL`
**Default:** no URL ### Logging From 11fa848e18c3ff1f432ebc06e6948fef9e4e81ae Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 02:13:37 -0500 Subject: [PATCH 12/16] Better introduce debug zip vs tsdump options and privileges required --- src/current/v26.1/cockroach-cert.md | 2 +- src/current/v26.1/create-user.md | 10 ++++------ .../v26.1/security-reference/authentication.md | 16 +++++++--------- 3 files changed, 12 insertions(+), 16 deletions(-) diff --git a/src/current/v26.1/cockroach-cert.md b/src/current/v26.1/cockroach-cert.md index 2321b6a0ed9..6dc9e7f91d7 100644 --- a/src/current/v26.1/cockroach-cert.md +++ b/src/current/v26.1/cockroach-cert.md @@ -334,7 +334,7 @@ total 40 ### Create a debug_user client certificate (Preview) -New in v26.1: To use the `debug_user` for diagnostic operations when root is disabled: +New in v26.1: To use the `debug_user` for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when root is disabled: {% include_cached copy-clipboard.html %} ~~~ shell diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index e2eb0a74d24..25af3944b77 100644 --- a/src/current/v26.1/create-user.md +++ b/src/current/v26.1/create-user.md @@ -316,14 +316,16 @@ with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} ### Create debug_user for diagnostics (Preview) -New in v26.1: The `debug_user` is a special privileged user for collecting diagnostic information when preferred over using the root user, or when root login is disabled. +New in v26.1: The `debug_user` is a special privileged user for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when preferred over using the root user, or when root login is disabled. {% include_cached copy-clipboard.html %} ~~~ sql > CREATE USER debug_user; ~~~ -Grant privileges for debug operations. You can either grant the `admin` role (simplest): +Grant SQL privileges for debug zip collection. These privileges are required for `cockroach debug zip` but are **not** required for `cockroach debug tsdump`. + +You can either grant the `admin` role (simplest): {% include_cached copy-clipboard.html %} ~~~ sql @@ -342,10 +344,6 @@ Or grant specific system privileges required for debug zip collection: > GRANT SYSTEM REPAIRCLUSTER TO debug_user; ~~~ -{{site.data.alerts.callout_info}} -**Note**: `cockroach debug tsdump` does not require any SQL privileges. Only debug zip collection requires the privileges above. -{{site.data.alerts.end}} - For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). ## See also diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index c92f713a0d4..b41a59186b7 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -115,16 +115,16 @@ For setup instructions, see [Disable root login and use debug_user](#disable-roo ### Using debug_user for diagnostics (Preview) -New in v26.1: The `debug_user` is a special privileged user designed for collecting debug information when root is disabled. Unlike root, `debug_user`: +New in v26.1: The `debug_user` is a special privileged user designed for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when root is disabled. Unlike root, `debug_user`: - Must be explicitly enabled using the `--allow-debug-user` flag on `cockroach start` - Is disabled by default for security - Must be manually created using `CREATE USER debug_user` - Requires a certificate with "debug_user" in CommonName or SubjectAlternativeName -- Has privileged access to `serverpb` admin and status endpoints required for debug zip collection +- Has privileged access to `serverpb` admin and status endpoints required for debug zip and tsdump collection - Can be audited using `SHOW USERS` -The `debug_user` is not subject to the `--disallow-root-login` flag and provides a secure, auditable alternative for diagnostic operations. +The `debug_user` is not subject to the `--disallow-root-login` flag and provides a secure, auditable alternative for these diagnostic operations. CockroachDB {{ site.data.products.advanced }} or CockroachDB {{ site.data.products.core }} customers can and should enforce network protections, preventing access attempts from any sources other than a valid ones such as application servers or a secure operations jumpbox. @@ -169,7 +169,7 @@ CockroachDB {{ site.data.products.cloud }} uses a service user named `managed-sq ## Disable root login and use debug_user -This procedure shows how to configure a cluster to disable root login for compliance requirements while maintaining debugging capabilities. +This procedure shows how to configure a cluster to disable root login for compliance requirements while maintaining the ability to collect debug zip and tsdump data. ### Before you begin @@ -193,7 +193,9 @@ This procedure shows how to configure a cluster to disable root login for compli CREATE USER debug_user; ~~~ -1. Grant privileges for debug operations. +1. Grant SQL privileges for debug zip collection. + + These privileges are required for `cockroach debug zip` but are **not** required for `cockroach debug tsdump`. **Option 1**: Grant the `admin` role (simplest approach): @@ -214,10 +216,6 @@ This procedure shows how to configure a cluster to disable root login for compli GRANT SYSTEM REPAIRCLUSTER TO debug_user; ~~~ - {{site.data.alerts.callout_info}} - **Note**: `cockroach debug tsdump` does not require any SQL privileges. Only debug zip collection requires the privileges above. - {{site.data.alerts.end}} - ### Step 2: Generate debug_user certificate {% include_cached copy-clipboard.html %} From 3f016b378d600715d3228228fc5802ba32a27617 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 02:16:08 -0500 Subject: [PATCH 13/16] docs: reduce duplication in debug_user documentation Consolidate duplicated content across multiple files to maintain a single source of truth while preserving user experience: - create-user.md: Remove duplicated privilege grant instructions, link to canonical source in authentication.md for details - cockroach-cert.md: Strengthen callout to emphasize certificate generation is one part of the complete setup procedure - authentication.md: Add reference to cockroach-cert.md as the definitive source for certificate generation details Benefits: - Eliminates ~20 lines of duplicated GRANT statements - Maintains authentication.md as canonical source for complete procedure - Each page still provides value with appropriate cross-references - Reduces maintenance burden and potential for inconsistency Co-Authored-By: Claude Sonnet 4.5 --- src/current/v26.1/cockroach-cert.md | 9 ++----- src/current/v26.1/create-user.md | 27 +++---------------- .../security-reference/authentication.md | 4 ++- 3 files changed, 9 insertions(+), 31 deletions(-) diff --git a/src/current/v26.1/cockroach-cert.md b/src/current/v26.1/cockroach-cert.md index 6dc9e7f91d7..fcfca73ed18 100644 --- a/src/current/v26.1/cockroach-cert.md +++ b/src/current/v26.1/cockroach-cert.md @@ -334,7 +334,7 @@ total 40 ### Create a debug_user client certificate (Preview) -New in v26.1: To use the `debug_user` for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when root is disabled: +New in v26.1: To use `debug_user` for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when root is disabled, generate a client certificate: {% include_cached copy-clipboard.html %} ~~~ shell @@ -351,12 +351,7 @@ This creates the following files: The certificate will contain "debug_user" in the CommonName field, which is required for `debug_user` authentication. {{site.data.alerts.callout_info}} -Before using this certificate, you must: - -1. Create the `debug_user` SQL user: `CREATE USER debug_user;` -1. Enable debug_user authentication by starting nodes with the [`--allow-debug-user`]({% link {{ page.version.version }}/cockroach-start.md %}#security) flag - -For complete setup instructions, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). +This certificate is only one part of the setup. For the complete procedure including user creation, privilege grants, and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). {{site.data.alerts.end}} ### List certificates and keys diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index 25af3944b77..d19d82600ff 100644 --- a/src/current/v26.1/create-user.md +++ b/src/current/v26.1/create-user.md @@ -316,35 +316,16 @@ with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} ### Create debug_user for diagnostics (Preview) -New in v26.1: The `debug_user` is a special privileged user for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data when preferred over using the root user, or when root login is disabled. +New in v26.1: The `debug_user` is a special privileged user for collecting [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug tsdump`]({% link {{ page.version.version }}/cockroach-debug-tsdump.md %}) data. For complete setup including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). -{% include_cached copy-clipboard.html %} -~~~ sql -> CREATE USER debug_user; -~~~ - -Grant SQL privileges for debug zip collection. These privileges are required for `cockroach debug zip` but are **not** required for `cockroach debug tsdump`. - -You can either grant the `admin` role (simplest): +Basic user creation: {% include_cached copy-clipboard.html %} ~~~ sql -> GRANT admin TO debug_user; -~~~ - -Or grant specific system privileges required for debug zip collection: - -{% include_cached copy-clipboard.html %} -~~~ sql -> GRANT SYSTEM VIEWACTIVITY TO debug_user; -> GRANT SYSTEM VIEWACTIVITYREDACTED TO debug_user; -> GRANT SYSTEM VIEWCLUSTERMETADATA TO debug_user; -> GRANT SYSTEM VIEWCLUSTERSETTING TO debug_user; -> GRANT SYSTEM VIEWSYSTEMTABLE TO debug_user; -> GRANT SYSTEM REPAIRCLUSTER TO debug_user; +> CREATE USER debug_user; ~~~ -For complete setup instructions including certificate generation and server configuration, see [Disable root login and use debug_user]({% link {{ page.version.version }}/security-reference/authentication.md %}#disable-root-login-and-use-debug_user). +For SQL privilege requirements (needed for debug zip only, not tsdump), see Step 1 in the [debug_user setup procedure]({% link {{ page.version.version }}/security-reference/authentication.md %}#step-1-create-debug_user). ## See also diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index b41a59186b7..63b7e7ae63c 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -218,6 +218,8 @@ This procedure shows how to configure a cluster to disable root login for compli ### Step 2: Generate debug_user certificate +Generate a client certificate for debug_user. See [Create a debug_user client certificate]({% link {{ page.version.version }}/cockroach-cert.md %}#create-a-debug_user-client-certificate-preview) for detailed instructions. + {% include_cached copy-clipboard.html %} ~~~ shell cockroach cert create-client debug_user \ @@ -225,7 +227,7 @@ cockroach cert create-client debug_user \ --ca-key=my-safe-directory/ca.key ~~~ -This creates `client.debug_user.crt` and `client.debug_user.key` in the specified certs directory. +This creates `client.debug_user.crt` and `client.debug_user.key` in the `certs` directory. ### Step 3: Test debug_user access From ac73fff7f3d06f09b1435b9a623ac2e1d036cfce Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 02:24:59 -0500 Subject: [PATCH 14/16] docs: add callout about alternative debug_user setup timing Add informational callout explaining that while it's possible to disable root without setting up debug_user first, doing so later requires a rolling restart and can delay troubleshooting. Recommends the documented workflow (setup debug_user first) without fully documenting the alternative approaches. Co-Authored-By: Claude Sonnet 4.5 --- src/current/v26.1/security-reference/authentication.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index 63b7e7ae63c..cfdce58bf15 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -171,6 +171,10 @@ CockroachDB {{ site.data.products.cloud }} uses a service user named `managed-sq This procedure shows how to configure a cluster to disable root login for compliance requirements while maintaining the ability to collect debug zip and tsdump data. +{{site.data.alerts.callout_info}} +While it is possible to disable root login without first setting up `debug_user`, enabling `debug_user` later when diagnostic data is needed requires a rolling restart of all cluster nodes and at least one other admin user to create it. This can add significant delay during troubleshooting incidents. We recommend setting up `debug_user` before disabling root login to ensure diagnostic capabilities are immediately available when needed. +{{site.data.alerts.end}} + ### Before you begin - You must have an existing CockroachDB cluster From 2ba041b938d4e99911c4465f6161141a5c637033 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 02:30:29 -0500 Subject: [PATCH 15/16] docs: clarify SQL privilege recommendation for debug_user Replace terse statement about privileges not being required for tsdump with fuller explanation that: - Acknowledges tsdump doesn't need SQL privileges - Explains debug zip does require them - Recommends granting upfront to avoid delays during troubleshooting - Notes they can be added later by another admin if needed This provides better context for the decision while still recommending the safer "configure it before you need it" approach. Co-Authored-By: Claude Sonnet 4.5 --- src/current/v26.1/security-reference/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index cfdce58bf15..ad4b33fe329 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -199,7 +199,7 @@ While it is possible to disable root login without first setting up `debug_user` 1. Grant SQL privileges for debug zip collection. - These privileges are required for `cockroach debug zip` but are **not** required for `cockroach debug tsdump`. + While `cockroach debug tsdump` does not require any SQL privileges, these privileges are required for `cockroach debug zip`. Cockroach Labs recommends granting them during initial setup to ensure debug zip capability is immediately available when needed. Another admin user can grant these privileges later if needed, but pre-configuring them avoids delays during troubleshooting. **Option 1**: Grant the `admin` role (simplest approach): From 60669fcb887d27bde4776eee124b98f4adddcb1b Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 20 Feb 2026 02:38:20 -0500 Subject: [PATCH 16/16] docs: soften debug_user setup requirement to recommendation Change "you must set up debug_user" to "it is highly recommended to set up debug_user" to better reflect that while technically possible to enable later, the existing callout already explains why pre-configuration is best practice. --- src/current/v26.1/security-reference/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index ad4b33fe329..4ba2e73886b 100644 --- a/src/current/v26.1/security-reference/authentication.md +++ b/src/current/v26.1/security-reference/authentication.md @@ -105,7 +105,7 @@ This ensures that access to the cluster can always be recovered, but it also mea {{site.data.alerts.callout_danger}} **Important Prerequisites**: -- Before disabling root, you must set up the `debug_user` for troubleshooting operations. See [Using debug_user for diagnostics](#using-debug_user-for-diagnostics). +- Before disabling root, it is highly recommended to set up the `debug_user` for troubleshooting operations. See [Using debug_user for diagnostics](#using-debug_user-for-diagnostics). - Ensure no cluster or client certificates contain "root" in their SAN (Subject Alternative Name) fields, as these will be blocked. - The cluster does not validate that `debug_user` is configured before allowing root to be disabled.