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