From 07281e4647e117849427563b256592a120f0ad83 Mon Sep 17 00:00:00 2001 From: Pavel Moravec Date: Tue, 11 Aug 2026 14:39:22 +0200 Subject: [PATCH] [man] Enhance sos-report.1 and sos-collect.1 by new options Similarly like in #4430 and #4440, man pages miss some command line options added as a feature, but forgotten to be mentioned in man pages. Further to that, mention --upload / --clean options there and refer to upload/clean component for their relevant options. Closes: #4441 Signed-off-by: Pavel Moravec --- man/en/sos-collect.1 | 116 +++++++++++++++++++++++++++++++++++++++++++ man/en/sos-report.1 | 31 ++++++++++++ 2 files changed, 147 insertions(+) diff --git a/man/en/sos-collect.1 b/man/en/sos-collect.1 index bb469961e9..97db430b77 100644 --- a/man/en/sos-collect.1 +++ b/man/en/sos-collect.1 @@ -7,17 +7,24 @@ sos_collect \- Collect sos reports from multiple (cluster) nodes [\-a|\-\-all\-options] [\-b|\-\-become] [\-\-batch] + [\-\-clean|\-\-cleaner|\-\-mask] + [\-\-cmd\-timeout TIMEOUT] [\-c CLUSTER_OPTIONS] [\-\-chroot CHROOT] [\-\-case\-id CASE_ID] [\-\-cluster\-type CLUSTER_TYPE] [\-\-container\-runtime RUNTIME] [\-e ENABLE_PLUGINS] + [\-i|\-\-ssh\-key SSH_KEY] + [\-\-inherit\-config\-file] [--encrypt-key KEY]\fR [--encrypt-pass PASS]\fR [\-\-group GROUP] [\-j|\-\-jobs JOBS] + [\-l|\-\-list\-options] + [\-\-namespaces NAMESPACES] [\-\-save\-group GROUP] + [\-\-no\-env\-vars] [\-\-nopasswd-sudo] [\-k PLUGIN_OPTION] [\-\-label LABEL] @@ -26,6 +33,8 @@ sos_collect \- Collect sos reports from multiple (cluster) nodes [\-\-nodes NODES] [\-\-no\-pkg\-check] [\-\-no\-local] + [\-\-node\-config\-file FILE] + [\-\-plugin\-timeout TIMEOUT] [\-\-primary PRIMARY] [\-\-image IMAGE] [\-\-force-pull-image TOGGLE, --pull TOGGLE] @@ -43,6 +52,7 @@ sos_collect \- Collect sos reports from multiple (cluster) nodes [\-\-ssh\-user SSH_USER] [\-\-sudo\-binary BINARY] [\-t|\-\-threads THREADS] + [\-\-upload] [\-\-timeout TIMEOUT] [\-\-transport TRANSPORT] [\-\-tmp\-dir TMP_DIR] @@ -76,6 +86,18 @@ Become the root user on the remote node when connecting as a non-root user. .TP \fB\-\-batch\fR Run in non-interactive mode. This will skip prompts for user input. +.TP +\fB\-\-clean\fR, \fB\-\-cleaner\fR, \fB\-\-mask\fR +Enable inline obfuscation/cleaning of the collected archives. + +When this option is used, the final collected archive (containing all node reports) +will be processed to obfuscate sensitive information such as hostnames, IP addresses, +MAC addresses, and user-specified keywords. + +Additional cleaning/masking options (such as \fB--domains\fR, \fB--keywords\fR, +\fB--map-file\fR, \fB--usernames\fR, etc.) control the cleaning behavior. For +documentation of all cleaning options, see \fBsos-clean(1)\fR. + .TP \fB\-\-all\-logs\fR Report option. Collects all logs regardless of size. @@ -90,6 +112,17 @@ a specific cluster you would use \fB'-c ovirt.cluster=example_cluster'\fR. Available cluster options can be listed by running \fB'sos collect -l'\fR. .TP +\fB\-\-cmd\-timeout\fR TIMEOUT +Report option. Specify a timeout limit in seconds for command execution on each node. + +This sets the command timeout for all plugins on the remote nodes. A value of 0 means +no timeout will be set. A value of -1 is used to indicate the default timeout of 300 seconds. + +This option sets the command timeout for all plugins. For plugin-specific command timeouts, +use the 'cmd-timeout' plugin option, e.g. '-k logs.cmd-timeout=600'. + +Note that setting a high cmd-timeout may require increasing --plugin-timeout as well. +.TP \fB\-\-chroot\fR CHROOT Report option. Set the chroot mode. When \fB\-\-sysroot\fR is used commands default to executing with SYSROOT as the root directory. This can be overridden by setting @@ -183,6 +216,27 @@ with the settings for cluster-type, primary, and the node list as discovered by Note that this means regexes are not directly saved to host groups, but the results of matching against those regexes are. .TP +\fB\-\-inherit\-config\-file\fR +Use the configuration file from the collector host for all nodes when running sos report. + +When this option is specified, sos collect will use its own sos.conf (or other +configuration file if specified via \fB--config-file\fR) and pass it to all nodes +to use when collecting their individual sos reports. This ensures consistent +configuration across all nodes in the cluster. + +This option is mutually exclusive with \fB--node-config-file\fR. +.TP +\fB\-i\fR SSH_KEY, \fB\-\-ssh\-key\fR SSH_KEY +Specify an SSH private key file to use for authentication when connecting to nodes. + +This is useful when SSH key-based authentication is configured but the key is not +in the default location (~/.ssh/id_rsa), or when you need to use a specific key +for cluster node authentication. + +The key file must be readable by the user running sos collect and must not be +password-protected (or the ssh-agent must have the key loaded) as sos collect +does not support interactive passphrase prompts for SSH keys. +.TP \fB\-j\fR JOBS \fB\-\-jobs\fR JOBS Specify the number of concurrent node collections that should be run. @@ -191,6 +245,19 @@ will start collecting from the first X number of nodes and then continue to iter through the remaining nodes as sos report collection finishes. Defaults to 4. +.TP +\fB\-l\fR, \fB\-\-list\-options\fR +Display available options for cluster profiles. + +This will show the cluster-specific options that can be used with the \fB-c\fR option +for the detected or specified cluster type. For example, cluster profiles may support +options to restrict node enumeration or modify collection behavior. + +Use with \fB--cluster-type\fR to see options for a specific cluster profile, otherwise +sos collect will attempt to auto-detect the cluster type. + +Example: \fBsos collect --cluster-type=kubernetes --list-options\fR + .TP \fB\-\-nopasswd-sudo\fR Use this option when connecting as a non-root user that has passwordless sudo @@ -224,6 +291,23 @@ collected will be collected in their entirety, which may drastically increase th size of the final sos report tarball and the memory usage of sos during collection of commands, such as very large journals that may be several GiB in size. .TP +\fB\-\-namespaces\fR NAMESPACES +Report option. For plugins that iterate collections over namespaces that exist on the system, +use this option to limit the number of namespaces that will be collected on each node. + +Use '0' (default) for no limit - all namespaces will be used for collections. + +Note that specific plugins may provide a similar 'namespaces' plugin option which will +override this option. +.TP +\fB\-\-no\-env\-vars\fR +Report option. Do not collect environment variables in the reports from nodes. + +By default, sos report collects environment variables from the system which may contain +sensitive information. Use this option to exclude environment variable collection on all +nodes for privacy or security reasons. Note that this may limit the usefulness of the +reports for debugging environment-related issues. +.TP \fB\-n\fR SKIP_PLUGINS, \fB\-\-skip\-plugins\fR SKIP_PLUGINS Report option. Disable (skip) a particular plugin that would otherwise run. This is useful if a particular plugin is prone to hanging for one reason or another. @@ -263,6 +347,17 @@ Specify an image to use for the temporary container created for collections on containerized host, if you do not want to use the default image specified by the host's policy. Note that this should include the registry. .TP +\fB\-\-node\-config\-file\fR FILE +Path to an existing configuration file on the nodes to use with sos report. + +When specified, sos collect will instruct each node to use the configuration file +at the given path (which must exist on each node) when running sos report. This +allows nodes to use a pre-deployed configuration file rather than their default +configuration or the collector's configuration. + +The path must be absolute and the file must exist on all nodes being collected from. +This option is mutually exclusive with \fB--inherit-config-file\fR. +.TP \fB\-\-force-pull-image TOGGLE, \-\-pull TOGGLE\fR When collecting an sos report from a containerized host, force the host to always pull the specified image, even if that image already exists on the host. @@ -317,6 +412,17 @@ are not used. If \fB\-\-preset\fR is specified and a given node either does not have that preset defined, or has a version of sos prior to 3.6, this option is ignored for that node. .TP +\fB\-\-plugin\-timeout\fR TIMEOUT +Report option. Specify a timeout in seconds to allow each plugin to run for on each node. + +A value of 0 means no timeout will be set. A value of -1 is used to indicate the default +timeout of 300 seconds. + +This option sets the timeout for all plugins. For plugin-specific timeouts, use the +'timeout' plugin option available to all plugins, e.g. '-k logs.timeout=600'. + +The plugin-specific timeout option will override this option. +.TP \fB\-p\fR SSH_PORT, \fB\-\-ssh\-port\fR SSH_PORT Specify SSH port for all nodes. Use this if SSH runs on any port other than 22. .TP @@ -331,6 +437,16 @@ will skip all commands with names that begin with the string "hostname". A comma delimited list of files or filepath wildcard matches to skip collection of. Values may either be exact filepaths or paths using UNIX shell-style wildcards, for example \fB/etc/sos/*\fR. +.TP +\fB\-\-upload\fR +Upload the collected archive to a vendor-defined or user-specified location after collection. + +Additional upload options (such as \fB--upload-url\fR, \fB--upload-user\fR, \fB--upload-s3-*\fR, +etc.) control the upload destination and authentication. For documentation of all upload +options, see \fBsos-upload(1)\fR or also \fBsos-report(1)\fR. + +Note: The upload applies to the final collected archive, not to individual node reports. + .TP \fB\-\-ssh\-user\fR SSH_USER Specify an SSH user for sos collect to connect to nodes with. Default is root. diff --git a/man/en/sos-report.1 b/man/en/sos-report.1 index efab2511bc..f4f88047d6 100644 --- a/man/en/sos-report.1 +++ b/man/en/sos-report.1 @@ -12,6 +12,7 @@ sos_report \- Collect and package diagnostic and support data [--no-report] [--config-file conf]\fR [--no-postproc]\fR [--preset preset] [--add-preset add_preset]\fR + [--note note]\fR [--del-preset del_preset] [--desc description]\fR [--batch] [--build] [--debug] [--dry-run]\fR [--estimate-only] [--label label] [--case-id id]\fR @@ -28,6 +29,7 @@ sos_report \- Collect and package diagnostic and support data [--verify]\fR [--log-size]\fR [--journal-size]\fR + [--no-env-vars]\fR [--all-logs]\fR [--since YYYYMMDD[HHMMSS]]\fR [--skip-commands commands]\fR @@ -36,6 +38,7 @@ sos_report \- Collect and package diagnostic and support data [--allow-system-changes]\fR [--low-priority]\fR [-z|--compression-type method]\fR + [--clean|--mask]\fR [--encrypt]\fR [--encrypt-key KEY]\fR [--encrypt-pass PASS]\fR @@ -152,6 +155,13 @@ Display a list of available presets and what options they carry. When using \fB--add-preset\fR use this option to add a description of the preset that will be displayed when using \fB--list-presets\fR. .TP +.B \--note NOTE +When using \fB--add-preset\fR, use this option to add a behaviour note to the preset +that will be displayed when using \fB--list-presets\fR. + +This is useful for documenting specific behaviours, caveats, or use-cases for the preset +beyond the basic description. +.TP .B \-s, \--sysroot SYSROOT Specify an alternate root file system path. Useful for collecting reports from containers and images. @@ -214,6 +224,14 @@ Tell plugins to collect all possible log data ignoring any size limits and including logs in non-default locations. This option may significantly increase the size of reports. .TP +.B \--no-env-vars +Do not collect environment variables in the report. + +By default, sos report collects environment variables from the system which may contain +sensitive information. Use this option to exclude environment variable collection for +privacy or security reasons. Note that this may limit the usefulness of the report for +debugging environment-related issues. +.TP .B \--since YYYYMMDD[HHMMSS] Limits the collection of log archives to those newer than this date. A log archive is any file not found in /etc, that has either a numeric or a @@ -251,6 +269,19 @@ Set sos to execute as a low priority process so that is does not interfere with other processes running on the system. Specific distributions may set their own constraints, but by default this involves setting process niceness to 19 and, if available, setting an idle IO class via ionice. +.TP +.B \--clean, \--cleaner, \--mask +Enable inline obfuscation/cleaning of the generated report. + +When this option is used, the report will be processed to obfuscate sensitive information +such as hostnames, IP addresses, MAC addresses, and user-specified keywords during generation, +rather than as a separate post-processing step. + +Additional cleaning/masking options (such as \fB--domains\fR, \fB--keywords\fR, +\fB--map-file\fR, \fB--usernames\fR, etc.) control the cleaning behavior. For +documentation of all cleaning options, see \fBsos-clean(1)\fR. + +.TP .B \-z, \--compression-type METHOD Override the default compression type specified by the active policy. .TP