1SOSREPORT(1)                General Commands Manual               SOSREPORT(1)
2
3
4

NAME

6       sosreport - Collect and package diagnostic and support data
7

SYNOPSIS

9       sosreport
10                 [-l|--list-plugins]
11                 [-n|--skip-plugins plugin-names]
12                 [-e|--enable-plugins plugin-names]
13                 [-o|--only-plugins plugin-names]
14                 [-a|--alloptions] [-v|--verbose]
15                 [-k plug.opt|--plugin-option plug.opt]
16                 [--no-report] [--config-file conf]
17                 [--no-postproc]
18                 [--preset preset] [--add-preset add_preset]
19                 [--del-preset del_preset] [--desc description]
20                 [--batch] [--build] [--debug] [--dry-run]
21                 [--label label] [--case-id id] [--ticket-number nr]
22                 [--threads threads]
23                 [--plugin-timeout TIMEOUT]
24                 [-s|--sysroot SYSROOT]
25                 [-c|--chroot {auto|always|never}
26                 [--tmp-dir directory]
27                 [-p|--profile profile-name]
28                 [--list-profiles]
29                 [--verify]
30                 [--log-size]
31                 [--all-logs]
32                 [--since YYYYMMDD[HHMMSS]]
33                 [--allow-system-changes]
34                 [-z|--compression-type method]
35                 [--encrypt-key KEY]
36                 [--encrypt-pass PASS]
37                 [--upload] [--upload-url url] [--upload-user user]
38                 [--upload-directory dir] [--upload-pass pass]
39                 [--experimental]
40                 [-h|--help]
41
42

DESCRIPTION

44       sosreport generates an archive of configuration and diagnostic informa‐
45       tion from the running system. The archive may be stored locally or cen‐
46       trally  for  recording or tracking purposes or may be sent to technical
47       support representatives, developers or system administrators to  assist
48       with technical fault-finding and debugging.
49
50       Sos  is modular in design and is able to collect data from a wide range
51       of subsystems and packages that may be installed. An HTML report summa‐
52       rizing  the  collected  information  is optionally generated and stored
53       within the archive.
54

OPTIONS

56       -l, --list-plugins
57              List all available plugins  and  their  options.  Plug-ins  that
58              would  not  be  enabled  by the current configuration are listed
59              separately.
60
61       -n, --skip-plugins PLUGNAME[,PLUGNAME]
62              Disable the specified plugin(s). Multiple plug-ins may be speci‐
63              fied by repeating the option or as a comma-separated list.
64
65       -e, --enable-plugins PLUGNAME[,PLUGNAME]
66              Enable  the specified plugin(s). Multiple plug-ins may be speci‐
67              fied by repeating the option or as a comma-separated list.
68
69       -o, --only-plugins PLUGNAME[,PLUGNAME]
70              Enable the specified plugin(s) only (all other plugins should be
71              disabled).  Multiple  plugins  may be specified by repeating the
72              option or as a comma-separated list.
73
74       -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE]
75              Specify plug-in options. The option PLUGOPT is enabled,  or  set
76              to the specified value in the plug-in PLUGNAME.
77
78       -a, --alloptions
79              Set all boolean options to True for all enabled plug-ins.
80
81       -v, --verbose
82              Increase  logging  verbosity. May be specified multiple times to
83              enable additional debugging messages.
84
85       -q, --quiet
86              Only log fatal errors to stderr.
87
88       --no-report
89              Disable HTML report writing.
90
91       --config-file CONFIG
92              Specify alternate configuration file.
93
94       --no-postproc
95              Disable postprocessing globally for all plugins. This will  mean
96              data is not obfuscated/sanitized from the archive during collec‐
97              tion.
98
99              Note that this means data such as password, SSH  keys,  certifi‐
100              cates, etc...  will be collected in plain text.
101
102              To selectively disable postprocessing on a per-plugin basis, use
103              the 'postproc' plugin option available to all plugins, e.g.  '-k
104              podman.postproc=off'.
105
106       --preset PRESET
107              Specify an existing preset to use for sos options.
108
109              Presets  are pre-configured sets of options for both sos and sos
110              plugins. For example a preset may enable a certain set of  plug‐
111              ins, disable others, or enable specific plugin options. They may
112              also specify sos options such as log-size or  package  verifica‐
113              tion.
114
115              User  defined  presets  are  saved under /var/lib/sos/presets as
116              JSON-formatted files.
117
118       --add-preset ADD_PRESET [options]
119              Add a preset with name ADD_PRESET that  enables  [options]  when
120              called.
121
122              For  example,  'sosreport --add-preset mypreset --log-size=50 -n
123              logs' will enable a user to run  'sosreport  --preset  mypreset'
124              that sets the maximum log size to 50 and disables the logs plug‐
125              in.
126
127              Note: to set a description for the preset that is displayed with
128              --list-presets, use the --desc option.
129
130              Note: to set a behaviour note of the preset, use --note option.
131
132              Note:  The  root  filesystem, as seen by sos if running within a
133              container, must be writable to save presets using this option.
134
135       --del-preset DEL_PRESET
136              Deletes the preset with name DEL_PRESET from the  filesystem  so
137              that it can no longer be used.
138
139       --list-presets
140              Display a list of available presets and what options they carry.
141
142       --desc DESCRIPTION
143              When  using --add-preset use this option to add a description of
144              the preset that will be displayed when using --list-presets.
145
146       -s, --sysroot SYSROOT
147              Specify an alternate root file system path. Useful for  collect‐
148              ing reports from containers and images.
149
150       -c, --chroot {auto|always|never}
151              Set  the chroot mode. When --sysroot is used commands default to
152              executing with SYSROOT as the root directory (unless disabled by
153              a  specific  plugin). This can be overridden by setting --chroot
154              to "always" (always chroot) or "never" (always run in  the  host
155              namespace).
156
157       --tmp-dir DIRECTORY
158              Specify  alternate  temporary  directory to copy data as well as
159              the compressed report.
160
161       --list-profiles
162              Display a list of available profiles and the plugins  that  they
163              enable.
164
165       -p, --profile NAME
166              Only  run plugins that correspond to the given profile. Multiple
167              profiles may be specified as a comma-separated list; the set  of
168              plugins  executed  is  the union of each of the profile's plugin
169              sets. Currently defined profiles include: boot,  cluster,  desk‐
170              top,  debug, hardware, identity, network, openstack, packageman‐
171              ager, security, services, storage, sysmgmt, system, performance,
172              virt, and webserver.
173
174       --verify
175              Instructs plugins to perform plugin-specific verification during
176              data collection. This may include package manager  verification,
177              log  integrity testing or other plugin defined behaviour. Use of
178              --verify may cause the time taken to generate  a  report  to  be
179              considerably longer.
180
181       --log-size
182              Places  a global limit on the size (in MiB) of any collected set
183              of logs. The limit is applied separately for each  set  of  logs
184              collected by any plugin.
185
186       --all-logs
187              Tell  plugins to collect all possible log data ignoring any size
188              limits and including logs in non-default locations. This  option
189              may significantly increase the size of reports.
190
191       --since YYYYMMDD[HHMMSS]
192              Limits  the  collection of log archives to those newer than this
193              date. A log archive is any file not  found  in  /etc,  that  has
194              either  a numeric or a compression-type file extension for exam‐
195              ple ".zip". ".1", ".gz" etc.).  This  also  affects  --all-logs.
196              The date string will be padded with zeros if HHMMSS is not spec‐
197              ified.
198
199       --allow-system-changes
200              Run commands even if they can change the system (e.g. load  ker‐
201              nel modules).
202
203       -z, --compression-type METHOD
204              Override  the  default  compression type specified by the active
205              policy.
206
207       --encrypt-key KEY
208              Encrypts the resulting archive  that  sosreport  produces  using
209              GPG.  KEY  must  be an existing key in the user's keyring as GPG
210              does not allow for keyfiles.  KEY can be any value  accepted  by
211              gpg's 'recipient' option.
212
213              Note  that the user running sosreport must match the user owning
214              the keyring from which keys will be obtained. In particular this
215              means  that  if  sudo is used to run sosreport, the keyring must
216              also be set up  using  sudo  (or  direct  shell  access  to  the
217              account).
218
219              Users  should  be  aware  that encrypting the final archive will
220              result in sos using double the amount of temporary disk space  -
221              the encrypted archive must be written as a separate, rather than
222              replacement, file within the temp directory that sos writes  the
223              archive  to.  However,  since  the encrypted archive will be the
224              same size as the original archive, there is no additional  space
225              consumption  once  the temporary directory is removed at the end
226              of execution.
227
228              This means that only the encrypted archive is  present  on  disk
229              after sos finishes running.
230
231              If encryption fails for any reason, the original unencrypted ar‐
232              chive is preserved instead.
233
234       --encrypt-pass PASS
235              The same as --encrypt-key, but use the provided PASS for symmet‐
236              ric encryption rather than key-pair encryption.
237
238       --batch
239              Generate archive without prompting for interactive input.
240
241       --name NAME
242              Deprecated. See --label
243
244       --label LABEL
245              Specify  an  arbitrary identifier to associate with the archive.
246              Labels will be appended after the system's  short  hostname  and
247              may contain alphanumeric characters.
248
249       --threads THREADS
250              Specify  the  number  of  threads sosreport will use for concur‐
251              rency. Defaults to 4.
252
253       --plugin-timeout TIMEOUT
254              Specify a timeout in seconds to allow each plugin to run for.  A
255              value of 0 means no timeout will be set.
256
257              Note  that this options sets the timeout for all plugins. If you
258              want to set a timeout for a specific plugin, use  the  'timeout'
259              plugin  option  available  to  all plugins - e.g. '-k logs.time‐
260              out=600'.
261
262              The plugin-specific timeout option will  override  this  option.
263              For  example,  using  ´--plugin-timeout=60  -k logs.timeout=600´
264              will set a timeout of 600 seconds for the  logs  plugin  and  60
265              seconds for all other enabled plugins.
266
267       --case-id NUMBER
268              Specify  a case identifier to associate with the archive.  Iden‐
269              tifiers may include alphanumeric characters, commas and  periods
270              ('.').  Synonymous with --ticket-number.
271
272       --ticket-number NUMBER
273              Specify  a  ticket  number or other identifier to associate with
274              the archive.  Identifiers may include  alphanumeric  characters,
275              commas and periods ('.').  Synonymous with --case-id.
276
277       --build
278              Do  not archive copied data. Causes sosreport to leave an uncom‐
279              pressed archive as a temporary file or directory tree.
280
281       --debug
282              Enable interactive debugging using the python  debugger.  Excep‐
283              tions in sos or plug-in code will cause a trap to the pdb shell.
284
285       --dry-run
286              Execute  plugins as normal, but do not collect any file content,
287              command output, or string data from the  system.  The  resulting
288              logs  may  be used to understand the actions that sos would have
289              taken without the dry run option.
290
291       --upload
292              If specified, attempt to upload the resulting archive to a  ven‐
293              dor defined location.
294
295              This option is implied if --upload-url is used.
296
297              You may be prompted for a username and password if these are not
298              defined by the vendor as well. If these credentials are not pro‐
299              vided,  sos  will  still  run and create an archive but will not
300              attempt an automatic upload, instead relying on the end user  to
301              upload it as needed.
302
303              The  sosreport archive will still remain on the local filesystem
304              even after a successful upload.
305
306              Note that depending on the distribution sos is being run on,  or
307              the vendor policy detected during execution, there may be depen‐
308              dencies that are not strictly required by the package at instal‐
309              lation time.
310
311              For  example, for HTTPS uploads the python-requests library must
312              be available. If this library is not  available,  HTTPS  uploads
313              will not be attempted.
314
315       --upload-url URL
316              If  a  vendor  does not provide a default upload location, or if
317              you would like to upload the archive to  a  different  location,
318              specify the address here.
319
320              A  support  protocol  MUST  be  specified in this URL. Currently
321              uploading is supported for HTTPS, SFTP, and FTP protocols.
322
323              If your destination server listens on a non-standard port, spec‐
324              ify the listening port in the URL.
325
326       --upload-user USER
327              If a vendor does not provide a default user for uploading, spec‐
328              ify the username here.
329
330              If this option is unused and upload is  request,  and  a  vendor
331              default  is not set, you will be prompted for one. If --batch is
332              used and this option is omitted, no username will  be  collected
333              and thus uploads will fail if no vendor default is set.
334
335       --upload-pass PASS
336              Specify the password to use for authentication with the destina‐
337              tion server.
338
339              If this option is omitted and upload is requested, you  will  be
340              prompted for one.
341
342              If  --batch  is used, this prompt will not occur, so any uploads
343              are likely to fail unless this option is used.
344
345              Note that this will result in the plaintext string appearing  in
346              `ps`  output that may be collected by sos and be in the archive.
347              If a password must be provided  by  you  for  uploading,  it  is
348              strongly  recommended  to not use --batch and enter the password
349              when prompted rather than using this option.
350
351       --upload-directory DIR
352              Specify a directory to upload to, if one is not specified  by  a
353              vendor  default  location or if your destination server does not
354              allow writes to '/'.
355
356       --experimental
357              Enable plugins marked as experimental. Experimental plugins  may
358              not  have been tested for this port or may still be under active
359              development.
360
361       --help Display usage message.
362

MAINTAINER

364       Bryn M. Reeves <bmr@redhat.com>
365

AUTHORS & CONTRIBUTORS

367       See AUTHORS file in the package documentation.
368

TRANSLATIONS

370       Translations are handled by transifex (https://fedorahosted.org/transifex/)
371
372
373
374                                Mon Mar 25 2013                   SOSREPORT(1)
Impressum