1SOS(COLLECT) SOS(COLLECT)
2
6 sos collect - Collect sosreports from multiple (cluster) nodes
7
9 sos collect
10 [-a|--all-options]
11 [-b|--become]
12 [--batch]
13 [-c CLUSTER_OPTIONS]
14 [--chroot CHROOT]
15 [--case-id CASE_ID]
16 [--cluster-type CLUSTER_TYPE]
17 [--container-runtime RUNTIME]
18 [-e ENABLE_PLUGINS]
19 [--encrypt-key KEY]
20 [--encrypt-pass PASS]
21 [--group GROUP]
22 [-j|--jobs JOBS]
23 [--save-group GROUP]
24 [--nopasswd-sudo]
25 [-k PLUGIN_OPTION]
26 [--label LABEL]
27 [--log-size SIZE]
28 [-n SKIP_PLUGINS]
29 [--nodes NODES]
30 [--no-pkg-check]
31 [--no-local]
32 [--primary PRIMARY]
33 [--image IMAGE]
34 [--force-pull-image TOGGLE, --pull TOGGLE]
35 [--registry-user USER]
36 [--registry-password PASSWORD]
37 [--registry-authfile FILE]
38 [-o ONLY_PLUGINS]
39 [-p SSH_PORT]
40 [--password]
41 [--password-per-node]
42 [--preset PRESET]
43 [--skip-commands COMMANDS]
44 [--skip-files FILES]
45 [-s|--sysroot SYSROOT]
46 [--ssh-user SSH_USER]
47 [--sos-cmd SOS_CMD]
48 [-t|--threads THREADS]
49 [--timeout TIMEOUT]
50 [--transport TRANSPORT]
51 [--tmp-dir TMP_DIR]
52 [-v|--verbose]
53 [--verify]
54 [-z|--compression-type COMPRESSION_TYPE]
55
58 collect is an sos subcommand to collect sosreports from multiple nodes
59 and package them in a single useful tar archive.
60 sos collect can be run either on a workstation that has SSH key authen‐
62 tication setup for the nodes in a given cluster, or from a "primary"
63 node in a cluster that has SSH keys configured for the other nodes.
64 Some sosreport options are supported by sos-collect and are passed di‐
66 rectly to the sosreport command run on each node.
67
70 -a, --alloptions
71 Enables all sosreport options.
72 This does NOT enable all sos collect options.
74 -b, --become
76 Become the root user on the remote node when connecting as a
77 non-root user.
78 --batch
80 Run in non-interactive mode. This will skip prompts for user in‐
81 put, with the exception of a prompt for the SSH password.
82 --all-logs
84 Sosreport option. Collects all logs regardless of size.
85 Default: no
87 -c CLUSTER_OPTIONS
89 Specify options used by cluster profiles. The format is 'pro‐
90 file.option_name=value'.
91 For example, for the ovirt plugin if you wanted to restrict node
93 enumeration to a specific cluster you would use '-c ovirt.clus‐
94 ter=example_cluster'.
95 Available cluster options can be listed by running 'sos collect
97 -l'.
98 --chroot CHROOT
100 Sosreport option. Set the chroot mode. When --sysroot is used
101 commands default to executing with SYSROOT as the root direc‐
102 tory. This can be overridden by setting --chroot to "always"
103 (always chroot) or "never" (always run in the host namespace).
104 --case-id CASE_ID
106 Sosreport option. Specifies a case number identifier.
107 --cluster-type CLUSTER_TYPE
109 When run by itself, sos collect will attempt to identify the
110 type of cluster at play. This is done by checking package or
111 configuration information against the localhost, or the primary
112 node if "--primary" is supplied.
113 Setting --cluster-type skips this step and forcibly sets a par‐
115 ticular profile.
116 Using a value of none or jbon (just a bunch of nodes) will ef‐
118 fectively disable all cluster-specific checks, and cause sos
119 collect to only use the nodes specified by the --nodes option.
120 Note that in this scenario, regex string(s) for node names will
121 be ignored.
122 Example: sos collect --cluster-type=kubernetes will force the
124 kubernetes profile to be run, and thus set sosreport options and
125 attempt to determine a list of nodes using that profile.
126 --container-runtime RUNTIME
128 sos report option. Using this with collect will pass this op‐
129 tion thru to nodes with sos version 4.3 or later. This option
130 controls the default container runtime plugins will use for col‐
131 lections. See man sos-report.
132 -e ENABLE_PLUGINS, --enable-plugins ENABLE_PLUGINS
134 Sosreport option. Use this to enable a plugin that would other‐
135 wise not be run.
136 This option supports providing a comma-delimited list of plug‐
138 ins.
139 --encrypt-key KEY
141 Encrypts the resulting archive that sos collect produces using
142 GPG. KEY must be an existing key in the user's keyring as GPG
143 does not allow for keyfiles. KEY can be any value accepted by
144 gpg's 'recipient' option.
145 Note that the user running sos collect must match the user own‐
147 ing the keyring from which keys will be obtained. In particular
148 this means that if sudo is used to run sos collect, the keyring
149 must also be set up using sudo (or direct shell access to the
150 account).
151 Users should be aware that encrypting the final archive will re‐
153 sult in sos using double the amount of temporary disk space -
154 the encrypted archive must be written as a separate, rather than
155 replacement, file within the temp directory that sos writes the
156 archive to. However, since the encrypted archive will be the
157 same size as the original archive, there is no additional space
158 consumption once the temporary directory is removed at the end
159 of execution.
160 This means that only the encrypted archive is present on disk
162 after sos finishes running.
163 If encryption fails for any reason, the original unencrypted ar‐
165 chive is preserved instead.
166 IMPORTANT: As of this version of sos collect, only the final ar‐
168 chive on the local machine running sos collect will be en‐
169 crypted. The individual sos reports that are collected on the
170 nodes will be collected unencrypted.
171 --encrypt-pass PASS
173 The same as --encrypt-key, but use the provided PASS for symmet‐
174 ric encryption rather than key-pair encryption.
175 --group GROUP
178 Specify an existing host group definition to use.
179 Host groups are pre-defined settings for the cluster-type, pri‐
181 mary node, and nodes options saved in JSON-formatted files under
182 /var/lib/sos collect/<GROUP>.
183 If cluster_type and/or primary are set in the group, sos collect
185 behaves as if these values were specified on the command-line.
186 If nodes is defined, sos collect extends the --nodes option, if
188 set, with the nodes or regexes listed in the group.
189 Note that sos collect will only write group definitions to
191 /var/lib/sos collect/ however the GROUP value may be a filename
192 for any group definitions that exist outside of the default lo‐
193 cation. If you are manually writing these files, use the value
194 null when a python NoneType is expected. Caveat: use string
195 'none' if setting cluster_type to none.
196 --save-group GROUP
198 Save the results of this run of sos collect to a host group def‐
199 inition.
200 sos-colllector will write a JSON-formatted file with name GROUP
202 to /var/lib/sos collect/ with the settings for cluster-type,
203 primary, and the node list as discovered by cluster enumeration.
204 Note that this means regexes are not directly saved to host
205 groups, but the results of matching against those regexes are.
206 -j JOBS --jobs JOBS
208 Specify the number of concurrent node collections that should be
209 run.
210 If the number of nodes enumerated exceeds the number of JOBS,
212 then sos collect will start collecting from the first X number
213 of nodes and then continue to iterate through the remaining
214 nodes as sosreport collection finishes.
215 Defaults to 4.
217 --nopasswd-sudo
219 Use this option when connecting as a non-root user that has
220 passwordless sudo configured.
221 If this option is omitted and a bogus sudo password is supplied,
223 collection of sosreports may exhibit unexpected behavior and/or
224 fail entirely.
225 -k PLUGIN_OPTION, --plugin-option PLUGIN_OPTION
227 Sosreport option. Set a plugin option to a particular value.
228 This takes the form of plugin_name.option_name=value.
229 Example: To enable the kubernetes "all" option in sosreport use
231 -k kubernetes.all=on.
232 --label LABEL
234 Specify a label to be added to the archive names. This label
235 will be applied to both the sos collect archive and the sosre‐
236 port archives.
237 If a cluster sets a default label, the user-provided label will
239 be appended to that cluster default.
240 --log-size SIZE
242 Places a limit on the size of collected logs and output in MiB.
243 Note that this causes sos to capture the last X amount of the
244 file or command output collected.
245 By default, this is set to 25 MiB and applies to all files and
247 command output collected with the exception of journal collec‐
248 tions, which are limited to 100 MiB.
249 Setting this value to 0 removes all size limitations, and any
251 files or commands collected will be collected in their entirety,
252 which may drastically increase the size of the final sos report
253 tarball and the memory usage of sos during collection of com‐
254 mands, such as very large journals that may be several GiB in
255 size.
256 -n SKIP_PLUGINS, --skip-plugins SKIP_PLUGINS
258 Sosreport option. Disable (skip) a particular plugin that would
259 otherwise run. This is useful if a particular plugin is prone
260 to hanging for one reason or another.
261 This option supports providing a comma-delimited list of plug‐
263 ins.
264 --nodes NODES
266 Provide a comma-delimited list of nodes to collect sosreports
267 from, or a regex string to be used to compare discovered node
268 names against. If using a regex, only nodes matching the regex
269 will be used - i.e. it can be used as a whitelist but not a
270 blacklist.
271 This option can be handed multiple regex strings separated by
273 commas. Additionally, both whole node names/addresses and regex
274 strings may be provided at the same time.
275 --no-pkg-check
277 Do not perform package checks. Most cluster profiles check
278 against installed packages to determine if the cluster profile
279 should be applied or not.
280 Use this with --cluster-type if there are rpm or apt issues on
282 the primary/local node.
283 --no-local
285 Do not collect a sosreport from the local system.
286 If --primary is not supplied, it is assumed that the host run‐
288 ning sosreport is part of the cluster that is to be collected.
289 Use this option to skip collection of a local sosreport.
290 This option is NOT needed if --primary is provided.
292 --primary PRIMARY
294 Specify a primary node IP address or hostname for the cluster.
295 If provided, then sos collect will check the primary node, not
297 localhost, for determining the type of cluster in use.
298 --image IMAGE
300 Specify an image to use for the temporary container created for
301 collections on containerized host, if you do not want to use the
302 default image specifed by the host's policy. Note that this
303 should include the registry.
304 --force-pull-image TOGGLE, --pull TOGGLE
306 When collecting an sos report from a containerized host, force
307 the host to always pull the specified image, even if that image
308 already exists on the host. This is useful to ensure that the
309 latest version of that image is always in use. Disabling this
310 option will use whatever version of the image is present on the
311 node, and only attempt a pull if there is no copy of the image
312 present at all.
313 Enable with true/on/yes or disable with false/off/no
315 Default: true
317 --registry-user USER
319 Specify the username to authenticate to the registry with in or‐
320 der to pull the container image
321 --registry-password PASSWORD
323 Specify the password to authenticate to the registry with in or‐
324 der to pull the container image. If no password is required,
325 leave this blank.
326 --registry-authfile FILE
328 Specify the filename to use for providing authentication creden‐
329 tials to the registry to pull the container image.
330 Note that this file must exist on the node(s) performing the
332 pull operations, not the node from which sos collect was run.
333 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
335 Sosreport option. Run ONLY the plugins listed.
336 Note that a cluster profile will NOT override this option. This
338 may cause the sosreports generated to not contain the relevant
339 output for a given type of cluster.
340 This option supports providing a comma-delimited list of plug‐
342 ins.
343 --password
345 Specifying this option will cause sos collect to prompt the user
346 for an SSH password that will be used to connect to all nodes.
347 If you have differing passwords for the same user across cluster
349 nodes, you should ideally deploy SSH keys, but the --pass‐
350 word-per-node option is also available.
351 --password-per-node
353 When using this option, sos collect will prompt the user for the
354 SSH password for each node that will have an sosreport collected
355 from it individually before attempting to connect to the nodes.
356 --preset PRESET
358 Specify a sos preset to use, note that this requires sos-3.6 or
359 later to be installed on the node. The given preset must also
360 exist on the remote node - local presets are not used.
361 If --preset is specified and a given node either does not have
363 that preset defined, or has a version of sos prior to 3.6, this
364 option is ignored for that node.
365 -p SSH_PORT, --ssh-port SSH_PORT
367 Specify SSH port for all nodes. Use this if SSH runs on any port
368 other than 22.
369 --skip-commands COMMANDS
371 A comma delimited list of commands to skip execution of, but
372 still allowing the rest of the plugin that calls the command to
373 run. This will generally need to be some form of UNIX shell-
374 style wildcard matching. For example, using a value of hostname
375 will skip only that single command, while using hostname* will
376 skip all commands with names that begin with the string "host‐
377 name".
378 --skip-files FILES
380 A comma delimited list of files or filepath wildcard matches to
381 skip collection of. Values may either be exact filepaths or
382 paths using UNIX shell-style wildcards, for example /etc/sos/*.
383 --ssh-user SSH_USER
385 Specify an SSH user for sos collect to connect to nodes with.
386 Default is root.
387 sos collect will prompt for a sudo password for non-root users.
389 -s SYSROOT, --sysroot SYSROOT
391 Sosreport option. Specify an alternate root file system path.
392 --sos-cmd SOS_CMD
394 Define all options that sosreport should be run with on the
395 nodes. This will override any other commandline options as well
396 as any options specified by a cluster profile.
397 The sosreport command will execute as 'sosreport --batch
399 SOS_CMD'. The BATCH option cannot be removed from the sosreport
400 command as it is required to run sosreport non-interactively for
401 sos collect to function.
402 -t THREADS --threads THREADS
404 Report option. Specify the number of collection threads to run.
405 The report process on each node will run THREADS number of plug‐
407 ins concurrently during the collection process.
408 Defaults to 4.
410 --timeout TIMEOUT
412 Timeout for sosreport generation on each node, in seconds.
413 Note that sosreports are collected in parallel, so you can ap‐
415 proximate the total runtime of sos collect via timeout*(number
416 of nodes/jobs).
417 Default is 180 seconds.
419 --transport TRANSPORT
421 Specify the type of remote transport to use to manage connec‐
422 tions to remote nodes.
423 sos collect uses locally installed binaries to connect to and
425 interact with remote nodes, instead of directly establishing
426 those connections. By default, OpenSSH's ControlPersist feature
427 is preferred, however certain cluster types may have preferences
428 of their own for how remote sessions should be established.
429 The types of transports supported are currently as follows:
431 auto Allow the cluster type to determine
433 the transport used
434 control_persist Use OpenSSH's ControlPersist feature.
435 This is the default behavior
436 oc Use a locally configured oc binary to
437 deploy collection pods on OCP nodes
438 --tmp-dir TMP_DIR
441 Specify a temporary directory to save sos archives to. By de‐
442 fault one will be created in /tmp and then removed after sos
443 collect has finished running.
444 This is NOT the same as specifying a temporary directory for
446 sosreport on the remote nodes.
447 -v --verbose
449 Print debug information to screen.
450 --verfiy
452 Sosreport option. Passes the "--verify" option to sosreport on
453 the nodes which causes sosreport to validate plugin-specific
454 data during collection.
455 Note that this option may considerably extend the time it takes
457 sosreport to run on the nodes. Consider increasing --timeout
458 when using this option.
459 -z COMPRESSION, --compression-type COMPRESSION
461 Sosreport option. Override the default compression type.
462
465 sos(1) sos-report(1) sos-clean(1) sos.conf(5)
466
469 Jake Hunsaker <jhunsake@redhat.com>
470April 2020 1 SOS(COLLECT)