diff --git a/src/current/_includes/v26.1/misc/session-vars.md b/src/current/_includes/v26.1/misc/session-vars.md index cbe1de7d54f..39c8e0e75e3 100644 --- a/src/current/_includes/v26.1/misc/session-vars.md +++ b/src/current/_includes/v26.1/misc/session-vars.md @@ -1,7 +1,7 @@ | Variable name | Description | Initial value | Modify with [`SET`]({% link {{ page.version.version }}/set-vars.md %})? | View with [`SHOW`]({% link {{ page.version.version }}/show-vars.md %})? | |---|---|---|---|---| | `always_distribute_full_scans` | When set to `on`, full table scans are always [distributed]({% link {{ page.version.version }}/architecture/sql-layer.md %}#distsql). | `off` | Yes | Yes | -| `allow_unsafe_internals` | Controls access to unsafe internals in the `system` database and the [`crdb_internal`]({% link {{ page.version.version }}/crdb-internal.md %}#access-control) schema. When set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}).

**Warning**: In a future major release, this session variable will default to `off`. To [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. | `on` | Yes | Yes | +| `allow_unsafe_internals` | Controls access to unsafe internals in the `system` database and the [`crdb_internal`]({% link {{ page.version.version }}/crdb-internal.md %}#access-control) schema. When set to `off`, queries to the `system` and `crdb_internal` namespaces will fail unless access is manually enabled. You should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}).

Usage of unsafe internals is [audited]({% link {{ page.version.version }}/logging-use-cases.md %}#example-unsafe-internals) via the `SENSITIVE_ACCESS` logging channel. | `off` | Yes | Yes | | `application_name` | The current application name for statistics collection. | Empty string, or `cockroach` for sessions from the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}). | Yes | Yes | | `autocommit_before_ddl` | When the [`autocommit_before_ddl` session setting]({% link {{page.version.version}}/set-vars.md %}#autocommit-before-ddl) is set to `on`, any schema change statement that is sent during an [explicit transaction]({% link {{page.version.version}}/transactions.md %}) will cause the transaction to [commit]({% link {{page.version.version}}/commit-transaction.md %}) before executing the schema change. This is useful because [CockroachDB does not fully support multiple schema changes in a single transaction]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions). : This setting is enabled by default. To disable it for [all roles]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users), issue the following statement: `ALTER ROLE ALL SET autocommit_before_ddl = false` | `on` | Yes | Yes | | `bytea_output` | The [mode for conversions from `STRING` to `BYTES`]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). | hex | Yes | Yes | diff --git a/src/current/v26.1/crdb-internal.md b/src/current/v26.1/crdb-internal.md index bc26c48bd8f..de530166d27 100644 --- a/src/current/v26.1/crdb-internal.md +++ b/src/current/v26.1/crdb-internal.md @@ -9,14 +9,7 @@ The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-c ## Access control -CockroachDB treats most objects in the `crdb_internal` schema, as well as tables and built-in functions in the `system` database, as *unsafe internals*. Access to these objects is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). This variable defaults to `on`. Set it to `off` to prevent unintentional access unless explicitly advised by Cockroach Labs. - -{% include_cached copy-clipboard.html %} -~~~ sql -SET allow_unsafe_internals = off; -~~~ - -With `allow_unsafe_internals` set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). +CockroachDB treats most objects in the `crdb_internal` schema, as well as tables and built-in functions in the `system` database, as *unsafe internals*. Access to these objects is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). This variable defaults to `off`, restricting access to the `system` and `crdb_internal` namespaces. Queries to these namespaces will fail unless access is manually enabled. With `allow_unsafe_internals` set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). {{site.data.alerts.callout_info}} If you need information not available through production-supported [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}), contact your account team or contact [Cockroach Labs support](https://support.cockroachlabs.com). @@ -31,11 +24,7 @@ SET allow_unsafe_internals = on; Some `SHOW commands`, such as [`SHOW DATABASES`]({% link {{ page.version.version }}/show-databases.md %}), and CockroachDB tools, such as the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) and [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}), rely on internal queries that access restricted data. These commands and tools are designed to bypass the `allow_unsafe_internals` setting and continue to function even when direct access is disabled. -CockroachDB emits log events to the [`SENSITIVE_ACCESS` channel]({% link {{ page.version.version }}/logging-use-cases.md %}#example-unsafe-internals) when a user overrides or is denied access to unsafe internals, creating a record of emergency access to system internals. Monitor these logs to ensure that neither workloads nor you and your users are unintentionally accessing unsafe internals. - -{{site.data.alerts.callout_danger}} -In a future major release, the `allow_unsafe_internals` session variable will default to `off`. To prepare for this change and [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. -{{site.data.alerts.end}} +CockroachDB emits log events to the [`SENSITIVE_ACCESS` channel]({% link {{ page.version.version }}/logging-use-cases.md %}#example-unsafe-internals) when a user overrides or is denied access to unsafe internals, creating an audit record of access to system internals. Monitor these logs to ensure that neither workloads nor you and your users are unintentionally accessing unsafe internals. diff --git a/src/current/v26.1/logging-use-cases.md b/src/current/v26.1/logging-use-cases.md index e0ba1ec6533..f0498e381d7 100644 --- a/src/current/v26.1/logging-use-cases.md +++ b/src/current/v26.1/logging-use-cases.md @@ -240,7 +240,7 @@ All possible `SESSIONS` event types are detailed in the [reference documentation ### SENSITIVE_ACCESS -The [`SENSITIVE_ACCESS`]({% link {{ page.version.version }}/logging.md %}#sensitive_access) channel logs SQL audit events. These include all queries run against [audited tables]({% link {{ page.version.version }}/alter-table.md %}#experimental_audit), when enabled, and queries executed by users with the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) role. It also logs when a user overrides or is denied access by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), generating a record of emergency access to system internals. +The [`SENSITIVE_ACCESS`]({% link {{ page.version.version }}/logging.md %}#sensitive_access) channel logs SQL audit events. These include all queries run against [audited tables]({% link {{ page.version.version }}/alter-table.md %}#experimental_audit), when enabled, and queries executed by users with the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) role. It also logs when a user overrides or is denied access by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), creating an audit log of access to system internals. #### Example: Audit events @@ -277,11 +277,9 @@ All possible `SENSITIVE_ACCESS` event types are detailed in the [reference docum #### Example: Unsafe internals -{{site.data.alerts.callout_danger}} -In a future major release, the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) will default to `off`. To [assess potential downstream impacts](#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. -{{site.data.alerts.end}} +The [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) defaults to `off`, restricting access to the `system` and `crdb_internal` namespaces. Queries to these namespaces will fail unless access is manually enabled. -CockroachDB emits log events to the `SENSITIVE_ACCESS` channel when a user overrides or is denied access to [unsafe internals]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), creating a log of emergency access to system internals. +CockroachDB emits log events to the `SENSITIVE_ACCESS` channel when a user overrides or is denied access to [unsafe internals]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), creating an audit log of access to system internals. The following events may be logged to the `SENSITIVE_ACCESS` channel, depending on whether the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) is enabled: @@ -314,22 +312,25 @@ W250930 19:51:01.128927 464484 8@util/log/event_log.go:90 ⋮ [T1,Vsystem,n1,cli ##### Unsafe internals disabled -To assess potential downstream impacts, disable `allow_unsafe_internals` in a test or staging environment. Monitoring tools or scripts that rely on these internals may be affected. `unsafe_internals_denied` events identify which tools or scripts attempted to access these internals. +By default, `allow_unsafe_internals` is disabled. Monitoring tools or scripts that rely on these internals may be affected. `unsafe_internals_denied` events identify which tools or scripts attempted to access these internals. -This example shows how to identify users denied access to unsafe internal tables. +This example shows how denied access to unsafe internal tables is logged. -This command disables access to unsafe internals for the user `can_not_access_unsafe_internals`: +Since `allow_unsafe_internals` defaults to `off`, users cannot access unsafe internals unless explicitly enabled. When a user without access attempts to access an unsafe internal object, the event is logged. + +For example, when the user `can_not_access_unsafe_internals` (who has the default `off` setting) connects to a session and attempts to access an unsafe internal object: {% include_cached copy-clipboard.html %} ~~~ sql -ALTER ROLE can_not_access_unsafe_internals SET allow_unsafe_internals = off; +SELECT count(*) FROM crdb_internal.active_range_feeds; ~~~ -When the user `can_not_access_unsafe_internals` connects to a session and attempts to access an unsafe internal object, the event is logged: +The following error message appears: -{% include_cached copy-clipboard.html %} -~~~ sql -SELECT count(*) FROM crdb_internal.active_range_feeds; +~~~ +ERROR: Access to crdb_internal and system is restricted. +SQLSTATE: 42501 +HINT: These interfaces are unsupported in production. To proceed, set the session variable allow_unsafe_internals = true (not recommended), or contact Cockroach Labs for a supported alternative. ~~~ This `unsafe_internals_denied` event indicates that access to the internal table `crdb_internal.active_range_feeds` was denied for the user `can_not_access_unsafe_internals`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement: diff --git a/src/current/v26.1/system-catalogs.md b/src/current/v26.1/system-catalogs.md index 3f2ff6fa31e..f3281dd994e 100644 --- a/src/current/v26.1/system-catalogs.md +++ b/src/current/v26.1/system-catalogs.md @@ -14,11 +14,7 @@ The following system catalogs are available as schemas preloaded to every databa - [`pg_catalog`]({% link {{ page.version.version }}/pg-catalog.md %}), a schema provided for compatibility with PostgreSQL. - [`pg_extension`]({% link {{ page.version.version }}/pg-extension.md %}), a schema catalog with information about CockroachDB extensions. -Access to the `crdb_internal` schema and to tables and built-in functions in the `system` database is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). For more information, see [`crdb_internal` access control]({% link {{ page.version.version }}/crdb-internal.md %}#access-control). The `system` and `crdb_internal` schemas are intended for advanced support scenarios only, and should be accessed under the guidance of Cockroach Labs. - -{{site.data.alerts.callout_danger}} -In a future major release, the `allow_unsafe_internals` session variable will default to `off`. To prepare for this change and [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. -{{site.data.alerts.end}} +Access to the `crdb_internal` schema and to tables and built-in functions in the `system` database is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals), which defaults to `off`. Queries to these namespaces will fail unless access is manually enabled. Usage is also audited via the [`SENSITIVE_ACCESS` logging channel]({% link {{ page.version.version }}/logging-use-cases.md %}#example-unsafe-internals). For more information, see [`crdb_internal` access control]({% link {{ page.version.version }}/crdb-internal.md %}#access-control). The `system` and `crdb_internal` schemas are intended for advanced support scenarios only, and should be accessed under the guidance of Cockroach Labs. {{site.data.alerts.callout_danger}} Tables in the system catalogs have varying levels of stability. Not all system catalog tables are meant for programmatic purposes. For more information, see [API Support Policy]({% link {{ page.version.version }}/api-support-policy.md %}).