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 a9f1b678439..fcfca73ed18 100644 --- a/src/current/v26.1/cockroach-cert.md +++ b/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) + +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 +$ 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 %} diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index a34784aef86..6d386a3404c 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/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.

**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. 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 -`--user` | The SQL user that will own the client session. Valid values are `root` and `debug_user`.

**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) + +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 %}) diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index fb1ebef87c3..c3297ba9b92 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/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.

**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 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 -`--user` | The SQL user that will own the client session. Valid values are `root` and `debug_user`.

**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) + +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 %}) diff --git a/src/current/v26.1/cockroach-start.md b/src/current/v26.1/cockroach-start.md index 831f0a9e449..42f9e038ea1 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 %}) diff --git a/src/current/v26.1/create-user.md b/src/current/v26.1/create-user.md index 6c30538f42a..d19d82600ff 100644 --- a/src/current/v26.1/create-user.md +++ b/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) + +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). + +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 %}) diff --git a/src/current/v26.1/security-reference/authentication.md b/src/current/v26.1/security-reference/authentication.md index 82638080061..4ba2e73886b 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, 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. + +{{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 [`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 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 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. ## Default behavior @@ -129,4 +165,173 @@ 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 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 +- 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 a user with admin privileges (such 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 SQL privileges for debug zip collection. + + 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): + + {% 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; + ~~~ + +### 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 \ + --certs-dir=certs \ + --ca-key=my-safe-directory/ca.key +~~~ + +This creates `client.debug_user.crt` and `client.debug_user.key` in the `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