Docs for disabling root and enabling debug_user

.gitignore

@@ -19,3 +19,4 @@ node_modules
 /src/*/vendor/
 spec_30_enriched.json
 .bundle/config
+src/current/changes.md

src/current/_includes/releases/v26.1/v26.1.0-alpha.2.md

@@ -6,7 +6,7 @@ Release Date: December 11, 2025
 
 <h3 id="v26-1-0-alpha-2-security-updates">Security updates</h3>
 
-- 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.
 

src/current/v26.1/cockroach-cert.md

@@ -332,6 +332,28 @@ total 40
 -rw-------  1 maxroach  maxroach  1.6K Jul 10 14:17 node.key
 ~~~
 
+### Create a debug_user client certificate (Preview)
+
+<span class="version-tag">New in v26.1:</span> 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
+$ 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}}
+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
 
 {% include_cached copy-clipboard.html %}

src/current/v26.1/cockroach-debug-tsdump.md

@@ -60,8 +60,8 @@ 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.<br><br>**Env Variable:** `COCKROACH_HOST`<br>**Default:** `localhost:26257`
 `--insecure` | Use an insecure connection.<br><br>**Env Variable:** `COCKROACH_INSECURE`<br>**Default:** `false`
+`--user` | <span class="version-tag">New in v26.1:</span> 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.<br><br>**Env Variable:** `COCKROACH_USER`<br>**Default:** `root`
 <a name="sql-flag-url"></a> `--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).<br><br>**Env Variable:** `COCKROACH_URL`<br>**Default:** no URL
-`--user` |  The SQL user that will own the client session. Valid values are `root` and `debug_user`.<br><br>**Default:** `root`
 
 ### Logging
 
@@ -181,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)
+
+<span class="version-tag">New in v26.1:</span> 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 %})

src/current/v26.1/cockroach-debug-zip.md

@@ -130,8 +130,8 @@ 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. <br><br>**Env Variable:** `COCKROACH_HOST`<br>**Default:** `localhost:26257`
 `--insecure` | Use an insecure connection.<br><br>**Env Variable:** `COCKROACH_INSECURE`<br>**Default:** `false`
+`--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).<br><br><span class="version-tag">New in v26.1:</span> 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.<br><br>**Env Variable:** `COCKROACH_USER`<br>**Default:** `root`
 <a name="sql-flag-url"></a> `--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).<br><br>**Env Variable:** `COCKROACH_URL`<br>**Default:** no URL
-`--user` |  The SQL user that will own the client session. Valid values are `root` and `debug_user`.<br><br>**Default:** `root`
 
 ### Logging
 
@@ -283,6 +283,24 @@ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host=2
 }
 ~~~
 
+### Generate a debug zip with debug_user (Preview)
+
+<span class="version-tag">New in v26.1:</span> 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=<node-address> \
+--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 %})

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**.<br><br>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.<br><br>**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.<br><br>**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 name="flags-cert-principal-map"></a> |  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` | <span class="version-tag">New in v26.1:</span> 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.<br><br>This is a [Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#feature-availability-phases) feature.<br><br>**Default:** `false`
+`--disallow-root-login` | <span class="version-tag">New in v26.1:</span> 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.<br><br>{{site.data.alerts.callout_danger}}<strong>Important:</strong> 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}}<br><br>This is a [Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}#feature-availability-phases) feature.<br><br>**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. <br /><br /> 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 %}).
 <a name="flags-external-io-disable-http"></a>`--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. <br><br>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=<node address> \
+--join=<join addresses> \
+--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 %})

src/current/v26.1/create-user.md

@@ -314,6 +314,19 @@ with_password              | {VALID UNTIL=2025-10-10 00:00:00+00:00}   | {}
 (11 rows)
 ~~~
 
+### Create debug_user for diagnostics (Preview)
+
+<span class="version-tag">New in v26.1:</span> 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).
+
+Basic user creation:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> CREATE USER 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
 
 - [Authorization]({% link {{ page.version.version }}/authorization.md %})