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 [-t|--threads THREADS]
48 [--timeout TIMEOUT]
49 [--transport TRANSPORT]
50 [--tmp-dir TMP_DIR]
51 [-v|--verbose]
52 [--verify]
53 [-z|--compression-type COMPRESSION_TYPE]
54
57 collect is an sos subcommand to collect sosreports from multiple nodes
58 and package them in a single useful tar archive.
59 sos collect can be run either on a workstation that has SSH key authen‐
61 tication setup for the nodes in a given cluster, or from a "primary"
62 node in a cluster that has SSH keys configured for the other nodes.
63 Some sosreport options are supported by sos-collect and are passed di‐
65 rectly to the sosreport command run on each node.
66
69 -a, --alloptions
70 Enables all sosreport options.
71 This does NOT enable all sos collect options.
73 -b, --become
75 Become the root user on the remote node when connecting as a
76 non-root user.
77 --batch
79 Run in non-interactive mode. This will skip prompts for user in‐
80 put, with the exception of a prompt for the SSH password.
81 --all-logs
83 Sosreport option. Collects all logs regardless of size.
84 Default: no
86 -c CLUSTER_OPTIONS
88 Specify options used by cluster profiles. The format is 'pro‐
89 file.option_name=value'.
90 For example, for the ovirt plugin if you wanted to restrict node
92 enumeration to a specific cluster you would use '-c ovirt.clus‐
93 ter=example_cluster'.
94 Available cluster options can be listed by running 'sos collect
96 -l'.
97 --chroot CHROOT
99 Sosreport option. Set the chroot mode. When --sysroot is used
100 commands default to executing with SYSROOT as the root direc‐
101 tory. This can be overridden by setting --chroot to "always"
102 (always chroot) or "never" (always run in the host namespace).
103 --case-id CASE_ID
105 Sosreport option. Specifies a case number identifier.
106 --cluster-type CLUSTER_TYPE
108 When run by itself, sos collect will attempt to identify the
109 type of cluster at play. This is done by checking package or
110 configuration information against the localhost, or the primary
111 node if "--primary" is supplied.
112 Setting --cluster-type skips this step and forcibly sets a par‐
114 ticular profile.
115 Using a value of none or jbon (just a bunch of nodes) will ef‐
117 fectively disable all cluster-specific checks, and cause sos
118 collect to only use the nodes specified by the --nodes option.
119 Note that in this scenario, regex string(s) for node names will
120 be ignored.
121 Example: sos collect --cluster-type=kubernetes will force the
123 kubernetes profile to be run, and thus set sosreport options and
124 attempt to determine a list of nodes using that profile.
125 --container-runtime RUNTIME
127 sos report option. Using this with collect will pass this op‐
128 tion thru to nodes with sos version 4.3 or later. This option
129 controls the default container runtime plugins will use for col‐
130 lections. See man sos-report.
131 -e ENABLE_PLUGINS, --enable-plugins ENABLE_PLUGINS
133 Sosreport option. Use this to enable a plugin that would other‐
134 wise not be run.
135 This option supports providing a comma-delimited list of plug‐
137 ins.
138 --encrypt-key KEY
140 Encrypts the resulting archive that sos collect produces using
141 GPG. KEY must be an existing key in the user's keyring as GPG
142 does not allow for keyfiles. KEY can be any value accepted by
143 gpg's 'recipient' option.
144 Note that the user running sos collect must match the user own‐
146 ing the keyring from which keys will be obtained. In particular
147 this means that if sudo is used to run sos collect, the keyring
148 must also be set up using sudo (or direct shell access to the
149 account).
150 Users should be aware that encrypting the final archive will re‐
152 sult in sos using double the amount of temporary disk space -
153 the encrypted archive must be written as a separate, rather than
154 replacement, file within the temp directory that sos writes the
155 archive to. However, since the encrypted archive will be the
156 same size as the original archive, there is no additional space
157 consumption once the temporary directory is removed at the end
158 of execution.
159 This means that only the encrypted archive is present on disk
161 after sos finishes running.
162 If encryption fails for any reason, the original unencrypted ar‐
164 chive is preserved instead.
165 IMPORTANT: As of this version of sos collect, only the final ar‐
167 chive on the local machine running sos collect will be en‐
168 crypted. The individual sos reports that are collected on the
169 nodes will be collected unencrypted.
170 --encrypt-pass PASS
172 The same as --encrypt-key, but use the provided PASS for symmet‐
173 ric encryption rather than key-pair encryption.
174 --group GROUP
177 Specify an existing host group definition to use.
178 Host groups are pre-defined settings for the cluster-type, pri‐
180 mary node, and nodes options saved in JSON-formatted files under
181 /var/lib/sos collect/<GROUP>.
182 If cluster_type and/or primary are set in the group, sos collect
184 behaves as if these values were specified on the command-line.
185 If nodes is defined, sos collect extends the --nodes option, if
187 set, with the nodes or regexes listed in the group.
188 Note that sos collect will only write group definitions to
190 /var/lib/sos collect/ however the GROUP value may be a filename
191 for any group definitions that exist outside of the default lo‐
192 cation. If you are manually writing these files, use the value
193 null when a python NoneType is expected. Caveat: use string
194 'none' if setting cluster_type to none.
195 --save-group GROUP
197 Save the results of this run of sos collect to a host group def‐
198 inition.
199 sos-collector will write a JSON-formatted file with name GROUP
201 to /var/lib/sos collect/ with the settings for cluster-type,
202 primary, and the node list as discovered by cluster enumeration.
203 Note that this means regexes are not directly saved to host
204 groups, but the results of matching against those regexes are.
205 -j JOBS --jobs JOBS
207 Specify the number of concurrent node collections that should be
208 run.
209 If the number of nodes enumerated exceeds the number of JOBS,
211 then sos collect will start collecting from the first X number
212 of nodes and then continue to iterate through the remaining
213 nodes as sosreport collection finishes.
214 Defaults to 4.
216 --nopasswd-sudo
218 Use this option when connecting as a non-root user that has
219 passwordless sudo configured.
220 If this option is omitted and a bogus sudo password is supplied,
222 collection of sosreports may exhibit unexpected behavior and/or
223 fail entirely.
224 -k PLUGIN_OPTION, --plugin-option PLUGIN_OPTION
226 Sosreport option. Set a plugin option to a particular value.
227 This takes the form of plugin_name.option_name=value.
228 Example: To enable the kubernetes "all" option in sosreport use
230 -k kubernetes.all=on.
231 --label LABEL
233 Specify a label to be added to the archive names. This label
234 will be applied to both the sos collect archive and the sosre‐
235 port archives.
236 If a cluster sets a default label, the user-provided label will
238 be appended to that cluster default.
239 --log-size SIZE
241 Places a limit on the size of collected logs and output in MiB.
242 Note that this causes sos to capture the last X amount of the
243 file or command output collected.
244 By default, this is set to 25 MiB and applies to all files and
246 command output collected with the exception of journal collec‐
247 tions, which are limited to 100 MiB.
248 Setting this value to 0 removes all size limitations, and any
250 files or commands collected will be collected in their entirety,
251 which may drastically increase the size of the final sos report
252 tarball and the memory usage of sos during collection of com‐
253 mands, such as very large journals that may be several GiB in
254 size.
255 -n SKIP_PLUGINS, --skip-plugins SKIP_PLUGINS
257 Sosreport option. Disable (skip) a particular plugin that would
258 otherwise run. This is useful if a particular plugin is prone
259 to hanging for one reason or another.
260 This option supports providing a comma-delimited list of plug‐
262 ins.
263 --nodes NODES
265 Provide a comma-delimited list of nodes to collect sosreports
266 from, or a regex string to be used to compare discovered node
267 names against. If using a regex, only nodes matching the regex
268 will be used - i.e. it can be used as a whitelist but not a
269 blacklist.
270 This option can be handed multiple regex strings separated by
272 commas. Additionally, both whole node names/addresses and regex
273 strings may be provided at the same time.
274 --no-pkg-check
276 Do not perform package checks. Most cluster profiles check
277 against installed packages to determine if the cluster profile
278 should be applied or not.
279 Use this with --cluster-type if there are rpm or apt issues on
281 the primary/local node.
282 --no-local
284 Do not collect a sosreport from the local system.
285 If --primary is not supplied, it is assumed that the host run‐
287 ning sosreport is part of the cluster that is to be collected.
288 Use this option to skip collection of a local sosreport.
289 This option is NOT needed if --primary is provided.
291 --primary PRIMARY
293 Specify a primary node IP address or hostname for the cluster.
294 If provided, then sos collect will check the primary node, not
296 localhost, for determining the type of cluster in use.
297 --image IMAGE
299 Specify an image to use for the temporary container created for
300 collections on containerized host, if you do not want to use the
301 default image specified by the host's policy. Note that this
302 should include the registry.
303 --force-pull-image TOGGLE, --pull TOGGLE
305 When collecting an sos report from a containerized host, force
306 the host to always pull the specified image, even if that image
307 already exists on the host. This is useful to ensure that the
308 latest version of that image is always in use. Disabling this
309 option will use whatever version of the image is present on the
310 node, and only attempt a pull if there is no copy of the image
311 present at all.
312 Enable with true/on/yes or disable with false/off/no
314 Default: true
316 --registry-user USER
318 Specify the username to authenticate to the registry with in or‐
319 der to pull the container image
320 --registry-password PASSWORD
322 Specify the password to authenticate to the registry with in or‐
323 der to pull the container image. If no password is required,
324 leave this blank.
325 --registry-authfile FILE
327 Specify the filename to use for providing authentication creden‐
328 tials to the registry to pull the container image.
329 Note that this file must exist on the node(s) performing the
331 pull operations, not the node from which sos collect was run.
332 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
334 Sosreport option. Run ONLY the plugins listed.
335 Note that a cluster profile will NOT override this option. This
337 may cause the sosreports generated to not contain the relevant
338 output for a given type of cluster.
339 This option supports providing a comma-delimited list of plug‐
341 ins.
342 --password
344 Specifying this option will cause sos collect to prompt the user
345 for an SSH password that will be used to connect to all nodes.
346 If you have differing passwords for the same user across cluster
348 nodes, you should ideally deploy SSH keys, but the --pass‐
349 word-per-node option is also available.
350 --password-per-node
352 When using this option, sos collect will prompt the user for the
353 SSH password for each node that will have an sosreport collected
354 from it individually before attempting to connect to the nodes.
355 --preset PRESET
357 Specify a sos preset to use, note that this requires sos-3.6 or
358 later to be installed on the node. The given preset must also
359 exist on the remote node - local presets are not used.
360 If --preset is specified and a given node either does not have
362 that preset defined, or has a version of sos prior to 3.6, this
363 option is ignored for that node.
364 -p SSH_PORT, --ssh-port SSH_PORT
366 Specify SSH port for all nodes. Use this if SSH runs on any port
367 other than 22.
368 --skip-commands COMMANDS
370 A comma delimited list of commands to skip execution of, but
371 still allowing the rest of the plugin that calls the command to
372 run. This will generally need to be some form of UNIX shell-
373 style wildcard matching. For example, using a value of hostname
374 will skip only that single command, while using hostname* will
375 skip all commands with names that begin with the string "host‐
376 name".
377 --skip-files FILES
379 A comma delimited list of files or filepath wildcard matches to
380 skip collection of. Values may either be exact filepaths or
381 paths using UNIX shell-style wildcards, for example /etc/sos/*.
382 --ssh-user SSH_USER
384 Specify an SSH user for sos collect to connect to nodes with.
385 Default is root.
386 sos collect will prompt for a sudo password for non-root users.
388 -s SYSROOT, --sysroot SYSROOT
390 Sosreport option. Specify an alternate root file system path.
391 -t THREADS --threads THREADS
393 Report option. Specify the number of collection threads to run.
394 The report process on each node will run THREADS number of plug‐
396 ins concurrently during the collection process.
397 Defaults to 4.
399 --timeout TIMEOUT
401 Timeout for sosreport generation on each node, in seconds.
402 Note that sosreports are collected in parallel, so you can ap‐
404 proximate the total runtime of sos collect via timeout*(number
405 of nodes/jobs).
406 Default is 180 seconds.
408 --transport TRANSPORT
410 Specify the type of remote transport to use to manage connec‐
411 tions to remote nodes.
412 sos collect uses locally installed binaries to connect to and
414 interact with remote nodes, instead of directly establishing
415 those connections. By default, OpenSSH's ControlPersist feature
416 is preferred, however certain cluster types may have preferences
417 of their own for how remote sessions should be established.
418 The types of transports supported are currently as follows:
420 auto Allow the cluster type to determine
422 the transport used
423 control_persist Use OpenSSH's ControlPersist feature.
424 This is the default behavior
425 oc Use a locally configured oc binary to
426 deploy collection pods on OCP nodes
427 --tmp-dir TMP_DIR
430 Specify a temporary directory to save sos archives to. By de‐
431 fault one will be created in /tmp and then removed after sos
432 collect has finished running.
433 This is NOT the same as specifying a temporary directory for
435 sosreport on the remote nodes.
436 -v --verbose
438 Print debug information to screen.
439 --verify
441 Sosreport option. Passes the "--verify" option to sosreport on
442 the nodes which causes sosreport to validate plugin-specific
443 data during collection.
444 Note that this option may considerably extend the time it takes
446 sosreport to run on the nodes. Consider increasing --timeout
447 when using this option.
448 -z COMPRESSION, --compression-type COMPRESSION
450 Sosreport option. Override the default compression type.
451
454 sos(1) sos-report(1) sos-clean(1) sos.conf(5)
455
458 Maintained on GitHub at https://github.com/sosreport/sos
459
461 See AUTHORS file in the package documentation.
462April 2020 1 SOS(COLLECT)