1SOS(REPORT) SOS(REPORT)
2
6 sos report - Collect and package diagnostic and support data
7
9 sos report
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 [--estimate-only] [--label label] [--case-id id]
22 [--threads threads]
23 [--plugin-timeout TIMEOUT]
24 [--cmd-timeout TIMEOUT]
25 [--namespaces NAMESPACES]
26 [--container-runtime RUNTIME]
27 [-s|--sysroot SYSROOT]
28 [-c|--chroot {auto|always|never}
29 [--tmp-dir directory]
30 [-p|--profile profile-name]
31 [--list-profiles]
32 [--verify]
33 [--log-size]
34 [--all-logs]
35 [--since YYYYMMDD[HHMMSS]]
36 [--skip-commands commands]
37 [--skip-files files]
38 [--allow-system-changes]
39 [-z|--compression-type method]
40 [--encrypt-key KEY]
41 [--encrypt-pass PASS]
42 [--upload] [--upload-url url] [--upload-user user]
43 [--upload-directory dir] [--upload-pass pass]
44 [--upload-no-ssl-verify] [--upload-method]
45 [--upload-protocol protocol]
46 [--experimental]
47 [-h|--help]
48
51 report is an sos subcommand that generates an archive of configuration
52 and diagnostic information from the running system. The archive may be
53 stored locally or centrally for recording or tracking purposes or may
54 be sent to technical support representatives, developers or system ad‐
55 ministrators to assist with technical fault-finding and debugging.
56 Sos is modular in design and is able to collect data from a wide range
58 of subsystems and packages that may be installed. An HTML report summa‐
59 rizing the collected information is optionally generated and stored
60 within the archive.
61
63 -l, --list-plugins
64 List all available plugins and their options. Plug-ins that
65 would not be enabled by the current configuration are listed
66 separately.
67 -n, --skip-plugins PLUGNAME[,PLUGNAME]
69 Disable the specified plugin(s). Multiple plug-ins may be speci‐
70 fied by repeating the option or as a comma-separated list.
71 -e, --enable-plugins PLUGNAME[,PLUGNAME]
73 Enable the specified plugin(s) that would otherwise be disabled.
74 Multiple plugins may be specified by repeating the option or as
75 a comma-separated list.
76 Note that if using -p, --profile this option will not enable
78 further plugins. Use -o, --only-plugins to extend the list of
79 plugins enabled by profiles.
80 -o, --only-plugins PLUGNAME[,PLUGNAME]
83 Enable the specified plugin(s) only (all other plugins should be
84 disabled). Multiple plugins may be specified by repeating the
85 option or as a comma-separated list.
86 -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE]
88 Specify plug-in options. The option PLUGOPT is enabled, or set
89 to the specified value in the plug-in PLUGNAME.
90 -a, --alloptions
92 Set all boolean options to True for all enabled plug-ins.
93 -v, --verbose
95 Increase logging verbosity. May be specified multiple times to
96 enable additional debugging messages.
97 -q, --quiet
99 Only log fatal errors to stderr.
100 --no-report
102 Disable HTML report writing.
103 --config-file CONFIG
105 Specify alternate configuration file.
106 --no-postproc
108 Disable postprocessing globally for all plugins. This will mean
109 data is not obfuscated/sanitized from the archive during collec‐
110 tion.
111 Note that this means data such as password, SSH keys, certifi‐
113 cates, etc... will be collected in plain text.
114 To selectively disable postprocessing on a per-plugin basis, use
116 the 'postproc' plugin option available to all plugins, e.g. '-k
117 podman.postproc=off'.
118 --preset PRESET
120 Specify an existing preset to use for sos options.
121 Presets are pre-configured sets of options for both sos and sos
123 plugins. For example a preset may enable a certain set of plug‐
124 ins, disable others, or enable specific plugin options. They may
125 also specify sos options such as log-size or package verifica‐
126 tion.
127 User defined presets are saved under /var/lib/sos/presets as
129 JSON-formatted files.
130 --add-preset ADD_PRESET [options]
132 Add a preset with name ADD_PRESET that enables [options] when
133 called.
134 For example, 'sos report --add-preset mypreset --log-size=50 -n
136 logs' will enable a user to run 'sos report --preset mypreset'
137 that sets the maximum log size to 50 and disables the logs
138 plugin.
139 Note: to set a description for the preset that is displayed with
141 --list-presets, use the --desc option.
142 Note: to set a behaviour note of the preset, use --note option.
144 Note: The root filesystem, as seen by sos if running within a
146 container, must be writable to save presets using this option.
147 --del-preset DEL_PRESET
149 Deletes the preset with name DEL_PRESET from the filesystem so
150 that it can no longer be used.
151 --list-presets
153 Display a list of available presets and what options they carry.
154 --desc DESCRIPTION
156 When using --add-preset use this option to add a description of
157 the preset that will be displayed when using --list-presets.
158 -s, --sysroot SYSROOT
160 Specify an alternate root file system path. Useful for collect‐
161 ing reports from containers and images.
162 -c, --chroot {auto|always|never}
164 Set the chroot mode. When --sysroot is used commands default to
165 executing with SYSROOT as the root directory (unless disabled by
166 a specific plugin). This can be overridden by setting --chroot
167 to "always" (always chroot) or "never" (always run in the host
168 namespace).
169 --tmp-dir DIRECTORY
171 Specify alternate temporary directory to copy data as well as
172 the compressed report.
173 --list-profiles
175 Display a list of available profiles and the plugins that they
176 enable.
177 -p, --profile, --profiles NAME
179 Only run plugins that correspond to the given profile. Multiple
180 profiles may be specified as a comma-separated list; the set of
181 plugins executed is the union of each of the profile's plugin
182 sets.
183 Note that if there are specific plugins outside of the pro‐
185 file(s) passed to this option that you would also want to en‐
186 able, use -o, --only-plugins to add those plugins to the list.
187 See sos report --list-profiles for a list of currently supported
189 profiles.
190 --verify
192 Instructs plugins to perform plugin-specific verification during
193 data collection. This may include package manager verification,
194 log integrity testing or other plugin defined behaviour. Use of
195 --verify may cause the time taken to generate a report to be
196 considerably longer.
197 --log-size
199 Places a limit on the size of collected logs and output in MiB.
200 Note that this causes sos to capture the last X amount of the
201 file or command output collected.
202 By default, this is set to 25 MiB and applies to all files and
204 command output collected with the exception of journal collec‐
205 tions, which are limited to 100 MiB.
206 Setting this value to 0 removes all size limitations, and any
208 files or commands collected will be collected in their entirety,
209 which may drastically increase the size of the final sos report
210 tarball and the memory usage of sos during collection of com‐
211 mands, such as very large journals that may be several GiB in
212 size.
213 --all-logs
216 Tell plugins to collect all possible log data ignoring any size
217 limits and including logs in non-default locations. This option
218 may significantly increase the size of reports.
219 --since YYYYMMDD[HHMMSS]
221 Limits the collection of log archives to those newer than this
222 date. A log archive is any file not found in /etc, that has ei‐
223 ther a numeric or a compression-type file extension for example
224 ".zip". ".1", ".gz" etc.). This also affects --all-logs. The
225 date string will be padded with zeros if HHMMSS is not speci‐
226 fied.
227 --skip-commands COMMANDS
229 A comma delimited list of commands to skip execution of, but
230 still allowing the rest of the plugin that calls the command to
231 run. This will generally need to be some form of UNIX shell-
232 style wildcard matching. For example, using a value of hostname
233 will skip only that single command, while using hostname* will
234 skip all commands with names that begin with the string "host‐
235 name".
236 --skip-files FILES
238 A comma delimited list of files or filepath wildcard matches to
239 skip collection of. Values may either be exact filepaths or
240 paths using UNIX shell-style wildcards, for example /etc/sos/*.
241 --allow-system-changes
243 Run commands even if they can change the system (e.g. load ker‐
244 nel modules).
245 -z, --compression-type METHOD
247 Override the default compression type specified by the active
248 policy.
249 --encrypt-key KEY
251 Encrypts the resulting archive that sosreport produces using
252 GPG. KEY must be an existing key in the user's keyring as GPG
253 does not allow for keyfiles. KEY can be any value accepted by
254 gpg's 'recipient' option.
255 Note that the user running sosreport must match the user owning
257 the keyring from which keys will be obtained. In particular this
258 means that if sudo is used to run sosreport, the keyring must
259 also be set up using sudo (or direct shell access to the ac‐
260 count).
261 Users should be aware that encrypting the final archive will re‐
263 sult in sos using double the amount of temporary disk space -
264 the encrypted archive must be written as a separate, rather than
265 replacement, file within the temp directory that sos writes the
266 archive to. However, since the encrypted archive will be the
267 same size as the original archive, there is no additional space
268 consumption once the temporary directory is removed at the end
269 of execution.
270 This means that only the encrypted archive is present on disk
272 after sos finishes running.
273 If encryption fails for any reason, the original unencrypted ar‐
275 chive is preserved instead.
276 --encrypt-pass PASS
278 The same as --encrypt-key, but use the provided PASS for symmet‐
279 ric encryption rather than key-pair encryption.
280 --batch
282 Generate archive without prompting for interactive input.
283 --name NAME
285 Deprecated. See --label
286 --label LABEL
288 Specify an arbitrary identifier to associate with the archive.
289 Labels will be appended after the system's short hostname and
290 may contain alphanumeric characters.
291 --threads THREADS
293 Specify the number of threads sosreport will use for concur‐
294 rency. Defaults to 4.
295 --plugin-timeout TIMEOUT
297 Specify a timeout in seconds to allow each plugin to run for. A
298 value of 0 means no timeout will be set. A value of -1 is used
299 to indicate the default timeout of 300 seconds.
300 Note that this option sets the timeout for all plugins. If you
302 want to set a timeout for a specific plugin, use the 'timeout'
303 plugin option available to all plugins - e.g. '-k logs.time‐
304 out=600'.
305 The plugin-specific timeout option will override this option.
307 For example, using ´--plugin-timeout=60 -k logs.timeout=600´
308 will set a timeout of 600 seconds for the logs plugin and 60
309 seconds for all other enabled plugins.
310 --cmd-timeout TIMEOUT
312 Specify a timeout limit in seconds for a command execution. Same
313 defaults logic from --plugin-timeout applies here.
314 This option sets the command timeout for all plugins. If you
316 want to set a cmd timeout for a specific plugin, use the 'cmd-
317 timeout' plugin option available to all plugins - e.g. '-k
318 logs.cmd-timeout=600'.
319 Again, the same plugin/global precedence logic as for --plugin-
321 timeout applies here.
322 Note that setting --cmd-timeout (or -k logs.cmd-timeout) high
324 should be followed by increasing the --plugin-timeout equiva‐
325 lent, otherwise the plugin can easily timeout on slow commands
326 execution.
327 --namespaces NAMESPACES
329 For plugins that iterate collections over namespaces that exist
330 on the system, for example the networking plugin collecting `ip`
331 command output for each network namespace, use this option to
332 limit the number of namespaces that will be collected.
333 Use '0' (default) for no limit - all namespaces will be used for
335 collections.
336 Note that specific plugins may provide a similar `namespaces`
338 plugin option. If the plugin option is used, it will override
339 this option.
340 --container-runtime RUNTIME
342 Force the use of the specified RUNTIME as the default runtime
343 that plugins will use to collect data from and about containers
344 and container images. By default, the setting of auto results in
345 the local policy determining what runtime will be the default
346 runtime (in configurations where multiple runtimes are installed
347 and active).
348 If no container runtimes are active, this option is ignored. If
350 there are runtimes active, but not one with a name matching RUN‐
351 TIME, sos will abort.
352 Setting this to none, off, or disabled will cause plugins to NOT
354 leverage any active runtimes for collections. Note that if dis‐
355 abled, plugins specifically for runtimes (e.g. the podman or
356 docker plugins) will still collect general data about the run‐
357 time, but will not inspect existing containers or images.
358 Default: 'auto' (policy determined)
360 --case-id NUMBER
362 Specify a case identifier to associate with the archive. Iden‐
363 tifiers may include alphanumeric characters, commas and periods
364 ('.').
365 --build
367 Do not archive copied data. Causes sosreport to leave an uncom‐
368 pressed archive as a temporary file or directory tree.
369 --debug
371 Enable interactive debugging using the python debugger. Excep‐
372 tions in sos or plug-in code will cause a trap to the pdb shell.
373 --dry-run
375 Execute plugins as normal, but do not collect any file content,
376 command output, or string data from the system. The resulting
377 logs may be used to understand the actions that sos would have
378 taken without the dry run option.
379 --estimate-only
381 Estimate disk space requirements when running sos report. This
382 can be valuable to prevent sosreport working dir to consume all
383 free disk space. No plugin data is available at the end.
384 Plugins will be collected sequentially, size of collected files
386 and commands outputs will be calculated and the plugin files
387 will be immediatelly deleted prior execution of the next plugin.
388 This still can consume whole free disk space, though.
389 Please note, size estimations may not be accurate for highly
391 utilized systems due to changes between an estimate and a real
392 execution. Also some difference between estimation (using `stat`
393 command) and other commands used (i.e. `du`).
394 A rule of thumb is to reserve at least double the estimation.
396 --upload
398 If specified, attempt to upload the resulting archive to a ven‐
399 dor defined location.
400 This option is implied if --upload-url is used.
402 You may be prompted for a username and password if these are not
404 defined by the vendor as well. If these credentials are not pro‐
405 vided, sos will still run and create an archive but will not at‐
406 tempt an automatic upload, instead relying on the end user to
407 upload it as needed.
408 The sosreport archive will still remain on the local filesystem
410 even after a successful upload.
411 Note that depending on the distribution sos is being run on, or
413 the vendor policy detected during execution, there may be depen‐
414 dencies that are not strictly required by the package at instal‐
415 lation time.
416 For example, for HTTPS uploads the python-requests library must
418 be available. If this library is not available, HTTPS uploads
419 will not be attempted.
420 --upload-url URL
422 If a vendor does not provide a default upload location, or if
423 you would like to upload the archive to a different location,
424 specify the address here.
425 A support protocol MUST be specified in this URL. Currently up‐
427 loading is supported for HTTPS, SFTP, and FTP protocols.
428 If your destination server listens on a non-standard port, spec‐
430 ify the listening port in the URL.
431 --upload-user USER
433 If a vendor does not provide a default user for uploading, spec‐
434 ify the username here.
435 If this option is unused and upload is request, and a vendor de‐
437 fault is not set, you will be prompted for one. If --batch is
438 used and this option is omitted, no username will be collected
439 and thus uploads will fail if no vendor default is set.
440 You also have the option of providing this value via the SOSU‐
442 PLOADUSER environment variable. If this variable is set, then no
443 username prompt will occur and --batch may be used provided all
444 other required values (case number, upload password) are pro‐
445 vided.
446 --upload-pass PASS
449 Specify the password to use for authentication with the destina‐
450 tion server.
451 If this option is omitted and upload is requested, you will be
453 prompted for one.
454 If --batch is used, this prompt will not occur, so any uploads
456 are likely to fail unless this option is used.
457 Note that this will result in the plaintext string appearing in
459 `ps` output that may be collected by sos and be in the archive.
460 If a password must be provided by you for uploading, it is
461 strongly recommended to not use --batch and enter the password
462 when prompted rather than using this option.
463 You also have the option of providing this value via the SOSU‐
465 PLOADPASSWORD environment variable. If this variable is set,
466 then no password prompt will occur and --batch may be used pro‐
467 vided all other required values (case number, upload user) are
468 provided.
469 --upload-directory DIR
472 Specify a directory to upload to, if one is not specified by a
473 vendor default location or if your destination server does not
474 allow writes to '/'.
475 --upload-method METHOD
477 Specify the HTTP method to use for uploading to the provided
478 --upload-url. Valid values are 'auto' (default), 'put', or
479 'post'. The use of 'auto' will default to the method required by
480 the policy-default upload location, if one exists.
481 This option has no effect on upload protocols other than HTTPS.
483 --upload-no-ssl-verify
485 Disable SSL verification for HTTPS uploads. This may be used to
486 allow uploading to locations that have self-signed certificates,
487 or certificates that are otherwise untrusted by the local sys‐
488 tem.
489 Default behavior is to perform SSL verification against all up‐
491 load locations.
492 --upload-protocol PROTO
494 Manually specify the protocol to use for uploading to the target
495 upload-url.
496 Normally this is determined via the upload address, assuming
498 that the protocol is part of the address provided, e.g.
499 'https://example.com'. By using this option, sos will skip the
500 protocol check and use the method defined for the specified
501 PROTO.
502 For RHEL systems, setting this option to sftp will skip the ini‐
504 tial attempt to upload to the Red Hat Customer Portal, and only
505 attempt an upload to Red Hat's SFTP server, which is typically
506 used as a fallback target.
507 Valid values for PROTO are: 'auto' (default), 'https', 'ftp',
509 'sftp'.
510 --experimental
512 Enable plugins marked as experimental. Experimental plugins may
513 not have been tested for this port or may still be under active
514 development.
515 --help Display usage message.
517
519 sos(1) sos-clean(1) sos-collect(1) sos.conf(5)
520
523 Jake Hunsaker <jhunsake@redhat.com>
524
526 See AUTHORS file in the package documentation.
527
529 Translations are handled by transifex (https://fedorahosted.org/transifex/)
530Mon Mar 25 2013 1 SOS(REPORT)