diff --git a/src/current/v25.4/cockroach-debug-zip.md b/src/current/v25.4/cockroach-debug-zip.md index 3390d7f0e61..6bdf18b4627 100644 --- a/src/current/v25.4/cockroach-debug-zip.md +++ b/src/current/v25.4/cockroach-debug-zip.md @@ -115,8 +115,8 @@ Flag | Description `--include-range-info` | Include one file per node with information about the KV ranges stored on that node, in `nodes/{node ID}/ranges.json`.

This information can be vital when debugging issues that involve the [KV layer]({% link {{ page.version.version }}/architecture/overview.md %}#layers) (which includes everything below the SQL layer), such as data placement, load balancing, performance or other behaviors. In certain situations, on large clusters with large numbers of ranges, these files can be omitted if and only if the issue being investigated is already known to be in another layer of the system (for example, an error message about an unsupported feature or incompatible value in a SQL schema change or statement). However, many higher-level issues are ultimately related to the underlying KV layer described by these files. Only set this to `false` if directed to do so by Cockroach Labs support.

In addition, include problem ranges information in `reports/problemranges.json`.

**Default:** true `--include-running-job-traces` | Include information about each traceable job that is running or reverting (such as [backup]({% link {{ page.version.version }}/backup.md %}), [restore]({% link {{ page.version.version }}/restore.md %}), [import]({% link {{ page.version.version }}/import-into.md %}), [physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %})) in `jobs/*/*/trace.zip` files. This involves collecting cluster-wide traces for each running job in the cluster.

**Default:** true `--nodes` | Specify nodes to inspect as a comma-separated list or range of node IDs. For example:

`--nodes=1,10,13-15` -`--redact` | Redact sensitive data from the generated `.zip`, with the exception of range keys, which must remain unredacted because they are essential to support CockroachDB. This flag replaces the deprecated `--redact-logs` flag, which only applied to log messages contained within `.zip`.

To redact hostnames and IP addresses in `.json` files, such as `status.json`, `details.json`, and `ranges.json`, you will also need to enable the [cluster setting `debug.zip.redact_addresses.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-debug-zip-redact-addresses-enabled). Note that enabling this cluster setting will not redact all hostnames and IP addresses in the `nodes.json` and `gossip.json` files.

For examples, refer to [Redact sensitive information](#redact-sensitive-information). -`--redact-logs` | **Deprecated** Redact sensitive data from collected log files only. Use the `--redact` flag instead, which redacts sensitive data across the entire generated `.zip` as well as the collected log files. Passing the `--redact-logs` flag will be interpreted as the `--redact` flag. +`--redact` | Redact sensitive data in the generated `.zip` file. This flag replaces the deprecated [`--redact-logs`](#redact-logs) flag.

This flag redacts the following data:This flag does **not** affect the following data:For examples, refer to [Redact sensitive information](#redact-sensitive-information). +`--redact-logs` | **Deprecated** Redact sensitive data from collected log files only. Use the `--redact` flag instead, which redacts sensitive data across the entire generated `.zip` as well as the collected log files. Passing the `--redact-logs` flag will be interpreted as the `--redact` flag. `--timeout` | In the process of generating a debug zip, many internal requests are made. Each request is allowed the maximum duration specified by the timeout. If an internal request does not complete within the timeout duration, an error is displayed for that request and its artifact is not included in the zip file.

The timeout is suffixed with `s` (seconds), `m` (minutes), or `h` (hours).

**Default:** `60s` `--validate-zip-file` | Validate debug zip file after generation. This is a quick check to validate whether the generated zip file is valid and not corrupted.

**Default:** `true` @@ -180,7 +180,7 @@ $ cockroach debug zip ./cockroach-data/logs/debug.zip --include-files=*.log #### Log redaction -Example of a log string without redaction enabled: +Example of a log string without [`--redact`](#redact) enabled: ~~~ server/server.go:1423 ⋮ password of user ‹admin› was set to ‹"s3cr34?!@x_"› @@ -197,6 +197,39 @@ $ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host server/server.go:1423 ⋮ password of user ‹×› was set to ‹×› ~~~ +#### Cluster settings redaction + +Example cluster settings in `crdb_internal.cluster_settings.txt` without [`--redact`](#redact) enabled: + +~~~ +variable value type public sensitive reportable description default_value origin +... +cluster.organization Cockroach Labs Testing s t f f organization name override +... +server.identity_map.configuration s t t f system-identity to database-username mappings default +~~~ + +`server.identity_map.configuration` is always redacted, since `sensitive` equals `true`. + +Enable log redaction: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host=200.100.50.25 +~~~ + +Cluster settings in `crdb_internal.cluster_settings.txt` with [`--redact`](#redact) enabled: + +~~~ +variable value type public sensitive reportable description default_value origin +... +cluster.organization s t f f organization name override +... +server.identity_map.configuration s t t f system-identity to database-username mappings default +~~~ + +`server.identity_map.configuration` is still redacted. `cluster.organization` is now redacted since `reportable` equals `false` and the `Cockroach Labs Testing` value is not the default value (in this case, the empty string). + #### Hostname and IP address redaction Example of `status.json` without hostname and IP address redaction enabled: @@ -215,7 +248,7 @@ Example of `status.json` without hostname and IP address redaction enabled: } ~~~ -First, [enable the cluster setting]({% link {{ page.version.version }}/set-cluster-setting.md %}): +Enable hostname and IP address redaction with the [`debug.zip.redact_addresses.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-debug-zip-redact-addresses-enabled) cluster setting: {% include_cached copy-clipboard.html %} ~~~ sql @@ -223,10 +256,10 @@ SET CLUSTER SETTING debug.zip.redact_addresses.enabled = true; ~~~ {{site.data.alerts.callout_info}} -Enabling the `debug.zip.redact_addresses.enabled` cluster setting will not redact all hostnames and IP addresses in the `nodes.json` and `gossip.json` files. +Some hostnames and IP addresses in the `nodes.json` and `gossip.json` files are **never** redacted, even when `debug.zip.redact_addresses.enabled` is enabled. {{site.data.alerts.end}} -Then, generate `.zip` with log redaction as well as hostname and IP address redaction: +Generate `.zip` with [`--redact`](#redact) enabled: {% include_cached copy-clipboard.html %} ~~~ shell