Docs for disabling root and enabling debug_user#22682
Open
Conversation
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
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
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
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
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
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
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
mikeCRL
commented
Feb 17, 2026
Contributor
Author
mikeCRL
left a comment
mikeCRL
left a comment
There was a problem hiding this comment.
@souravcrl Submitting for your review with a couple inline comments/questions. Thank you.
Comment on lines
170
to
194
| ## 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; | ||
| ~~~ |
Contributor
Author
There was a problem hiding this comment.
@souravcrl Must debug_user actually be set up before disabling root (or is that the only workflow we want to publish)?
I am wondering if there are alternative workflows that are possible (and, if so, worth documenting) where a customer can disable root without setting up debug_user; then, when troubleshooting is needed:
- Rolling restart to re-enable root, or, if preferable, make use of a different user with
adminprivileges - Collect debug data with root, or with the other admin user, or just use one of these to set up debug_user at that time, and use it
- Remove any users/roles, to return to prior state, if preferred
I could leave the doc as-is and we can save this for a follow-up if worthwhile. Please let me know what you think.
Regardless, should I expand "Connect to the cluster as root" to say "Connect to the cluster as root or another user with the admin role or CREATEROLE privilege?"
There was a problem hiding this comment.
It seems only admin users can create or drop roles(https://www.cockroachlabs.com/docs/v25.2/security-reference/authorization#admin-role), so if there are other admin roles, it seems we can maybe postpone creation of debug_user.
On the contrary for the debug zip collection workflow, it is actually dependent on granting of certain privileges to debug_user which obs team is managing, so will defer the question to them as the user granting the privilege must have permission to do the same. cc: @aa-joshi
There was a problem hiding this comment.
There are couple of ways with which we can generate debug.zip with debug_user:
- grant admin privileges to
debug_user. - grant below privileges to
debug_user:
2.1. VIEWACTIVITY
2.2. VIEWACTIVITYREDACTED
2.3 VIEWCLUSTERMETADATA
2.4 VIEWCLUSTERSETTING
2.5 VIEWSYSTEMTABLE
2.6 REPAIRCLUSTER
2.7 REPLICATION
Note: As of v25.2 REPLICATION is deprecated. Instead, use the REPLICATIONSOURCE and REPLICATIONDEST privileges at the table level.
Comment on lines
196
to
201
| 1. Grant admin privileges (optional, but recommended for full debug access): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| GRANT admin TO debug_user; | ||
| ~~~ |
Contributor
Author
There was a problem hiding this comment.
@souravcrl Is this accurate?
If it lacks the SQL admin role, will debug_user collect some/all/none of the debug zip/tsdump info?
There was a problem hiding this comment.
This again relates to the debug zip collection part(independent of the user having rpc access). I will again defer this to @aa-joshi
There was a problem hiding this comment.
It will fetch the data which is not tied to privileges. Tsdump is not tied with any privileges.
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
souravcrl
approved these changes
Feb 18, 2026
souravcrl
left a comment
souravcrl
left a comment
There was a problem hiding this comment.
lgtm for the access and authorization changes bits.
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
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.
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.
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
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves DOC-15543 DOC-15545