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