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           [--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
48

DESCRIPTION

50       collect  is an sos subcommand to collect sosreports from multiple nodes
51       and package them in a single useful tar archive.
52
53       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
57       Some sosreport options are supported by sos-collect and are passed  di‐
58       rectly to the sosreport command run on each node.
59
60

OPTIONS

62       -a, --alloptions
63              Enables all sosreport options.
64
65              This does NOT enable all sos collect options.
66
67       -b, --become
68              Become  the  root  user  on the remote node when connecting as a
69              non-root user.
70
71       --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
75       --all-logs
76              Sosreport option. Collects all logs regardless of size.
77
78              Default: no
79
80       -c CLUSTER_OPTIONS
81              Specify  options  used  by cluster profiles. The format is 'pro‐
82              file.option_name=value'.
83
84              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
88              Available cluster options can be listed by running 'sos  collect
89              -l'.
90
91       --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
97       --case-id CASE_ID
98              Sosreport option. Specifies a case number identifier.
99
100       --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
106              Setting  --cluster-type skips this step and forcibly sets a par‐
107              ticular profile.
108
109              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
115              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
119       -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
123              This  option  supports providing a comma-delimited list of plug‐
124              ins.
125
126       --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
132              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
138              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
147              This means that only the encrypted archive is  present  on  disk
148              after sos finishes running.
149
150              If encryption fails for any reason, the original unencrypted ar‐
151              chive is preserved instead.
152
153              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
158       --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
162
163       --group GROUP
164              Specify an existing host group definition to use.
165
166              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
170              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
173              If  nodes is defined, sos collect extends the --nodes option, if
174              set, with the nodes or regexes listed in the group.
175
176              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
183       --save-group GROUP
184              Save the results of this run of sos collect to a host group def‐
185              inition.
186
187              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
193       -j JOBS --jobs JOBS
194              Specify the number of concurrent node collections that should be
195              run.
196
197              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
202              Defaults to 4.
203
204       --nopasswd-sudo
205              Use this option when connecting as  a  non-root  user  that  has
206              passwordless sudo configured.
207
208              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
212       -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
216              Example: To enable the kubernetes "all" option in sosreport  use
217              -k kubernetes.all=on.
218
219       --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
224              If  a cluster sets a default label, the user-provided label will
225              be appended to that cluster default.
226
227       -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
232              This option supports providing a comma-delimited list  of  plug‐
233              ins.
234
235       --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
242              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
246       --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
251              Use  this  with --cluster-type if there are rpm or apt issues on
252              the master/local node.
253
254       --no-local
255              Do not collect a sosreport from the local system.
256
257              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
261              This option is NOT needed if --master is provided.
262
263       --master MASTER
264              Specify a master node for the cluster.
265
266              If provided, then sos collect will check the  master  node,  not
267              localhost, for determining the type of cluster in use.
268
269       -o ONLY_PLUGINS, --only-plugins ONLY_PLUGINS
270              Sosreport option. Run ONLY the plugins listed.
271
272              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
276              This  option  supports providing a comma-delimited list of plug‐
277              ins.
278
279       --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
283              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
287       --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
292       --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
297              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
301       -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
305       --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
314       --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
319       --ssh-user SSH_USER
320              Specify an SSH user for sos collect to connect  to  nodes  with.
321              Default is root.
322
323              sos collect will prompt for a sudo password for non-root users.
324
325       -s SYSROOT, --sysroot SYSROOT
326              Sosreport option. Specify an alternate root file system path.
327
328       --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
333              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
338       -t THREADS --threads THREADS
339              Report option. Specify the number of collection threads to run.
340
341              The report process on each node will run THREADS number of plug‐
342              ins concurrently during the collection process.
343
344              Defaults to 4.
345
346       --timeout TIMEOUT
347              Timeout for sosreport generation on each node, in seconds.
348
349              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
353              Default is 180 seconds.
354
355       --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
360              This  is  NOT  the  same as specifying a temporary directory for
361              sosreport on the remote nodes.
362
363       -v --verbose
364              Print debug information to screen.
365
366       --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
371              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
375       -z COMPRESSION, --compression-type COMPRESSION
376              Sosreport option. Override the default compression type.
377
378

SEE ALSO

380       sos(1) sos-report(1)
381
382

MAINTAINER

384           Jake Hunsaker <jhunsake@redhat.com>
385
386
387
388April 2020                             1                          sos(collect)
Impressum