1sos(collect)                                                      sos(collect)
2
3
4

NAME

6       sos collect - Collect sosreports from multiple (cluster) nodes
7

SYNOPSIS

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
46

DESCRIPTION

48       collect  is an sos subcommand to collect sosreports from multiple nodes
49       and package them in a single useful tar archive.
50
51       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
55       Some sosreport options are supported  by  sos-collect  and  are  passed
56       directly to the sosreport command run on each node.
57
58

OPTIONS

60       -a, --alloptions
61              Enables all sosreport options.
62
63              This does NOT enable all sos collect options.
64
65       -b, --become
66              Become  the  root  user  on the remote node when connecting as a
67              non-root user.
68
69       --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
73       --all-logs
74              Sosreport option. Collects all logs regardless of size.
75
76              Default: no
77
78       -c CLUSTER_OPTIONS
79              Specify  options  used  by cluster profiles. The format is 'pro‐
80              file.option_name=value'.
81
82              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
86              Available cluster options can be listed by running 'sos  collect
87              -l'.
88
89       --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
95       --case-id CASE_ID
96              Sosreport option. Specifies a case number identifier.
97
98       --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
104              Setting  --cluster-type skips this step and forcibly sets a par‐
105              ticular profile.
106
107              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
113              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
117       -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
121              This  option  supports providing a comma-delimited list of plug‐
122              ins.
123
124       --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
130              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
136              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
145              This means that only the encrypted archive is  present  on  disk
146              after sos finishes running.
147
148              If encryption fails for any reason, the original unencrypted ar‐
149              chive is preserved instead.
150
151              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
156       --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
160
161       --group GROUP
162              Specify an existing host group definition to use.
163
164              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
168              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
171              If  nodes is defined, sos collect extends the --nodes option, if
172              set, with the nodes or regexes listed in the group.
173
174              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
181       --save-group GROUP
182              Save the results of this run of sos collect to a host group def‐
183              inition.
184
185              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
191       -j JOBS --jobs JOBS
192              Specify the number of concurrent node collections that should be
193              run.
194
195              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
200              Defaults to 4.
201
202       --nopasswd-sudo
203              Use this option when connecting as  a  non-root  user  that  has
204              passwordless sudo configured.
205
206              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
210       -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
214              Example: To enable the kubernetes "all" option in sosreport  use
215              -k kubernetes.all=on.
216
217       --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
222              If  a cluster sets a default label, the user-provided label will
223              be appended to that cluster default.
224
225       -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
230              This option supports providing a comma-delimited list  of  plug‐
231              ins.
232
233       --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
240              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
244       --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
249              Use  this  with --cluster-type if there are rpm or apt issues on
250              the master/local node.
251
252       --no-local
253              Do not collect a sosreport from the local system.
254
255              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
259              This option is NOT needed if --master is provided.
260
261       --master MASTER
262              Specify a master node for the cluster.
263
264              If provided, then sos collect will check the  master  node,  not
265              localhost, for determining the type of cluster in use.
266
267       -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
268              Sosreport option. Run ONLY the plugins listed.
269
270              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
274              This  option  supports providing a comma-delimited list of plug‐
275              ins.
276
277       --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
281              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
285       --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
290       --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
295              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
299       -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
303       --ssh-user SSH_USER
304              Specify an SSH user for sos collect to connect  to  nodes  with.
305              Default is root.
306
307              sos collect will prompt for a sudo password for non-root users.
308
309       -s SYSROOT, --sysroot SYSROOT
310              Sosreport option. Specify an alternate root file system path.
311
312       --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
317              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
322       -t THREADS --threads THREADS
323              Report option. Specify the number of collection threads to run.
324
325              The report process on each node will run THREADS number of plug‐
326              ins concurrently during the collection process.
327
328              Defaults to 4.
329
330       --timeout TIMEOUT
331              Timeout for sosreport generation on each node, in seconds.
332
333              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
337              Default is 180 seconds.
338
339       --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
344              This  is  NOT  the  same as specifying a temporary directory for
345              sosreport on the remote nodes.
346
347       -v --verbose
348              Print debug information to screen.
349
350       --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
355              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
359       -z COMPRESSION, --compression-type COMPRESSION
360              Sosreport option. Override the default compression type.
361
362

SEE ALSO

364       sos(1) sos-report(1)
365
366

MAINTAINER

368           Jake Hunsaker <jhunsake@redhat.com>
369
370
371
372April 2020                             1                          sos(collect)
Impressum