From af48bd737e934ec07cde8a7d9952647e45344694 Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Wed, 17 Jul 2024 15:20:14 -0700 Subject: [PATCH 1/2] [DOC-10012] Improve docs about statement bundle privileges --- src/current/v23.1/explain-analyze.md | 13 +++++++++++-- src/current/v23.2/explain-analyze.md | 14 ++++++++++++-- src/current/v24.1/explain-analyze.md | 14 ++++++++++++-- src/current/v24.2/authorization.md | 22 ++-------------------- src/current/v24.2/explain-analyze.md | 14 ++++++++++++-- 5 files changed, 49 insertions(+), 28 deletions(-) diff --git a/src/current/v23.1/explain-analyze.md b/src/current/v23.1/explain-analyze.md index ec0d618c4a2..1862ca7226c 100644 --- a/src/current/v23.1/explain-analyze.md +++ b/src/current/v23.1/explain-analyze.md @@ -33,7 +33,16 @@ Parameter | Description ## Required privileges -The user requires the appropriate [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) for the statement being explained. +To generate a statement bundle, you must have the [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) to execute the SQL statement, as well as the privileges required to collect the statement bundle. + +To find the minimum required privileges for a SQL statement, refer to the [SQL reference documentation]({% link {{ page.version.version}}/sql-statements.md %}) for the statement. + +A user with the `VIEWACTIVITY` [system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) can generate a bundle for any statement. To grant this privilege, issue the following SQL commands. Replace `{user}` with the user's ID. + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER USER {user} WITH VIEWACTIVITY; +~~~ ## Success responses @@ -172,7 +181,7 @@ You can obtain this ZIP file by following the link provided in the `EXPLAIN ANAL ## `REDACT` option -`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. +`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. You can use the `REDACT` flag in combination with the [`PLAN`](#plan-option) option (including the `VERBOSE` and `TYPES` [suboptions](#plan-suboptions)) to redact sensitive values in the physical statement plan, and with the [`DEBUG`](#debug-option) option to redact values in the statement bundle. diff --git a/src/current/v23.2/explain-analyze.md b/src/current/v23.2/explain-analyze.md index 994f6d70106..4411d277091 100644 --- a/src/current/v23.2/explain-analyze.md +++ b/src/current/v23.2/explain-analyze.md @@ -33,7 +33,17 @@ Parameter | Description ## Required privileges -The user requires the appropriate [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) for the statement being explained. +To generate a statement bundle, you must have the [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) to execute the SQL statement, as well as the privileges required to collect the statement bundle. + +To find the minimum required privileges for a SQL statement, refer to the [SQL reference documentation]({% link {{ page.version.version}}/sql-statements.md %}) for the statement. + +A user with the `VIEWACTIVITY` [system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) can generate a bundle for any statement. To grant this privilege, issue the following SQL commands. Replace `{user}` with the user's ID. + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER USER {user} WITH VIEWACTIVITY; +GRANT SYSTEM VIEWSYSTEMTABLE TO {user}; +~~~ ## Success responses @@ -172,7 +182,7 @@ You can obtain this ZIP file by following the link provided in the `EXPLAIN ANAL ## `REDACT` option -`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. +`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. You can use the `REDACT` flag in combination with the [`PLAN`](#plan-option) option (including the `VERBOSE` and `TYPES` [suboptions](#plan-suboptions)) to redact sensitive values in the physical statement plan, and with the [`DEBUG`](#debug-option) option to redact values in the statement bundle. diff --git a/src/current/v24.1/explain-analyze.md b/src/current/v24.1/explain-analyze.md index 80e1d4a4e4d..68cb8e8c7d5 100644 --- a/src/current/v24.1/explain-analyze.md +++ b/src/current/v24.1/explain-analyze.md @@ -33,7 +33,17 @@ Parameter | Description ## Required privileges -The user requires the appropriate [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) for the statement being explained. +To generate a statement bundle, you must have the [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) to execute the SQL statement, as well as the privileges required to collect the statement bundle. + +To find the minimum required privileges for a SQL statement, refer to the [SQL reference documentation]({% link {{ page.version.version}}/sql-statements.md %}) for the statement. + +A user with the `VIEWACTIVITY` [system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) can generate a bundle for any statement. To grant this privilege, issue the following SQL commands. Replace `{user}` with the user's ID. + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER USER {user} WITH VIEWACTIVITY; +GRANT SYSTEM VIEWSYSTEMTABLE TO {user}; +~~~ ## Success responses @@ -172,7 +182,7 @@ You can obtain this ZIP file by following the link provided in the `EXPLAIN ANAL ## `REDACT` option -`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. +`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. You can use the `REDACT` flag in combination with the [`PLAN`](#plan-option) option (including the `VERBOSE` and `TYPES` [suboptions](#plan-suboptions)) to redact sensitive values in the physical statement plan, and with the [`DEBUG`](#debug-option) option to redact values in the statement bundle. diff --git a/src/current/v24.2/authorization.md b/src/current/v24.2/authorization.md index 6eec67c32cd..c82776db588 100644 --- a/src/current/v24.2/authorization.md +++ b/src/current/v24.2/authorization.md @@ -7,7 +7,7 @@ docs_area: manage This page documents procedures for managing the lifecycle of SQL users and roles on CockroachDB clusters. -Procedures for managing access are covered in [Managing Access in CockroachDB {{ site.data.products.cloud }}](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access). +For clusters in CockroachDB {{ site.data.products.cloud }}, refer to [Managing Access in CockroachDB {{ site.data.products.cloud }}](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access). {{site.data.alerts.callout_info}} The concept of *Organization user* is distinct from Authorization of *SQL user/role* on clusters is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users within CockroachDB {{ site.data.products.cloud }} organizations. @@ -15,8 +15,8 @@ The concept of *Organization user* is distinct from Authorization of *SQL user/r Learn more: [Overview of the CockroachDB Cloud authorization model](https://www.cockroachlabs.com/docs/cockroachcloud/authorization#overview-of-the-cockroachdb-cloud-two-level-authorization-model) {{site.data.alerts.end}} - For reference documentation and explanation of related concepts, see [Security Reference—Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %}). + ## Create CockroachDB users Use the [`CREATE USER`]({% link {{ page.version.version }}/create-user.md %}) and [`DROP USER`]({% link {{ page.version.version }}/drop-user.md %}) statements to create and remove users, the [`ALTER USER`]({% link {{ page.version.version }}/alter-user.md %}) statement to add or change a user's password and role options, the [`GRANT`]({% link {{ page.version.version }}/grant.md %}) and [`REVOKE`]({% link {{ page.version.version }}/revoke.md %}) statements to manage the user’s privileges, and the [`SHOW USERS`]({% link {{ page.version.version }}/show-users.md %}) statement to list users. @@ -27,7 +27,6 @@ A new user must be granted the required privileges for each database and table t By default, a new user belongs to the `public` role and has no privileges other than those assigned to the `public` role. {{site.data.alerts.end}} - ## Create and manage roles To create and manage your cluster's roles, use the following statements: @@ -41,19 +40,6 @@ Statement | Description [`SHOW ROLES`]({% link {{ page.version.version }}/show-roles.md %}) | List the roles for all databases. [`SHOW GRANTS`]({% link {{ page.version.version }}/show-grants.md %}) | List the privileges granted to users. - - - - - - - - - - - - - For example, suppose a cluster contains a role named `cockroachlabs`, and a user named `max` is a member of the `cockroachlabs` role: ~~~ @@ -100,10 +86,6 @@ max@localhost:26257/db> SHOW CREATE TABLE albums; (1 row) ~~~ - - - - ## Example
diff --git a/src/current/v24.2/explain-analyze.md b/src/current/v24.2/explain-analyze.md index 80e1d4a4e4d..68cb8e8c7d5 100644 --- a/src/current/v24.2/explain-analyze.md +++ b/src/current/v24.2/explain-analyze.md @@ -33,7 +33,17 @@ Parameter | Description ## Required privileges -The user requires the appropriate [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) for the statement being explained. +To generate a statement bundle, you must have the [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) to execute the SQL statement, as well as the privileges required to collect the statement bundle. + +To find the minimum required privileges for a SQL statement, refer to the [SQL reference documentation]({% link {{ page.version.version}}/sql-statements.md %}) for the statement. + +A user with the `VIEWACTIVITY` [system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) can generate a bundle for any statement. To grant this privilege, issue the following SQL commands. Replace `{user}` with the user's ID. + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER USER {user} WITH VIEWACTIVITY; +GRANT SYSTEM VIEWSYSTEMTABLE TO {user}; +~~~ ## Success responses @@ -172,7 +182,7 @@ You can obtain this ZIP file by following the link provided in the `EXPLAIN ANAL ## `REDACT` option -`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. +`EXPLAIN ANALYZE (REDACT)` executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as `‹×›` in the output. You can use the `REDACT` flag in combination with the [`PLAN`](#plan-option) option (including the `VERBOSE` and `TYPES` [suboptions](#plan-suboptions)) to redact sensitive values in the physical statement plan, and with the [`DEBUG`](#debug-option) option to redact values in the statement bundle. From 3e652eed8610c011163b8abf370677c5f72e981b Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Tue, 23 Jul 2024 10:48:05 -0700 Subject: [PATCH 2/2] Remove stray modified file --- src/current/v24.2/authorization.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/current/v24.2/authorization.md b/src/current/v24.2/authorization.md index c82776db588..6eec67c32cd 100644 --- a/src/current/v24.2/authorization.md +++ b/src/current/v24.2/authorization.md @@ -7,7 +7,7 @@ docs_area: manage This page documents procedures for managing the lifecycle of SQL users and roles on CockroachDB clusters. -For clusters in CockroachDB {{ site.data.products.cloud }}, refer to [Managing Access in CockroachDB {{ site.data.products.cloud }}](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access). +Procedures for managing access are covered in [Managing Access in CockroachDB {{ site.data.products.cloud }}](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access). {{site.data.alerts.callout_info}} The concept of *Organization user* is distinct from Authorization of *SQL user/role* on clusters is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users within CockroachDB {{ site.data.products.cloud }} organizations. @@ -15,8 +15,8 @@ The concept of *Organization user* is distinct from Authorization of *SQL user/r Learn more: [Overview of the CockroachDB Cloud authorization model](https://www.cockroachlabs.com/docs/cockroachcloud/authorization#overview-of-the-cockroachdb-cloud-two-level-authorization-model) {{site.data.alerts.end}} -For reference documentation and explanation of related concepts, see [Security Reference—Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %}). +For reference documentation and explanation of related concepts, see [Security Reference—Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %}). ## Create CockroachDB users Use the [`CREATE USER`]({% link {{ page.version.version }}/create-user.md %}) and [`DROP USER`]({% link {{ page.version.version }}/drop-user.md %}) statements to create and remove users, the [`ALTER USER`]({% link {{ page.version.version }}/alter-user.md %}) statement to add or change a user's password and role options, the [`GRANT`]({% link {{ page.version.version }}/grant.md %}) and [`REVOKE`]({% link {{ page.version.version }}/revoke.md %}) statements to manage the user’s privileges, and the [`SHOW USERS`]({% link {{ page.version.version }}/show-users.md %}) statement to list users. @@ -27,6 +27,7 @@ A new user must be granted the required privileges for each database and table t By default, a new user belongs to the `public` role and has no privileges other than those assigned to the `public` role. {{site.data.alerts.end}} + ## Create and manage roles To create and manage your cluster's roles, use the following statements: @@ -40,6 +41,19 @@ Statement | Description [`SHOW ROLES`]({% link {{ page.version.version }}/show-roles.md %}) | List the roles for all databases. [`SHOW GRANTS`]({% link {{ page.version.version }}/show-grants.md %}) | List the privileges granted to users. + + + + + + + + + + + + + For example, suppose a cluster contains a role named `cockroachlabs`, and a user named `max` is a member of the `cockroachlabs` role: ~~~ @@ -86,6 +100,10 @@ max@localhost:26257/db> SHOW CREATE TABLE albums; (1 row) ~~~ + + + + ## Example