{ "content": [ { "type": "text", "text": "# sos-collect(1) (man)\n\n**Summary:** soscollect - Collect sos reports from multiple (cluster) nodes\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -a | --alloptions | — | Enables all sos report options. This does NOT enable all sos collect options. |\n| -b | --become | — | Become the root user on the remote node when connecting as a non-root user. |\n| — | --batch | — | Run in non-interactive mode. This will skip prompts for user input. |\n| — | --all-logs | — | Report option. Collects all logs regardless of size. Default: no |\n| -c | — | — | Specify options used by cluster profiles. The format is 'profile.optionname=value'. For example, for the ovirt plugin if |\n| -e | --enable-plugins | — | Report option. Use this to enable a plugin that would otherwise not be run. This option supports providing a comma-delim |\n| — | --encrypt-key | KEY | Encrypts the resulting archive that sos collect produces using GPG. KEY must be an ex‐ isting key in the user's keyring |\n| — | --encrypt-pass | PASS | The same as --encrypt-key, but use the provided PASS for symmetric encryption rather than key-pair encryption. --group G |\n| -j | --jobs | — | Specify the number of concurrent node collections that should be run. If the number of nodes enumerated exceeds the numb |\n| — | --nopasswd-sudo | — | Use this option when connecting as a non-root user that has passwordless sudo config‐ ured. If this option is omitted an |\n| -k | --plugin-option | — | Report option. Set a plugin option to a particular value. This takes the form of pluginname.optionname=value. Example: T |\n| -n | --skip-plugins | — | Report option. Disable (skip) a particular plugin that would otherwise run. This is useful if a particular plugin is pro |\n| — | --no-pkg-check | — | Do not perform package checks. Most cluster profiles check against installed packages to determine if the cluster profil |\n| — | --no-local | — | Do not collect a sos report from the local system. If --primary is not supplied, it is assumed that the host running sos |\n| — | --image | IMAGE | Specify an image to use for the temporary container created for collections on con‐ tainerized host, if you do not want |\n| — | --pull | TOGGLE | When collecting an sos report from a containerized host, force the host to always pull the specified image, even if that |\n| — | --registry-user | USER | Specify the username to authenticate to the registry with in order to pull the con‐ tainer image |\n| — | --registry-password | PASSWORD | Specify the password to authenticate to the registry with in order to pull the con‐ tainer image. If no password is requ |\n| — | --registry-authfile | FILE | Specify the filename to use for providing authentication credentials to the registry to pull the container image. Note t |\n| -o | --only-plugins | — | Report option. Run ONLY the plugins listed. Note that a cluster profile will NOT override this option. This may cause th |\n| — | --password | — | Specifying this option will cause sos collect to prompt the user for an SSH password that will be used to connect to all |\n| — | --password-per-node | — | When using this option, sos collect will prompt the user for the SSH password for each node that will have an sos report |\n| -p | --ssh-port | — | Specify SSH port for all nodes. Use this if SSH runs on any port other than 22. --skip-commands COMMANDS A comma delimit |\n| -s | --sysroot | — | Report option. Specify an alternate root file system path. |\n| -t | --threads | — | Report option. Specify the number of collection threads to run. The report process on each node will run THREADS number |\n| -v | --verbose | — | Print debug information to screen. |\n| — | --verify | — | Report option. Passes the \"--verify\" option to sos report on the nodes which causes sos report to validate plugin-specif |\n| -z | --compression-type | — | Report option. Override the default compression type. |\n\n## See Also\n\n- sos(1)\n- sos-report(1)\n- sos-clean(1)\n- sos.conf(5)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (1 lines) — 1 subsections\n - sos collect (46 lines)\n- **DESCRIPTION** (13 lines)\n- **OPTIONS** (1 lines) — 28 subsections\n - -a --alloptions (4 lines)\n - -b --become (2 lines)\n - --batch (2 lines)\n - --all-logs (4 lines)\n - -c (36 lines)\n - -e --enable-plugins (4 lines)\n - --encrypt-key KEY (26 lines)\n - --encrypt-pass PASS (30 lines)\n - -j --jobs (8 lines)\n - --nopasswd-sudo (6 lines)\n - -k --plugin-option (24 lines)\n - -n --skip-plugins (14 lines)\n - --no-pkg-check (5 lines)\n - --no-local (14 lines)\n - --image IMAGE (4 lines)\n - --force-pull-image TOGGLE, --pull TOGGLE (10 lines)\n - --registry-user USER (3 lines)\n - --registry-password PASSWORD (3 lines)\n - --registry-authfile FILE (6 lines)\n - -o --only-plugins (7 lines)\n - --password (6 lines)\n - --password-per-node (12 lines)\n - -p --ssh-port (19 lines)\n - -s --sysroot (2 lines)\n - -t --threads (39 lines)\n - -v --verbose (2 lines)\n - --verify (6 lines)\n - -z --compression-type (3 lines)\n- **SEE ALSO** (3 lines)\n- **MAINTAINER** (2 lines) — 1 subsections\n - AUTHORS & CONTRIBUTORS (5 lines)\n\n## Full Content\n\n### NAME\n\nsoscollect - Collect sos reports from multiple (cluster) nodes\n\n### SYNOPSIS\n\n#### sos collect\n\n[-a|--all-options]\n[-b|--become]\n[--batch]\n[-c CLUSTEROPTIONS]\n[--chroot CHROOT]\n[--case-id CASEID]\n[--cluster-type CLUSTERTYPE]\n[--container-runtime RUNTIME]\n[-e ENABLEPLUGINS]\n[--encrypt-key KEY]\n[--encrypt-pass PASS]\n[--group GROUP]\n[-j|--jobs JOBS]\n[--save-group GROUP]\n[--nopasswd-sudo]\n[-k PLUGINOPTION]\n[--label LABEL]\n[--log-size SIZE]\n[-n SKIPPLUGINS]\n[--nodes NODES]\n[--no-pkg-check]\n[--no-local]\n[--primary PRIMARY]\n[--image IMAGE]\n[--force-pull-image TOGGLE, --pull TOGGLE]\n[--registry-user USER]\n[--registry-password PASSWORD]\n[--registry-authfile FILE]\n[-o ONLYPLUGINS]\n[-p SSHPORT]\n[--password]\n[--password-per-node]\n[--preset PRESET]\n[--skip-commands COMMANDS]\n[--skip-files FILES]\n[-s|--sysroot SYSROOT]\n[--ssh-user SSHUSER]\n[-t|--threads THREADS]\n[--timeout TIMEOUT]\n[--transport TRANSPORT]\n[--tmp-dir TMPDIR]\n[-v|--verbose]\n[--verify]\n[-z|--compression-type COMPRESSIONTYPE]\n\n### DESCRIPTION\n\ncollect is an sos subcommand to collect sos reports from multiple nodes and package them in a\nsingle useful tar archive.\n\nsos collect can be run either on a workstation that has SSH key authentication setup for the\nnodes in a given cluster, or from a \"primary\" node in a cluster that has SSH keys configured\nfor the other nodes.\n\nSome sos report options are supported by sos-collect and are passed directly to the sos re‐\nport command run on each node.\n\nNote: the sos-collector command has been deprecated and will be removed in sos-4.9. Use the\nnew sos collect syntax instead.\n\n### OPTIONS\n\n#### -a --alloptions\n\nEnables all sos report options.\n\nThis does NOT enable all sos collect options.\n\n#### -b --become\n\nBecome the root user on the remote node when connecting as a non-root user.\n\n#### --batch\n\nRun in non-interactive mode. This will skip prompts for user input.\n\n#### --all-logs\n\nReport option. Collects all logs regardless of size.\n\nDefault: no\n\n#### -c\n\nSpecify options used by cluster profiles. The format is 'profile.optionname=value'.\n\nFor example, for the ovirt plugin if you wanted to restrict node enumeration to a spe‐\ncific cluster you would use '-c ovirt.cluster=examplecluster'.\n\nAvailable cluster options can be listed by running 'sos collect -l'.\n\n--chroot CHROOT\nReport option. Set the chroot mode. When --sysroot is used commands default to execut‐\ning with SYSROOT as the root directory. This can be overridden by setting --chroot to\n\"always\" (always chroot) or \"never\" (always run in the host namespace).\n\n--case-id CASEID\nReport option. Specifies a case number identifier.\n\n--cluster-type CLUSTERTYPE\nWhen run by itself, sos collect will attempt to identify the type of cluster at play.\nThis is done by checking package or configuration information against the localhost,\nor the primary node if \"--primary\" is supplied.\n\nSetting --cluster-type skips this step and forcibly sets a particular profile.\n\nUsing a value of none or jbon (just a bunch of nodes) will effectively disable all\ncluster-specific checks, and cause sos collect to only use the nodes specified by the\n--nodes option. Note that in this scenario, regex string(s) for node names will be ig‐\nnored.\n\nExample: sos collect --cluster-type=kubernetes will force the kubernetes profile to be\nrun, and thus set sos report options and attempt to determine a list of nodes using\nthat profile.\n\n--container-runtime RUNTIME\nsos report option. Using this with collect will pass this option thru to nodes with\nsos version 4.3 or later. This option controls the default container runtime plugins\nwill use for collections. See man sos-report.\n\n#### -e --enable-plugins\n\nReport option. Use this to enable a plugin that would otherwise not be run.\n\nThis option supports providing a comma-delimited list of plugins.\n\n#### --encrypt-key KEY\n\nEncrypts the resulting archive that sos collect produces using GPG. KEY must be an ex‐\nisting key in the user's keyring as GPG does not allow for keyfiles. KEY can be any\nvalue accepted by gpg's 'recipient' option.\n\nNote that the user running sos collect must match the user owning the keyring from\nwhich keys will be obtained. In particular this means that if sudo is used to run sos\ncollect, the keyring must also be set up using sudo (or direct shell access to the ac‐\ncount).\n\nUsers should be aware that encrypting the final archive will result in sos using dou‐\nble the amount of temporary disk space - the encrypted archive must be written as a\nseparate, rather than replacement, file within the temp directory that sos writes the\narchive to. However, since the encrypted archive will be the same size as the original\narchive, there is no additional space consumption once the temporary directory is re‐\nmoved at the end of execution.\n\nThis means that only the encrypted archive is present on disk after sos finishes run‐\nning.\n\nIf encryption fails for any reason, the original unencrypted archive is preserved in‐\nstead.\n\nIMPORTANT: As of this version of sos collect, only the final archive on the local ma‐\nchine running sos collect will be encrypted. The individual sos reports that are col‐\nlected on the nodes will be collected unencrypted.\n\n#### --encrypt-pass PASS\n\nThe same as --encrypt-key, but use the provided PASS for symmetric encryption rather\nthan key-pair encryption.\n\n\n--group GROUP\nSpecify an existing host group definition to use.\n\nHost groups are pre-defined settings for the cluster-type, primary node, and nodes op‐\ntions saved in JSON-formatted files under /etc/sos/groups.d/.\n\nIf clustertype and/or primary are set in the group, sos collect behaves as if these\nvalues were specified on the command-line.\n\nIf nodes is defined, sos collect extends the --nodes option, if set, with the nodes or\nregexes listed in the group.\n\nNote that sos collect will only write group definitions to /etc/sos/groups.d/ however\nthe GROUP value may be a filename for any group definitions that exist outside of the\ndefault location. If you are manually writing these files, use the value null when a\npython NoneType is expected. Caveat: use string 'none' if setting clustertype to\nnone.\n\n--save-group GROUP\nSave the results of this run of sos collect to a host group definition.\n\nsos-collector will write a JSON-formatted file with name GROUP to /etc/sos/groups.d/\nwith the settings for cluster-type, primary, and the node list as discovered by clus‐\nter enumeration. Note that this means regexes are not directly saved to host groups,\nbut the results of matching against those regexes are.\n\n#### -j --jobs\n\nSpecify the number of concurrent node collections that should be run.\n\nIf the number of nodes enumerated exceeds the number of JOBS, then sos collect will\nstart collecting from the first X number of nodes and then continue to iterate through\nthe remaining nodes as sos report collection finishes.\n\nDefaults to 4.\n\n#### --nopasswd-sudo\n\nUse this option when connecting as a non-root user that has passwordless sudo config‐\nured.\n\nIf this option is omitted and a bogus sudo password is supplied, collection of sos re‐\nports may exhibit unexpected behavior and/or fail entirely.\n\n#### -k --plugin-option\n\nReport option. Set a plugin option to a particular value. This takes the form of\npluginname.optionname=value.\n\nExample: To enable the kubernetes \"all\" option in sos report use -k kubernetes.all=on.\n\n--label LABEL\nSpecify a label to be added to the archive names. This label will be applied to both\nthe sos collect archive and the sos report archives.\n\nIf a cluster sets a default label, the user-provided label will be appended to that\ncluster default.\n\n--log-size SIZE\nPlaces a limit on the size of collected logs and output in MiB. Note that this causes\nsos to capture the last X amount of the file or command output collected.\n\nBy default, this is set to 25 MiB and applies to all files and command output col‐\nlected with the exception of journal collections, which are limited to 100 MiB.\n\nSetting this value to 0 removes all size limitations, and any files or commands col‐\nlected will be collected in their entirety, which may drastically increase the size of\nthe final sos report tarball and the memory usage of sos during collection of com‐\nmands, such as very large journals that may be several GiB in size.\n\n#### -n --skip-plugins\n\nReport option. Disable (skip) a particular plugin that would otherwise run. This is\nuseful if a particular plugin is prone to hanging for one reason or another.\n\nThis option supports providing a comma-delimited list of plugins.\n\n--nodes NODES\nProvide a comma-delimited list of nodes to collect sos reports from, or a regex string\nto be used to compare discovered node names against. If using a regex, only nodes\nmatching the regex will be used - i.e. it can be used as a whitelist but not a black‐\nlist.\n\nThis option can be handed multiple regex strings separated by commas. Additionally,\nboth whole node names/addresses and regex strings may be provided at the same time.\n\n#### --no-pkg-check\n\nDo not perform package checks. Most cluster profiles check against installed packages\nto determine if the cluster profile should be applied or not.\n\nUse this with --cluster-type if there are rpm or apt issues on the primary/local node.\n\n#### --no-local\n\nDo not collect a sos report from the local system.\n\nIf --primary is not supplied, it is assumed that the host running sos report is part\nof the cluster that is to be collected. Use this option to skip collection of a local\nsos report.\n\nThis option is NOT needed if --primary is provided.\n\n--primary PRIMARY\nSpecify a primary node IP address or hostname for the cluster.\n\nIf provided, then sos collect will check the primary node, not localhost, for deter‐\nmining the type of cluster in use.\n\n#### --image IMAGE\n\nSpecify an image to use for the temporary container created for collections on con‐\ntainerized host, if you do not want to use the default image specified by the host's\npolicy. Note that this should include the registry.\n\n#### --force-pull-image TOGGLE, --pull TOGGLE\n\nWhen collecting an sos report from a containerized host, force the host to always pull\nthe specified image, even if that image already exists on the host. This is useful to\nensure that the latest version of that image is always in use. Disabling this option\nwill use whatever version of the image is present on the node, and only attempt a pull\nif there is no copy of the image present at all.\n\nEnable with true/on/yes or disable with false/off/no\n\nDefault: true\n\n#### --registry-user USER\n\nSpecify the username to authenticate to the registry with in order to pull the con‐\ntainer image\n\n#### --registry-password PASSWORD\n\nSpecify the password to authenticate to the registry with in order to pull the con‐\ntainer image. If no password is required, leave this blank.\n\n#### --registry-authfile FILE\n\nSpecify the filename to use for providing authentication credentials to the registry\nto pull the container image.\n\nNote that this file must exist on the node(s) performing the pull operations, not the\nnode from which sos collect was run.\n\n#### -o --only-plugins\n\nReport option. Run ONLY the plugins listed.\n\nNote that a cluster profile will NOT override this option. This may cause the sos re‐\nports generated to not contain the relevant output for a given type of cluster.\n\nThis option supports providing a comma-delimited list of plugins.\n\n#### --password\n\nSpecifying this option will cause sos collect to prompt the user for an SSH password\nthat will be used to connect to all nodes.\n\nIf you have differing passwords for the same user across cluster nodes, you should\nideally deploy SSH keys, but the --password-per-node option is also available.\n\n#### --password-per-node\n\nWhen using this option, sos collect will prompt the user for the SSH password for each\nnode that will have an sos report collected from it individually before attempting to\nconnect to the nodes.\n\n--preset PRESET\nSpecify a sos preset to use, note that this requires sos-3.6 or later to be installed\non the node. The given preset must also exist on the remote node - local presets are\nnot used.\n\nIf --preset is specified and a given node either does not have that preset defined, or\nhas a version of sos prior to 3.6, this option is ignored for that node.\n\n#### -p --ssh-port\n\nSpecify SSH port for all nodes. Use this if SSH runs on any port other than 22.\n\n--skip-commands COMMANDS\nA comma delimited list of commands to skip execution of, but still allowing the rest\nof the plugin that calls the command to run. This will generally need to be some form\nof UNIX shell-style wildcard matching. For example, using a value of hostname will\nskip only that single command, while using hostname* will skip all commands with names\nthat begin with the string \"hostname\".\n\n--skip-files FILES\nA comma delimited list of files or filepath wildcard matches to skip collection of.\nValues may either be exact filepaths or paths using UNIX shell-style wildcards, for\nexample /etc/sos/*.\n\n--ssh-user SSHUSER\nSpecify an SSH user for sos collect to connect to nodes with. Default is root.\n\nsos collect will prompt for a sudo password for non-root users.\n\n#### -s --sysroot\n\nReport option. Specify an alternate root file system path.\n\n#### -t --threads\n\nReport option. Specify the number of collection threads to run.\n\nThe report process on each node will run THREADS number of plugins concurrently during\nthe collection process.\n\nDefaults to 4.\n\n--timeout TIMEOUT\nTimeout for sos report generation on each node, in seconds.\n\nNote that sos reports are collected in parallel, so you can approximate the total run‐\ntime of sos collect via timeout*(number of nodes/jobs).\n\nDefault is 180 seconds.\n\n--transport TRANSPORT\nSpecify the type of remote transport to use to manage connections to remote nodes.\n\nsos collect uses locally installed binaries to connect to and interact with remote\nnodes, instead of directly establishing those connections. By default, OpenSSH's Con‐\ntrolPersist feature is preferred, however certain cluster types may have preferences\nof their own for how remote sessions should be established.\n\nThe types of transports supported are currently as follows:\n\nauto Allow the cluster type to determine the transport used\ncontrolpersist Use OpenSSH's ControlPersist feature. This is the default\nbehavior\noc Use a locally configured oc binary to deploy collection pods\non OCP nodes\n\n\n--tmp-dir TMPDIR\nSpecify a temporary directory to save sos archives to. By default one will be created\nin /tmp and then removed after sos collect has finished running.\n\nThis is NOT the same as specifying a temporary directory for sos report on the remote\nnodes.\n\n#### -v --verbose\n\nPrint debug information to screen.\n\n#### --verify\n\nReport option. Passes the \"--verify\" option to sos report on the nodes which causes\nsos report to validate plugin-specific data during collection.\n\nNote that this option may considerably extend the time it takes sos report to run on\nthe nodes. Consider increasing --timeout when using this option.\n\n#### -z --compression-type\n\nReport option. Override the default compression type.\n\n### SEE ALSO\n\nsos(1) sos-report(1) sos-clean(1) sos.conf(5)\n\n### MAINTAINER\n\nMaintained on GitHub at https://github.com/sosreport/sos\n\n#### AUTHORS & CONTRIBUTORS\n\nSee AUTHORS file in the package documentation.\n\n\n\nApril 2020 SOSCOLLECT(1)\n\n" } ], "structuredContent": { "command": "sos-collect", "section": "1", "mode": "man", "summary": "soscollect - Collect sos reports from multiple (cluster) nodes", "synopsis": "", "flags": [ { "flag": "-a", "long": "--alloptions", "arg": null, "description": "Enables all sos report options. This does NOT enable all sos collect options." }, { "flag": "-b", "long": "--become", "arg": null, "description": "Become the root user on the remote node when connecting as a non-root user." }, { "flag": "", "long": "--batch", "arg": null, "description": "Run in non-interactive mode. This will skip prompts for user input." }, { "flag": "", "long": "--all-logs", "arg": null, "description": "Report option. Collects all logs regardless of size. Default: no" }, { "flag": "-c", "long": null, "arg": null, "description": "Specify options used by cluster profiles. The format is 'profile.optionname=value'. For example, for the ovirt plugin if you wanted to restrict node enumeration to a spe‐ cific cluster you would use '-c ovirt.cluster=examplecluster'. Available cluster options can be listed by running 'sos collect -l'. --chroot CHROOT Report option. Set the chroot mode. When --sysroot is used commands default to execut‐ ing with SYSROOT as the root directory. This can be overridden by setting --chroot to \"always\" (always chroot) or \"never\" (always run in the host namespace). --case-id CASEID Report option. Specifies a case number identifier. --cluster-type CLUSTERTYPE When run by itself, sos collect will attempt to identify the type of cluster at play. This is done by checking package or configuration information against the localhost, or the primary node if \"--primary\" is supplied. Setting --cluster-type skips this step and forcibly sets a particular profile. Using a value of none or jbon (just a bunch of nodes) will effectively disable all cluster-specific checks, and cause sos collect to only use the nodes specified by the --nodes option. Note that in this scenario, regex string(s) for node names will be ig‐ nored. Example: sos collect --cluster-type=kubernetes will force the kubernetes profile to be run, and thus set sos report options and attempt to determine a list of nodes using that profile. --container-runtime RUNTIME sos report option. Using this with collect will pass this option thru to nodes with sos version 4.3 or later. This option controls the default container runtime plugins will use for collections. See man sos-report." }, { "flag": "-e", "long": "--enable-plugins", "arg": null, "description": "Report option. Use this to enable a plugin that would otherwise not be run. This option supports providing a comma-delimited list of plugins." }, { "flag": "", "long": "--encrypt-key", "arg": "KEY", "description": "Encrypts the resulting archive that sos collect produces using GPG. KEY must be an ex‐ isting key in the user's keyring as GPG does not allow for keyfiles. KEY can be any value accepted by gpg's 'recipient' option. Note that the user running sos collect must match the user owning the keyring from which keys will be obtained. In particular this means that if sudo is used to run sos collect, the keyring must also be set up using sudo (or direct shell access to the ac‐ count). Users should be aware that encrypting the final archive will result in sos using dou‐ ble the amount of temporary disk space - the encrypted archive must be written as a separate, rather than replacement, file within the temp directory that sos writes the archive to. However, since the encrypted archive will be the same size as the original archive, there is no additional space consumption once the temporary directory is re‐ moved at the end of execution. This means that only the encrypted archive is present on disk after sos finishes run‐ ning. If encryption fails for any reason, the original unencrypted archive is preserved in‐ stead. IMPORTANT: As of this version of sos collect, only the final archive on the local ma‐ chine running sos collect will be encrypted. The individual sos reports that are col‐ lected on the nodes will be collected unencrypted." }, { "flag": "", "long": "--encrypt-pass", "arg": "PASS", "description": "The same as --encrypt-key, but use the provided PASS for symmetric encryption rather than key-pair encryption. --group GROUP Specify an existing host group definition to use. Host groups are pre-defined settings for the cluster-type, primary node, and nodes op‐ tions saved in JSON-formatted files under /etc/sos/groups.d/. If clustertype and/or primary are set in the group, sos collect behaves as if these values were specified on the command-line. If nodes is defined, sos collect extends the --nodes option, if set, with the nodes or regexes listed in the group. Note that sos collect will only write group definitions to /etc/sos/groups.d/ however the GROUP value may be a filename for any group definitions that exist outside of the default location. If you are manually writing these files, use the value null when a python NoneType is expected. Caveat: use string 'none' if setting clustertype to none. --save-group GROUP Save the results of this run of sos collect to a host group definition. sos-collector will write a JSON-formatted file with name GROUP to /etc/sos/groups.d/ with the settings for cluster-type, primary, and the node list as discovered by clus‐ ter enumeration. Note that this means regexes are not directly saved to host groups, but the results of matching against those regexes are." }, { "flag": "-j", "long": "--jobs", "arg": null, "description": "Specify the number of concurrent node collections that should be run. If the number of nodes enumerated exceeds the number of JOBS, then sos collect will start collecting from the first X number of nodes and then continue to iterate through the remaining nodes as sos report collection finishes. Defaults to 4." }, { "flag": "", "long": "--nopasswd-sudo", "arg": null, "description": "Use this option when connecting as a non-root user that has passwordless sudo config‐ ured. If this option is omitted and a bogus sudo password is supplied, collection of sos re‐ ports may exhibit unexpected behavior and/or fail entirely." }, { "flag": "-k", "long": "--plugin-option", "arg": null, "description": "Report option. Set a plugin option to a particular value. This takes the form of pluginname.optionname=value. Example: To enable the kubernetes \"all\" option in sos report use -k kubernetes.all=on. --label LABEL Specify a label to be added to the archive names. This label will be applied to both the sos collect archive and the sos report archives. If a cluster sets a default label, the user-provided label will be appended to that cluster default. --log-size SIZE Places a limit on the size of collected logs and output in MiB. Note that this causes sos to capture the last X amount of the file or command output collected. By default, this is set to 25 MiB and applies to all files and command output col‐ lected with the exception of journal collections, which are limited to 100 MiB. Setting this value to 0 removes all size limitations, and any files or commands col‐ lected will be collected in their entirety, which may drastically increase the size of the final sos report tarball and the memory usage of sos during collection of com‐ mands, such as very large journals that may be several GiB in size." }, { "flag": "-n", "long": "--skip-plugins", "arg": null, "description": "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. This option supports providing a comma-delimited list of plugins. --nodes NODES Provide a comma-delimited list of nodes to collect sos reports from, or a regex string to be used to compare discovered node names against. If using a regex, only nodes matching the regex will be used - i.e. it can be used as a whitelist but not a black‐ list. This option can be handed multiple regex strings separated by commas. Additionally, both whole node names/addresses and regex strings may be provided at the same time." }, { "flag": "", "long": "--no-pkg-check", "arg": null, "description": "Do not perform package checks. Most cluster profiles check against installed packages to determine if the cluster profile should be applied or not. Use this with --cluster-type if there are rpm or apt issues on the primary/local node." }, { "flag": "", "long": "--no-local", "arg": null, "description": "Do not collect a sos report from the local system. If --primary is not supplied, it is assumed that the host running sos report is part of the cluster that is to be collected. Use this option to skip collection of a local sos report. This option is NOT needed if --primary is provided. --primary PRIMARY Specify a primary node IP address or hostname for the cluster. If provided, then sos collect will check the primary node, not localhost, for deter‐ mining the type of cluster in use." }, { "flag": "", "long": "--image", "arg": "IMAGE", "description": "Specify an image to use for the temporary container created for collections on con‐ tainerized host, if you do not want to use the default image specified by the host's policy. Note that this should include the registry." }, { "flag": "", "long": "--pull", "arg": "TOGGLE", "description": "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. This is useful to ensure that the latest version of that image is always in use. Disabling this option will use whatever version of the image is present on the node, and only attempt a pull if there is no copy of the image present at all. Enable with true/on/yes or disable with false/off/no Default: true" }, { "flag": "", "long": "--registry-user", "arg": "USER", "description": "Specify the username to authenticate to the registry with in order to pull the con‐ tainer image" }, { "flag": "", "long": "--registry-password", "arg": "PASSWORD", "description": "Specify the password to authenticate to the registry with in order to pull the con‐ tainer image. If no password is required, leave this blank." }, { "flag": "", "long": "--registry-authfile", "arg": "FILE", "description": "Specify the filename to use for providing authentication credentials to the registry to pull the container image. Note that this file must exist on the node(s) performing the pull operations, not the node from which sos collect was run." }, { "flag": "-o", "long": "--only-plugins", "arg": null, "description": "Report option. Run ONLY the plugins listed. Note that a cluster profile will NOT override this option. This may cause the sos re‐ ports generated to not contain the relevant output for a given type of cluster. This option supports providing a comma-delimited list of plugins." }, { "flag": "", "long": "--password", "arg": null, "description": "Specifying this option will cause sos collect to prompt the user for an SSH password that will be used to connect to all nodes. If you have differing passwords for the same user across cluster nodes, you should ideally deploy SSH keys, but the --password-per-node option is also available." }, { "flag": "", "long": "--password-per-node", "arg": null, "description": "When using this option, sos collect will prompt the user for the SSH password for each node that will have an sos report collected from it individually before attempting to connect to the nodes. --preset PRESET Specify a sos preset to use, note that this requires sos-3.6 or later to be installed on the node. The given preset must also exist on the remote node - local presets are not used. If --preset 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." }, { "flag": "-p", "long": "--ssh-port", "arg": null, "description": "Specify SSH port for all nodes. Use this if SSH runs on any port other than 22. --skip-commands COMMANDS A comma delimited list of commands to skip execution of, but still allowing the rest of the plugin that calls the command to run. This will generally need to be some form of UNIX shell-style wildcard matching. For example, using a value of hostname will skip only that single command, while using hostname* will skip all commands with names that begin with the string \"hostname\". --skip-files FILES 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 /etc/sos/*. --ssh-user SSHUSER Specify an SSH user for sos collect to connect to nodes with. Default is root. sos collect will prompt for a sudo password for non-root users." }, { "flag": "-s", "long": "--sysroot", "arg": null, "description": "Report option. Specify an alternate root file system path." }, { "flag": "-t", "long": "--threads", "arg": null, "description": "Report option. Specify the number of collection threads to run. The report process on each node will run THREADS number of plugins concurrently during the collection process. Defaults to 4. --timeout TIMEOUT Timeout for sos report generation on each node, in seconds. Note that sos reports are collected in parallel, so you can approximate the total run‐ time of sos collect via timeout*(number of nodes/jobs). Default is 180 seconds. --transport TRANSPORT Specify the type of remote transport to use to manage connections to remote nodes. sos collect uses locally installed binaries to connect to and interact with remote nodes, instead of directly establishing those connections. By default, OpenSSH's Con‐ trolPersist feature is preferred, however certain cluster types may have preferences of their own for how remote sessions should be established. The types of transports supported are currently as follows: auto Allow the cluster type to determine the transport used controlpersist Use OpenSSH's ControlPersist feature. This is the default behavior oc Use a locally configured oc binary to deploy collection pods on OCP nodes --tmp-dir TMPDIR Specify a temporary directory to save sos archives to. By default one will be created in /tmp and then removed after sos collect has finished running. This is NOT the same as specifying a temporary directory for sos report on the remote nodes." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "Print debug information to screen." }, { "flag": "", "long": "--verify", "arg": null, "description": "Report option. Passes the \"--verify\" option to sos report on the nodes which causes sos report to validate plugin-specific data during collection. Note that this option may considerably extend the time it takes sos report to run on the nodes. Consider increasing --timeout when using this option." }, { "flag": "-z", "long": "--compression-type", "arg": null, "description": "Report option. Override the default compression type." } ], "examples": [], "see_also": [ { "name": "sos", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/sos/1/json" }, { "name": "sos-report", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/sos-report/1/json" }, { "name": "sos-clean", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/sos-clean/1/json" }, { "name": "sos.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/sos.conf/5/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "sos collect", "lines": 46 } ] }, { "name": "DESCRIPTION", "lines": 13, "subsections": [] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "-a --alloptions", "lines": 4, "flag": "-a", "long": "--alloptions" }, { "name": "-b --become", "lines": 2, "flag": "-b", "long": "--become" }, { "name": "--batch", "lines": 2, "long": "--batch" }, { "name": "--all-logs", "lines": 4, "long": "--all-logs" }, { "name": "-c", "lines": 36, "flag": "-c" }, { "name": "-e --enable-plugins", "lines": 4, "flag": "-e", "long": "--enable-plugins" }, { "name": "--encrypt-key KEY", "lines": 26, "long": "--encrypt-key", "arg": "KEY" }, { "name": "--encrypt-pass PASS", "lines": 30, "long": "--encrypt-pass", "arg": "PASS" }, { "name": "-j --jobs", "lines": 8, "flag": "-j", "long": "--jobs" }, { "name": "--nopasswd-sudo", "lines": 6, "long": "--nopasswd-sudo" }, { "name": "-k --plugin-option", "lines": 24, "flag": "-k", "long": "--plugin-option" }, { "name": "-n --skip-plugins", "lines": 14, "flag": "-n", "long": "--skip-plugins" }, { "name": "--no-pkg-check", "lines": 5, "long": "--no-pkg-check" }, { "name": "--no-local", "lines": 14, "long": "--no-local" }, { "name": "--image IMAGE", "lines": 4, "long": "--image", "arg": "IMAGE" }, { "name": "--force-pull-image TOGGLE, --pull TOGGLE", "lines": 10, "long": "--pull", "arg": "TOGGLE" }, { "name": "--registry-user USER", "lines": 3, "long": "--registry-user", "arg": "USER" }, { "name": "--registry-password PASSWORD", "lines": 3, "long": "--registry-password", "arg": "PASSWORD" }, { "name": "--registry-authfile FILE", "lines": 6, "long": "--registry-authfile", "arg": "FILE" }, { "name": "-o --only-plugins", "lines": 7, "flag": "-o", "long": "--only-plugins" }, { "name": "--password", "lines": 6, "long": "--password" }, { "name": "--password-per-node", "lines": 12, "long": "--password-per-node" }, { "name": "-p --ssh-port", "lines": 19, "flag": "-p", "long": "--ssh-port" }, { "name": "-s --sysroot", "lines": 2, "flag": "-s", "long": "--sysroot" }, { "name": "-t --threads", "lines": 39, "flag": "-t", "long": "--threads" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "--verify", "lines": 6, "long": "--verify" }, { "name": "-z --compression-type", "lines": 3, "flag": "-z", "long": "--compression-type" } ] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "MAINTAINER", "lines": 2, "subsections": [ { "name": "AUTHORS & CONTRIBUTORS", "lines": 5 } ] } ] } }