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]
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
306 Use this option to force the container runtime to pull the spec‐
307 ified image (even if it is the policy default image) even if the
308 image already exists on the host. This may be useful to update
309 an older container image on containerized hosts.
310 --registry-user USER
312 Specify the username to authenticate to the registry with in or‐
313 der to pull the container image
314 --registry-password PASSWORD
316 Specify the password to authenticate to the registry with in or‐
317 der to pull the container image. If no password is required,
318 leave this blank.
319 --registry-authfile FILE
321 Specify the filename to use for providing authentication creden‐
322 tials to the registry to pull the container image.
323 Note that this file must exist on the node(s) performing the
325 pull operations, not the node from which sos collect was run.
326 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
328 Sosreport option. Run ONLY the plugins listed.
329 Note that a cluster profile will NOT override this option. This
331 may cause the sosreports generated to not contain the relevant
332 output for a given type of cluster.
333 This option supports providing a comma-delimited list of plug‐
335 ins.
336 --password
338 Specifying this option will cause sos collect to prompt the user
339 for an SSH password that will be used to connect to all nodes.
340 If you have differing passwords for the same user across cluster
342 nodes, you should ideally deploy SSH keys, but the --pass‐
343 word-per-node option is also available.
344 --password-per-node
346 When using this option, sos collect will prompt the user for the
347 SSH password for each node that will have an sosreport collected
348 from it individually before attempting to connect to the nodes.
349 --preset PRESET
351 Specify a sos preset to use, note that this requires sos-3.6 or
352 later to be installed on the node. The given preset must also
353 exist on the remote node - local presets are not used.
354 If --preset is specified and a given node either does not have
356 that preset defined, or has a version of sos prior to 3.6, this
357 option is ignored for that node.
358 -p SSH_PORT, --ssh-port SSH_PORT
360 Specify SSH port for all nodes. Use this if SSH runs on any port
361 other than 22.
362 --skip-commands COMMANDS
364 A comma delimited list of commands to skip execution of, but
365 still allowing the rest of the plugin that calls the command to
366 run. This will generally need to be some form of UNIX shell-
367 style wildcard matching. For example, using a value of hostname
368 will skip only that single command, while using hostname* will
369 skip all commands with names that begin with the string "host‐
370 name".
371 --skip-files FILES
373 A comma delimited list of files or filepath wildcard matches to
374 skip collection of. Values may either be exact filepaths or
375 paths using UNIX shell-style wildcards, for example /etc/sos/*.
376 --ssh-user SSH_USER
378 Specify an SSH user for sos collect to connect to nodes with.
379 Default is root.
380 sos collect will prompt for a sudo password for non-root users.
382 -s SYSROOT, --sysroot SYSROOT
384 Sosreport option. Specify an alternate root file system path.
385 --sos-cmd SOS_CMD
387 Define all options that sosreport should be run with on the
388 nodes. This will override any other commandline options as well
389 as any options specified by a cluster profile.
390 The sosreport command will execute as 'sosreport --batch
392 SOS_CMD'. The BATCH option cannot be removed from the sosreport
393 command as it is required to run sosreport non-interactively for
394 sos collect to function.
395 -t THREADS --threads THREADS
397 Report option. Specify the number of collection threads to run.
398 The report process on each node will run THREADS number of plug‐
400 ins concurrently during the collection process.
401 Defaults to 4.
403 --timeout TIMEOUT
405 Timeout for sosreport generation on each node, in seconds.
406 Note that sosreports are collected in parallel, so you can ap‐
408 proximate the total runtime of sos collect via timeout*(number
409 of nodes/jobs).
410 Default is 180 seconds.
412 --transport TRANSPORT
414 Specify the type of remote transport to use to manage connec‐
415 tions to remote nodes.
416 sos collect uses locally installed binaries to connect to and
418 interact with remote nodes, instead of directly establishing
419 those connections. By default, OpenSSH's ControlPersist feature
420 is preferred, however certain cluster types may have preferences
421 of their own for how remote sessions should be established.
422 The types of transports supported are currently as follows:
424 auto Allow the cluster type to determine
426 the transport used
427 control_persist Use OpenSSH's ControlPersist feature.
428 This is the default behavior
429 oc Use a locally configured oc binary to
430 deploy collection pods on OCP nodes
431 --tmp-dir TMP_DIR
434 Specify a temporary directory to save sos archives to. By de‐
435 fault one will be created in /tmp and then removed after sos
436 collect has finished running.
437 This is NOT the same as specifying a temporary directory for
439 sosreport on the remote nodes.
440 -v --verbose
442 Print debug information to screen.
443 --verfiy
445 Sosreport option. Passes the "--verify" option to sosreport on
446 the nodes which causes sosreport to validate plugin-specific
447 data during collection.
448 Note that this option may considerably extend the time it takes
450 sosreport to run on the nodes. Consider increasing --timeout
451 when using this option.
452 -z COMPRESSION, --compression-type COMPRESSION
454 Sosreport option. Override the default compression type.
455
458 sos(1) sos-report(1) sos-clean(1) sos.conf(5)
459
462 Jake Hunsaker <jhunsake@redhat.com>
463April 2020 1 SOS(COLLECT)