Docs for disabling root and enabling debug_user#22682
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.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
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.
| ## 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; | ||
| ~~~ |
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.
| 1. Grant admin privileges (optional, but recommended for full debug access): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| GRANT admin TO debug_user; | ||
| ~~~ |
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
left a comment
souravcrl
left a comment
There was a problem hiding this comment.
lgtm for the access and authorization changes bits.
3 participants
Resolves DOC-15543 DOC-15545