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 [-s|--sysroot SYSROOT]
37 [--ssh-user SSH_USER]
38 [--sos-cmd SOS_CMD]
39 [-t|--threads THREADS]
40 [--timeout TIMEOUT]
41 [--tmp-dir TMP_DIR]
42 [-v|--verbose]
43 [--verify]
44 [-z|--compression-type COMPRESSION_TYPE]
45
48 collect is an sos subcommand to collect sosreports from multiple nodes
49 and package them in a single useful tar archive.
50 sos collect can be run either on a workstation that has SSH key authen‐
52 tication setup for the nodes in a given cluster, or from a "master"
53 node in a cluster that has SSH keys configured for the other nodes.
54 Some sosreport options are supported by sos-collect and are passed
56 directly to the sosreport command run on each node.
57
60 -a, --alloptions
61 Enables all sosreport options.
62 This does NOT enable all sos collect options.
64 -b, --become
66 Become the root user on the remote node when connecting as a
67 non-root user.
68 --batch
70 Run in non-interactive mode. This will skip prompts for user
71 input, with the exception of a prompt for the SSH password.
72 --all-logs
74 Sosreport option. Collects all logs regardless of size.
75 Default: no
77 -c CLUSTER_OPTIONS
79 Specify options used by cluster profiles. The format is 'pro‐
80 file.option_name=value'.
81 For example, for the ovirt plugin if you wanted to restrict node
83 enumeration to a specific cluster you would use '-c ovirt.clus‐
84 ter=example_cluster'.
85 Available cluster options can be listed by running 'sos collect
87 -l'.
88 --chroot CHROOT
90 Sosreport option. Set the chroot mode. When --sysroot is used
91 commands default to executing with SYSROOT as the root direc‐
92 tory. This can be overridden by setting --chroot to "always"
93 (always chroot) or "never" (always run in the host namespace).
94 --case-id CASE_ID
96 Sosreport option. Specifies a case number identifier.
97 --cluster-type CLUSTER_TYPE
99 When run by itself, sos collect will attempt to identify the
100 type of cluster at play. This is done by checking package or
101 configuration information against the localhost, or the master
102 node if "--master" is supplied.
103 Setting --cluster-type skips this step and forcibly sets a par‐
105 ticular profile.
106 Using a value of none or jbon (just a bunch of nodes) will
108 effectively disable all cluster-specific checks, and cause sos
109 collect to only use the nodes specified by the --nodes option.
110 Note that in this scenario, regex string(s) for node names will
111 be ignored.
112 Example: sos collect --cluster-type=kubernetes will force the
114 kubernetes profile to be run, and thus set sosreport options and
115 attempt to determine a list of nodes using that profile.
116 -e ENABLE_PLUGINS, --enable-plugins ENABLE_PLUGINS
118 Sosreport option. Use this to enable a plugin that would other‐
119 wise not be run.
120 This option supports providing a comma-delimited list of plug‐
122 ins.
123 --encrypt-key KEY
125 Encrypts the resulting archive that sos collect produces using
126 GPG. KEY must be an existing key in the user's keyring as GPG
127 does not allow for keyfiles. KEY can be any value accepted by
128 gpg's 'recipient' option.
129 Note that the user running sos collect must match the user own‐
131 ing the keyring from which keys will be obtained. In particular
132 this means that if sudo is used to run sos collect, the keyring
133 must also be set up using sudo (or direct shell access to the
134 account).
135 Users should be aware that encrypting the final archive will
137 result in sos using double the amount of temporary disk space -
138 the encrypted archive must be written as a separate, rather than
139 replacement, file within the temp directory that sos writes the
140 archive to. However, since the encrypted archive will be the
141 same size as the original archive, there is no additional space
142 consumption once the temporary directory is removed at the end
143 of execution.
144 This means that only the encrypted archive is present on disk
146 after sos finishes running.
147 If encryption fails for any reason, the original unencrypted ar‐
149 chive is preserved instead.
150 IMPORTANT: As of this version of sos collect, only the final ar‐
152 chive on the local machine running sos collect will be
153 encrypted. The individual sos reports that are collected on the
154 nodes will be collected unencrypted.
155 --encrypt-pass PASS
157 The same as --encrypt-key, but use the provided PASS for symmet‐
158 ric encryption rather than key-pair encryption.
159 --group GROUP
162 Specify an existing host group definition to use.
163 Host groups are pre-defined settings for the cluster-type, mas‐
165 ter, and nodes options saved in JSON-formatted files under
166 /var/lib/sos collect/<GROUP>.
167 If cluster_type and/or master are set in the group, sos collect
169 behaves as if these values were specified on the command-line.
170 If nodes is defined, sos collect extends the --nodes option, if
172 set, with the nodes or regexes listed in the group.
173 Note that sos collect will only write group definitions to
175 /var/lib/sos collect/ however the GROUP value may be a filename
176 for any group definitions that exist outside of the default
177 location. If you are manually writing these files, use the value
178 null when a python NoneType is expected. Caveat: use string
179 'none' if setting cluster_type to none.
180 --save-group GROUP
182 Save the results of this run of sos collect to a host group def‐
183 inition.
184 sos-colllector will write a JSON-formatted file with name GROUP
186 to /var/lib/sos collect/ with the settings for cluster-type,
187 master, and the node list as discovered by cluster enumeration.
188 Note that this means regexes are not directly saved to host
189 groups, but the results of matching against those regexes are.
190 -j JOBS --jobs JOBS
192 Specify the number of concurrent node collections that should be
193 run.
194 If the number of nodes enumerated exceeds the number of JOBS,
196 then sos collect will start collecting from the first X number
197 of nodes and then continue to iterate through the remaining
198 nodes as sosreport collection finishes.
199 Defaults to 4.
201 --nopasswd-sudo
203 Use this option when connecting as a non-root user that has
204 passwordless sudo configured.
205 If this option is omitted and a bogus sudo password is supplied,
207 collection of sosreports may exhibit unexpected behavior and/or
208 fail entirely.
209 -k PLUGIN_OPTION, --plugin-option PLUGIN_OPTION
211 Sosreport option. Set a plugin option to a particular value.
212 This takes the form of plugin_name.option_name=value.
213 Example: To enable the kubernetes "all" option in sosreport use
215 -k kubernetes.all=on.
216 --label LABEL
218 Specify a label to be added to the archive names. This label
219 will be applied to both the sos collect archive and the sosre‐
220 port archives.
221 If a cluster sets a default label, the user-provided label will
223 be appended to that cluster default.
224 -n SKIP_PLUGINS, --skip-plugins SKIP_PLUGINS
226 Sosreport option. Disable (skip) a particular plugin that would
227 otherwise run. This is useful if a particular plugin is prone
228 to hanging for one reason or another.
229 This option supports providing a comma-delimited list of plug‐
231 ins.
232 --nodes NODES
234 Provide a comma-delimited list of nodes to collect sosreports
235 from, or a regex string to be used to compare discovered node
236 names against. If using a regex, only nodes matching the regex
237 will be used - i.e. it can be used as a whitelist but not a
238 blacklist.
239 This option can be handed multiple regex strings separated by
241 commas. Additionally, both whole node names/addresses and regex
242 strings may be provided at the same time.
243 --no-pkg-check
245 Do not perform package checks. Most cluster profiles check
246 against installed packages to determine if the cluster profile
247 should be applied or not.
248 Use this with --cluster-type if there are rpm or apt issues on
250 the master/local node.
251 --no-local
253 Do not collect a sosreport from the local system.
254 If --master is not supplied, it is assumed that the host running
256 sosreport is part of the cluster that is to be collected. Use
257 this option to skip collection of a local sosreport.
258 This option is NOT needed if --master is provided.
260 --master MASTER
262 Specify a master node for the cluster.
263 If provided, then sos collect will check the master node, not
265 localhost, for determining the type of cluster in use.
266 -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
268 Sosreport option. Run ONLY the plugins listed.
269 Note that a cluster profile will NOT override this option. This
271 may cause the sosreports generated to not contain the relevant
272 output for a given type of cluster.
273 This option supports providing a comma-delimited list of plug‐
275 ins.
276 --password
278 Specifying this option will cause sos collect to prompt the user
279 for an SSH password that will be used to connect to all nodes.
280 If you have differing passwords for the same user across cluster
282 nodes, you should ideally deploy SSH keys, but the --pass‐
283 word-per-node option is also available.
284 --password-per-node
286 When using this option, sos collect will prompt the user for the
287 SSH password for each node that will have an sosreport collected
288 from it individually before attempting to connect to the nodes.
289 --preset PRESET
291 Specify a sos preset to use, note that this requires sos-3.6 or
292 later to be installed on the node. The given preset must also
293 exist on the remote node - local presets are not used.
294 If --preset is specified and a given node either does not have
296 that preset defined, or has a version of sos prior to 3.6, this
297 option is ignored for that node.
298 -p SSH_PORT, --ssh-port SSH_PORT
300 Specify SSH port for all nodes. Use this if SSH runs on any port
301 other than 22.
302 --ssh-user SSH_USER
304 Specify an SSH user for sos collect to connect to nodes with.
305 Default is root.
306 sos collect will prompt for a sudo password for non-root users.
308 -s SYSROOT, --sysroot SYSROOT
310 Sosreport option. Specify an alternate root file system path.
311 --sos-cmd SOS_CMD
313 Define all options that sosreport should be run with on the
314 nodes. This will override any other commandline options as well
315 as any options specified by a cluster profile.
316 The sosreport command will execute as 'sosreport --batch
318 SOS_CMD'. The BATCH option cannot be removed from the sosreport
319 command as it is required to run sosreport non-interactively for
320 sos collect to function.
321 -t THREADS --threads THREADS
323 Report option. Specify the number of collection threads to run.
324 The report process on each node will run THREADS number of plug‐
326 ins concurrently during the collection process.
327 Defaults to 4.
329 --timeout TIMEOUT
331 Timeout for sosreport generation on each node, in seconds.
332 Note that sosreports are collected in parallel, so you can
334 approximate the total runtime of sos collect via timeout*(number
335 of nodes/jobs).
336 Default is 180 seconds.
338 --tmp-dir TMP_DIR
340 Specify a temporary directory to save sos archives to. By
341 default one will be created in /tmp and then removed after sos
342 collect has finished running.
343 This is NOT the same as specifying a temporary directory for
345 sosreport on the remote nodes.
346 -v --verbose
348 Print debug information to screen.
349 --verfiy
351 Sosreport option. Passes the "--verify" option to sosreport on
352 the nodes which causes sosreport to validate plugin-specific
353 data during collection.
354 Note that this option may considerably extend the time it takes
356 sosreport to run on the nodes. Consider increasing --timeout
357 when using this option.
358 -z COMPRESSION, --compression-type COMPRESSION
360 Sosreport option. Override the default compression type.
361
364 sos(1) sos-report(1)
365
368 Jake Hunsaker <jhunsake@redhat.com>
369April 2020 1 sos(collect)