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 [-n SKIP_PLUGINS]
27 [--nodes NODES]
28 [--no-pkg-check]
29 [--no-local]
30 [--master MASTER]
31 [-o ONLY_PLUGINS]
32 [-p SSH_PORT]
33 [--password]
34 [--password-per-node]
35 [--preset PRESET]
36 [--skip-commands COMMANDS]
37 [--skip-files FILES]
38 [-s|--sysroot SYSROOT]
39 [--ssh-user SSH_USER]
40 [--sos-cmd SOS_CMD]
41 [-t|--threads THREADS]
42 [--timeout TIMEOUT]
43 [--tmp-dir TMP_DIR]
44 [-v|--verbose]
45 [--verify]
46 [-z|--compression-type COMPRESSION_TYPE]
47
50 collect is an sos subcommand to collect sosreports from multiple nodes
51 and package them in a single useful tar archive.
52 sos collect can be run either on a workstation that has SSH key authen‐
54 tication setup for the nodes in a given cluster, or from a "master"
55 node in a cluster that has SSH keys configured for the other nodes.
56 Some sosreport options are supported by sos-collect and are passed di‐
58 rectly to the sosreport command run on each node.
59
62 -a, --alloptions
63 Enables all sosreport options.
64 This does NOT enable all sos collect options.
66 -b, --become
68 Become the root user on the remote node when connecting as a
69 non-root user.
70 --batch
72 Run in non-interactive mode. This will skip prompts for user in‐
73 put, with the exception of a prompt for the SSH password.
74 --all-logs
76 Sosreport option. Collects all logs regardless of size.
77 Default: no
79 -c CLUSTER_OPTIONS
81 Specify options used by cluster profiles. The format is 'pro‐
82 file.option_name=value'.
83 For example, for the ovirt plugin if you wanted to restrict node
85 enumeration to a specific cluster you would use '-c ovirt.clus‐
86 ter=example_cluster'.
87 Available cluster options can be listed by running 'sos collect
89 -l'.
90 --chroot CHROOT
92 Sosreport option. Set the chroot mode. When --sysroot is used
93 commands default to executing with SYSROOT as the root direc‐
94 tory. This can be overridden by setting --chroot to "always"
95 (always chroot) or "never" (always run in the host namespace).
96 --case-id CASE_ID
98 Sosreport option. Specifies a case number identifier.
99 --cluster-type CLUSTER_TYPE
101 When run by itself, sos collect will attempt to identify the
102 type of cluster at play. This is done by checking package or
103 configuration information against the localhost, or the master
104 node if "--master" is supplied.
105 Setting --cluster-type skips this step and forcibly sets a par‐
107 ticular profile.
108 Using a value of none or jbon (just a bunch of nodes) will ef‐
110 fectively disable all cluster-specific checks, and cause sos
111 collect to only use the nodes specified by the --nodes option.
112 Note that in this scenario, regex string(s) for node names will
113 be ignored.
114 Example: sos collect --cluster-type=kubernetes will force the
116 kubernetes profile to be run, and thus set sosreport options and
117 attempt to determine a list of nodes using that profile.
118 -e ENABLE_PLUGINS, --enable-plugins ENABLE_PLUGINS
120 Sosreport option. Use this to enable a plugin that would other‐
121 wise not be run.
122 This option supports providing a comma-delimited list of plug‐
124 ins.
125 --encrypt-key KEY
127 Encrypts the resulting archive that sos collect produces using
128 GPG. KEY must be an existing key in the user's keyring as GPG
129 does not allow for keyfiles. KEY can be any value accepted by
130 gpg's 'recipient' option.
131 Note that the user running sos collect must match the user own‐
133 ing the keyring from which keys will be obtained. In particular
134 this means that if sudo is used to run sos collect, the keyring
135 must also be set up using sudo (or direct shell access to the
136 account).
137 Users should be aware that encrypting the final archive will re‐
139 sult in sos using double the amount of temporary disk space -
140 the encrypted archive must be written as a separate, rather than
141 replacement, file within the temp directory that sos writes the
142 archive to. However, since the encrypted archive will be the
143 same size as the original archive, there is no additional space
144 consumption once the temporary directory is removed at the end
145 of execution.
146 This means that only the encrypted archive is present on disk
148 after sos finishes running.
149 If encryption fails for any reason, the original unencrypted ar‐
151 chive is preserved instead.
152 IMPORTANT: As of this version of sos collect, only the final ar‐
154 chive on the local machine running sos collect will be en‐
155 crypted. The individual sos reports that are collected on the
156 nodes will be collected unencrypted.
157 --encrypt-pass PASS
159 The same as --encrypt-key, but use the provided PASS for symmet‐
160 ric encryption rather than key-pair encryption.
161 --group GROUP
164 Specify an existing host group definition to use.
165 Host groups are pre-defined settings for the cluster-type, mas‐
167 ter, and nodes options saved in JSON-formatted files under
168 /var/lib/sos collect/<GROUP>.
169 If cluster_type and/or master are set in the group, sos collect
171 behaves as if these values were specified on the command-line.
172 If nodes is defined, sos collect extends the --nodes option, if
174 set, with the nodes or regexes listed in the group.
175 Note that sos collect will only write group definitions to
177 /var/lib/sos collect/ however the GROUP value may be a filename
178 for any group definitions that exist outside of the default lo‐
179 cation. If you are manually writing these files, use the value
180 null when a python NoneType is expected. Caveat: use string
181 'none' if setting cluster_type to none.
182 --save-group GROUP
184 Save the results of this run of sos collect to a host group def‐
185 inition.
186 sos-colllector will write a JSON-formatted file with name GROUP
188 to /var/lib/sos collect/ with the settings for cluster-type,
189 master, and the node list as discovered by cluster enumeration.
190 Note that this means regexes are not directly saved to host
191 groups, but the results of matching against those regexes are.
192 -j JOBS --jobs JOBS
194 Specify the number of concurrent node collections that should be
195 run.
196 If the number of nodes enumerated exceeds the number of JOBS,
198 then sos collect will start collecting from the first X number
199 of nodes and then continue to iterate through the remaining
200 nodes as sosreport collection finishes.
201 Defaults to 4.
203 --nopasswd-sudo
205 Use this option when connecting as a non-root user that has
206 passwordless sudo configured.
207 If this option is omitted and a bogus sudo password is supplied,
209 collection of sosreports may exhibit unexpected behavior and/or
210 fail entirely.
211 -k PLUGIN_OPTION, --plugin-option PLUGIN_OPTION
213 Sosreport option. Set a plugin option to a particular value.
214 This takes the form of plugin_name.option_name=value.
215 Example: To enable the kubernetes "all" option in sosreport use
217 -k kubernetes.all=on.
218 --label LABEL
220 Specify a label to be added to the archive names. This label
221 will be applied to both the sos collect archive and the sosre‐
222 port archives.
223 If a cluster sets a default label, the user-provided label will
225 be appended to that cluster default.
226 -n SKIP_PLUGINS, --skip-plugins SKIP_PLUGINS
228 Sosreport option. Disable (skip) a particular plugin that would
229 otherwise run. This is useful if a particular plugin is prone
230 to hanging for one reason or another.
231 This option supports providing a comma-delimited list of plug‐
233 ins.
234 --nodes NODES
236 Provide a comma-delimited list of nodes to collect sosreports
237 from, or a regex string to be used to compare discovered node
238 names against. If using a regex, only nodes matching the regex
239 will be used - i.e. it can be used as a whitelist but not a
240 blacklist.
241 This option can be handed multiple regex strings separated by
243 commas. Additionally, both whole node names/addresses and regex
244 strings may be provided at the same time.
245 --no-pkg-check
247 Do not perform package checks. Most cluster profiles check
248 against installed packages to determine if the cluster profile
249 should be applied or not.
250 Use this with --cluster-type if there are rpm or apt issues on
252 the master/local node.
253 --no-local
255 Do not collect a sosreport from the local system.
256 If --master is not supplied, it is assumed that the host running
258 sosreport is part of the cluster that is to be collected. Use
259 this option to skip collection of a local sosreport.
260 This option is NOT needed if --master is provided.
262 --master MASTER
264 Specify a master node for the cluster.
265 If provided, then sos collect will check the master node, not
267 localhost, for determining the type of cluster in use.
268 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
270 Sosreport option. Run ONLY the plugins listed.
271 Note that a cluster profile will NOT override this option. This
273 may cause the sosreports generated to not contain the relevant
274 output for a given type of cluster.
275 This option supports providing a comma-delimited list of plug‐
277 ins.
278 --password
280 Specifying this option will cause sos collect to prompt the user
281 for an SSH password that will be used to connect to all nodes.
282 If you have differing passwords for the same user across cluster
284 nodes, you should ideally deploy SSH keys, but the --pass‐
285 word-per-node option is also available.
286 --password-per-node
288 When using this option, sos collect will prompt the user for the
289 SSH password for each node that will have an sosreport collected
290 from it individually before attempting to connect to the nodes.
291 --preset PRESET
293 Specify a sos preset to use, note that this requires sos-3.6 or
294 later to be installed on the node. The given preset must also
295 exist on the remote node - local presets are not used.
296 If --preset is specified and a given node either does not have
298 that preset defined, or has a version of sos prior to 3.6, this
299 option is ignored for that node.
300 -p SSH_PORT, --ssh-port SSH_PORT
302 Specify SSH port for all nodes. Use this if SSH runs on any port
303 other than 22.
304 --skip-commands COMMANDS
306 A comma delimited list of commands to skip execution of, but
307 still allowing the rest of the plugin that calls the command to
308 run. This will generally need to be some form of UNIX shell-
309 style wildcard matching. For example, using a value of hostname
310 will skip only that single command, while using hostname* will
311 skip all commands with names that begin with the string "host‐
312 name".
313 --skip-files FILES
315 A comma delimited list of files or filepath wildcard matches to
316 skip collection of. Values may either be exact filepaths or
317 paths using UNIX shell-style wildcards, for example /etc/sos/*.
318 --ssh-user SSH_USER
320 Specify an SSH user for sos collect to connect to nodes with.
321 Default is root.
322 sos collect will prompt for a sudo password for non-root users.
324 -s SYSROOT, --sysroot SYSROOT
326 Sosreport option. Specify an alternate root file system path.
327 --sos-cmd SOS_CMD
329 Define all options that sosreport should be run with on the
330 nodes. This will override any other commandline options as well
331 as any options specified by a cluster profile.
332 The sosreport command will execute as 'sosreport --batch
334 SOS_CMD'. The BATCH option cannot be removed from the sosreport
335 command as it is required to run sosreport non-interactively for
336 sos collect to function.
337 -t THREADS --threads THREADS
339 Report option. Specify the number of collection threads to run.
340 The report process on each node will run THREADS number of plug‐
342 ins concurrently during the collection process.
343 Defaults to 4.
345 --timeout TIMEOUT
347 Timeout for sosreport generation on each node, in seconds.
348 Note that sosreports are collected in parallel, so you can ap‐
350 proximate the total runtime of sos collect via timeout*(number
351 of nodes/jobs).
352 Default is 180 seconds.
354 --tmp-dir TMP_DIR
356 Specify a temporary directory to save sos archives to. By de‐
357 fault one will be created in /tmp and then removed after sos
358 collect has finished running.
359 This is NOT the same as specifying a temporary directory for
361 sosreport on the remote nodes.
362 -v --verbose
364 Print debug information to screen.
365 --verfiy
367 Sosreport option. Passes the "--verify" option to sosreport on
368 the nodes which causes sosreport to validate plugin-specific
369 data during collection.
370 Note that this option may considerably extend the time it takes
372 sosreport to run on the nodes. Consider increasing --timeout
373 when using this option.
374 -z COMPRESSION, --compression-type COMPRESSION
376 Sosreport option. Override the default compression type.
377
380 sos(1) sos-report(1)
381
384 Jake Hunsaker <jhunsake@redhat.com>
385April 2020 1 sos(collect)