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 [-e ENABLE_PLUGINS]
18 [--encrypt-key KEY]
19 [--encrypt-pass PASS]
20 [--group GROUP]
21 [-j|--jobs JOBS]
22 [--save-group GROUP]
23 [--nopasswd-sudo]
24 [-k PLUGIN_OPTION]
25 [--label LABEL]
26 [--log-size SIZE]
27 [-n SKIP_PLUGINS]
28 [--nodes NODES]
29 [--no-pkg-check]
30 [--no-local]
31 [--master MASTER]
32 [--image IMAGE]
33 [--force-pull-image]
34 [--registry-user USER]
35 [--registry-password PASSWORD]
36 [--registry-authfile FILE]
37 [-o ONLY_PLUGINS]
38 [-p SSH_PORT]
39 [--password]
40 [--password-per-node]
41 [--preset PRESET]
42 [--skip-commands COMMANDS]
43 [--skip-files FILES]
44 [-s|--sysroot SYSROOT]
45 [--ssh-user SSH_USER]
46 [--sos-cmd SOS_CMD]
47 [-t|--threads THREADS]
48 [--timeout TIMEOUT]
49 [--tmp-dir TMP_DIR]
50 [-v|--verbose]
51 [--verify]
52 [-z|--compression-type COMPRESSION_TYPE]
53
56 collect is an sos subcommand to collect sosreports from multiple nodes
57 and package them in a single useful tar archive.
58 sos collect can be run either on a workstation that has SSH key authen‐
60 tication setup for the nodes in a given cluster, or from a "master"
61 node in a cluster that has SSH keys configured for the other nodes.
62 Some sosreport options are supported by sos-collect and are passed di‐
64 rectly to the sosreport command run on each node.
65
68 -a, --alloptions
69 Enables all sosreport options.
70 This does NOT enable all sos collect options.
72 -b, --become
74 Become the root user on the remote node when connecting as a
75 non-root user.
76 --batch
78 Run in non-interactive mode. This will skip prompts for user in‐
79 put, with the exception of a prompt for the SSH password.
80 --all-logs
82 Sosreport option. Collects all logs regardless of size.
83 Default: no
85 -c CLUSTER_OPTIONS
87 Specify options used by cluster profiles. The format is 'pro‐
88 file.option_name=value'.
89 For example, for the ovirt plugin if you wanted to restrict node
91 enumeration to a specific cluster you would use '-c ovirt.clus‐
92 ter=example_cluster'.
93 Available cluster options can be listed by running 'sos collect
95 -l'.
96 --chroot CHROOT
98 Sosreport option. Set the chroot mode. When --sysroot is used
99 commands default to executing with SYSROOT as the root direc‐
100 tory. This can be overridden by setting --chroot to "always"
101 (always chroot) or "never" (always run in the host namespace).
102 --case-id CASE_ID
104 Sosreport option. Specifies a case number identifier.
105 --cluster-type CLUSTER_TYPE
107 When run by itself, sos collect will attempt to identify the
108 type of cluster at play. This is done by checking package or
109 configuration information against the localhost, or the master
110 node if "--master" is supplied.
111 Setting --cluster-type skips this step and forcibly sets a par‐
113 ticular profile.
114 Using a value of none or jbon (just a bunch of nodes) will ef‐
116 fectively disable all cluster-specific checks, and cause sos
117 collect to only use the nodes specified by the --nodes option.
118 Note that in this scenario, regex string(s) for node names will
119 be ignored.
120 Example: sos collect --cluster-type=kubernetes will force the
122 kubernetes profile to be run, and thus set sosreport options and
123 attempt to determine a list of nodes using that profile.
124 -e ENABLE_PLUGINS, --enable-plugins ENABLE_PLUGINS
126 Sosreport option. Use this to enable a plugin that would other‐
127 wise not be run.
128 This option supports providing a comma-delimited list of plug‐
130 ins.
131 --encrypt-key KEY
133 Encrypts the resulting archive that sos collect produces using
134 GPG. KEY must be an existing key in the user's keyring as GPG
135 does not allow for keyfiles. KEY can be any value accepted by
136 gpg's 'recipient' option.
137 Note that the user running sos collect must match the user own‐
139 ing the keyring from which keys will be obtained. In particular
140 this means that if sudo is used to run sos collect, the keyring
141 must also be set up using sudo (or direct shell access to the
142 account).
143 Users should be aware that encrypting the final archive will re‐
145 sult in sos using double the amount of temporary disk space -
146 the encrypted archive must be written as a separate, rather than
147 replacement, file within the temp directory that sos writes the
148 archive to. However, since the encrypted archive will be the
149 same size as the original archive, there is no additional space
150 consumption once the temporary directory is removed at the end
151 of execution.
152 This means that only the encrypted archive is present on disk
154 after sos finishes running.
155 If encryption fails for any reason, the original unencrypted ar‐
157 chive is preserved instead.
158 IMPORTANT: As of this version of sos collect, only the final ar‐
160 chive on the local machine running sos collect will be en‐
161 crypted. The individual sos reports that are collected on the
162 nodes will be collected unencrypted.
163 --encrypt-pass PASS
165 The same as --encrypt-key, but use the provided PASS for symmet‐
166 ric encryption rather than key-pair encryption.
167 --group GROUP
170 Specify an existing host group definition to use.
171 Host groups are pre-defined settings for the cluster-type, mas‐
173 ter, and nodes options saved in JSON-formatted files under
174 /var/lib/sos collect/<GROUP>.
175 If cluster_type and/or master are set in the group, sos collect
177 behaves as if these values were specified on the command-line.
178 If nodes is defined, sos collect extends the --nodes option, if
180 set, with the nodes or regexes listed in the group.
181 Note that sos collect will only write group definitions to
183 /var/lib/sos collect/ however the GROUP value may be a filename
184 for any group definitions that exist outside of the default lo‐
185 cation. If you are manually writing these files, use the value
186 null when a python NoneType is expected. Caveat: use string
187 'none' if setting cluster_type to none.
188 --save-group GROUP
190 Save the results of this run of sos collect to a host group def‐
191 inition.
192 sos-colllector will write a JSON-formatted file with name GROUP
194 to /var/lib/sos collect/ with the settings for cluster-type,
195 master, and the node list as discovered by cluster enumeration.
196 Note that this means regexes are not directly saved to host
197 groups, but the results of matching against those regexes are.
198 -j JOBS --jobs JOBS
200 Specify the number of concurrent node collections that should be
201 run.
202 If the number of nodes enumerated exceeds the number of JOBS,
204 then sos collect will start collecting from the first X number
205 of nodes and then continue to iterate through the remaining
206 nodes as sosreport collection finishes.
207 Defaults to 4.
209 --nopasswd-sudo
211 Use this option when connecting as a non-root user that has
212 passwordless sudo configured.
213 If this option is omitted and a bogus sudo password is supplied,
215 collection of sosreports may exhibit unexpected behavior and/or
216 fail entirely.
217 -k PLUGIN_OPTION, --plugin-option PLUGIN_OPTION
219 Sosreport option. Set a plugin option to a particular value.
220 This takes the form of plugin_name.option_name=value.
221 Example: To enable the kubernetes "all" option in sosreport use
223 -k kubernetes.all=on.
224 --label LABEL
226 Specify a label to be added to the archive names. This label
227 will be applied to both the sos collect archive and the sosre‐
228 port archives.
229 If a cluster sets a default label, the user-provided label will
231 be appended to that cluster default.
232 --log-size SIZE
234 Places a limit on the size of collected logs and output in MiB.
235 Note that this causes sos to capture the last X amount of the
236 file or command output collected.
237 By default, this is set to 25 MiB and applies to all files and
239 command output collected with the exception of journal collec‐
240 tions, which are limited to 100 MiB.
241 Setting this value to 0 removes all size limitations, and any
243 files or commands collected will be collected in their entirety,
244 which may drastically increase the size of the final sos report
245 tarball and the memory usage of sos during collection of com‐
246 mands, such as very large journals that may be several GiB in
247 size.
248 -n SKIP_PLUGINS, --skip-plugins SKIP_PLUGINS
250 Sosreport option. Disable (skip) a particular plugin that would
251 otherwise run. This is useful if a particular plugin is prone
252 to hanging for one reason or another.
253 This option supports providing a comma-delimited list of plug‐
255 ins.
256 --nodes NODES
258 Provide a comma-delimited list of nodes to collect sosreports
259 from, or a regex string to be used to compare discovered node
260 names against. If using a regex, only nodes matching the regex
261 will be used - i.e. it can be used as a whitelist but not a
262 blacklist.
263 This option can be handed multiple regex strings separated by
265 commas. Additionally, both whole node names/addresses and regex
266 strings may be provided at the same time.
267 --no-pkg-check
269 Do not perform package checks. Most cluster profiles check
270 against installed packages to determine if the cluster profile
271 should be applied or not.
272 Use this with --cluster-type if there are rpm or apt issues on
274 the master/local node.
275 --no-local
277 Do not collect a sosreport from the local system.
278 If --master is not supplied, it is assumed that the host running
280 sosreport is part of the cluster that is to be collected. Use
281 this option to skip collection of a local sosreport.
282 This option is NOT needed if --master is provided.
284 --master MASTER
286 Specify a master node for the cluster.
287 If provided, then sos collect will check the master node, not
289 localhost, for determining the type of cluster in use.
290 --image IMAGE
292 Specify an image to use for the temporary container created for
293 collections on containerized host, if you do not want to use the
294 default image specifed by the host's policy. Note that this
295 should include the registry.
296 --force-pull-image
298 Use this option to force the container runtime to pull the spec‐
299 ified image (even if it is the policy default image) even if the
300 image already exists on the host. This may be useful to update
301 an older container image on containerized hosts.
302 --registry-user USER
304 Specify the username to authenticate to the registry with in or‐
305 der to pull the container image
306 --registry-password PASSWORD
308 Specify the password to authenticate to the registry with in or‐
309 der to pull the container image. If no password is required,
310 leave this blank.
311 --registry-authfile FILE
313 Specify the filename to use for providing authentication creden‐
314 tials to the registry to pull the container image.
315 Note that this file must exist on the node(s) performing the
317 pull operations, not the node from which sos collect was run.
318 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
320 Sosreport option. Run ONLY the plugins listed.
321 Note that a cluster profile will NOT override this option. This
323 may cause the sosreports generated to not contain the relevant
324 output for a given type of cluster.
325 This option supports providing a comma-delimited list of plug‐
327 ins.
328 --password
330 Specifying this option will cause sos collect to prompt the user
331 for an SSH password that will be used to connect to all nodes.
332 If you have differing passwords for the same user across cluster
334 nodes, you should ideally deploy SSH keys, but the --pass‐
335 word-per-node option is also available.
336 --password-per-node
338 When using this option, sos collect will prompt the user for the
339 SSH password for each node that will have an sosreport collected
340 from it individually before attempting to connect to the nodes.
341 --preset PRESET
343 Specify a sos preset to use, note that this requires sos-3.6 or
344 later to be installed on the node. The given preset must also
345 exist on the remote node - local presets are not used.
346 If --preset is specified and a given node either does not have
348 that preset defined, or has a version of sos prior to 3.6, this
349 option is ignored for that node.
350 -p SSH_PORT, --ssh-port SSH_PORT
352 Specify SSH port for all nodes. Use this if SSH runs on any port
353 other than 22.
354 --skip-commands COMMANDS
356 A comma delimited list of commands to skip execution of, but
357 still allowing the rest of the plugin that calls the command to
358 run. This will generally need to be some form of UNIX shell-
359 style wildcard matching. For example, using a value of hostname
360 will skip only that single command, while using hostname* will
361 skip all commands with names that begin with the string "host‐
362 name".
363 --skip-files FILES
365 A comma delimited list of files or filepath wildcard matches to
366 skip collection of. Values may either be exact filepaths or
367 paths using UNIX shell-style wildcards, for example /etc/sos/*.
368 --ssh-user SSH_USER
370 Specify an SSH user for sos collect to connect to nodes with.
371 Default is root.
372 sos collect will prompt for a sudo password for non-root users.
374 -s SYSROOT, --sysroot SYSROOT
376 Sosreport option. Specify an alternate root file system path.
377 --sos-cmd SOS_CMD
379 Define all options that sosreport should be run with on the
380 nodes. This will override any other commandline options as well
381 as any options specified by a cluster profile.
382 The sosreport command will execute as 'sosreport --batch
384 SOS_CMD'. The BATCH option cannot be removed from the sosreport
385 command as it is required to run sosreport non-interactively for
386 sos collect to function.
387 -t THREADS --threads THREADS
389 Report option. Specify the number of collection threads to run.
390 The report process on each node will run THREADS number of plug‐
392 ins concurrently during the collection process.
393 Defaults to 4.
395 --timeout TIMEOUT
397 Timeout for sosreport generation on each node, in seconds.
398 Note that sosreports are collected in parallel, so you can ap‐
400 proximate the total runtime of sos collect via timeout*(number
401 of nodes/jobs).
402 Default is 180 seconds.
404 --tmp-dir TMP_DIR
406 Specify a temporary directory to save sos archives to. By de‐
407 fault one will be created in /tmp and then removed after sos
408 collect has finished running.
409 This is NOT the same as specifying a temporary directory for
411 sosreport on the remote nodes.
412 -v --verbose
414 Print debug information to screen.
415 --verfiy
417 Sosreport option. Passes the "--verify" option to sosreport on
418 the nodes which causes sosreport to validate plugin-specific
419 data during collection.
420 Note that this option may considerably extend the time it takes
422 sosreport to run on the nodes. Consider increasing --timeout
423 when using this option.
424 -z COMPRESSION, --compression-type COMPRESSION
426 Sosreport option. Override the default compression type.
427
430 sos(1) sos-report(1) sos-clean(1) sos.conf(5)
431
434 Jake Hunsaker <jhunsake@redhat.com>
435April 2020 1 SOS(COLLECT)