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 [--label label] [--case-id id]
22 [--threads threads]
23 [--plugin-timeout TIMEOUT]
24 [--cmd-timeout TIMEOUT]
25 [--namespaces NAMESPACES]
26 [-s|--sysroot SYSROOT]
27 [-c|--chroot {auto|always|never}
28 [--tmp-dir directory]
29 [-p|--profile profile-name]
30 [--list-profiles]
31 [--verify]
32 [--log-size]
33 [--all-logs]
34 [--since YYYYMMDD[HHMMSS]]
35 [--skip-commands commands]
36 [--skip-files files]
37 [--allow-system-changes]
38 [-z|--compression-type method]
39 [--encrypt-key KEY]
40 [--encrypt-pass PASS]
41 [--upload] [--upload-url url] [--upload-user user]
42 [--upload-directory dir] [--upload-pass pass]
43 [--upload-no-ssl-verify] [--upload-method]
44 [--upload-protocol protocol]
45 [--experimental]
46 [-h|--help]
47
50 report is an sos subcommand that generates an archive of configuration
51 and diagnostic information from the running system. The archive may be
52 stored locally or centrally for recording or tracking purposes or may
53 be sent to technical support representatives, developers or system ad‐
54 ministrators to assist with technical fault-finding and debugging.
55 Sos is modular in design and is able to collect data from a wide range
57 of subsystems and packages that may be installed. An HTML report summa‐
58 rizing the collected information is optionally generated and stored
59 within the archive.
60
62 -l, --list-plugins
63 List all available plugins and their options. Plug-ins that
64 would not be enabled by the current configuration are listed
65 separately.
66 -n, --skip-plugins PLUGNAME[,PLUGNAME]
68 Disable the specified plugin(s). Multiple plug-ins may be speci‐
69 fied by repeating the option or as a comma-separated list.
70 -e, --enable-plugins PLUGNAME[,PLUGNAME]
72 Enable the specified plugin(s) that would otherwise be disabled.
73 Multiple plugins may be specified by repeating the option or as
74 a comma-separated list.
75 Note that if using -p, --profile this option will not enable
77 further plugins. Use -o, --only-plugins to extend the list of
78 plugins enabled by profiles.
79 -o, --only-plugins PLUGNAME[,PLUGNAME]
82 Enable the specified plugin(s) only (all other plugins should be
83 disabled). Multiple plugins may be specified by repeating the
84 option or as a comma-separated list.
85 -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE]
87 Specify plug-in options. The option PLUGOPT is enabled, or set
88 to the specified value in the plug-in PLUGNAME.
89 -a, --alloptions
91 Set all boolean options to True for all enabled plug-ins.
92 -v, --verbose
94 Increase logging verbosity. May be specified multiple times to
95 enable additional debugging messages.
96 -q, --quiet
98 Only log fatal errors to stderr.
99 --no-report
101 Disable HTML report writing.
102 --config-file CONFIG
104 Specify alternate configuration file.
105 --no-postproc
107 Disable postprocessing globally for all plugins. This will mean
108 data is not obfuscated/sanitized from the archive during collec‐
109 tion.
110 Note that this means data such as password, SSH keys, certifi‐
112 cates, etc... will be collected in plain text.
113 To selectively disable postprocessing on a per-plugin basis, use
115 the 'postproc' plugin option available to all plugins, e.g. '-k
116 podman.postproc=off'.
117 --preset PRESET
119 Specify an existing preset to use for sos options.
120 Presets are pre-configured sets of options for both sos and sos
122 plugins. For example a preset may enable a certain set of plug‐
123 ins, disable others, or enable specific plugin options. They may
124 also specify sos options such as log-size or package verifica‐
125 tion.
126 User defined presets are saved under /var/lib/sos/presets as
128 JSON-formatted files.
129 --add-preset ADD_PRESET [options]
131 Add a preset with name ADD_PRESET that enables [options] when
132 called.
133 For example, 'sos report --add-preset mypreset --log-size=50 -n
135 logs' will enable a user to run 'sos report --preset mypreset'
136 that sets the maximum log size to 50 and disables the logs
137 plugin.
138 Note: to set a description for the preset that is displayed with
140 --list-presets, use the --desc option.
141 Note: to set a behaviour note of the preset, use --note option.
143 Note: The root filesystem, as seen by sos if running within a
145 container, must be writable to save presets using this option.
146 --del-preset DEL_PRESET
148 Deletes the preset with name DEL_PRESET from the filesystem so
149 that it can no longer be used.
150 --list-presets
152 Display a list of available presets and what options they carry.
153 --desc DESCRIPTION
155 When using --add-preset use this option to add a description of
156 the preset that will be displayed when using --list-presets.
157 -s, --sysroot SYSROOT
159 Specify an alternate root file system path. Useful for collect‐
160 ing reports from containers and images.
161 -c, --chroot {auto|always|never}
163 Set the chroot mode. When --sysroot is used commands default to
164 executing with SYSROOT as the root directory (unless disabled by
165 a specific plugin). This can be overridden by setting --chroot
166 to "always" (always chroot) or "never" (always run in the host
167 namespace).
168 --tmp-dir DIRECTORY
170 Specify alternate temporary directory to copy data as well as
171 the compressed report.
172 --list-profiles
174 Display a list of available profiles and the plugins that they
175 enable.
176 -p, --profile, --profiles NAME
178 Only run plugins that correspond to the given profile. Multiple
179 profiles may be specified as a comma-separated list; the set of
180 plugins executed is the union of each of the profile's plugin
181 sets.
182 Note that if there are specific plugins outside of the pro‐
184 file(s) passed to this option that you would also want to en‐
185 able, use -o, --only-plugins to add those plugins to the list.
186 See sos report --list-profiles for a list of currently supported
188 profiles.
189 --verify
191 Instructs plugins to perform plugin-specific verification during
192 data collection. This may include package manager verification,
193 log integrity testing or other plugin defined behaviour. Use of
194 --verify may cause the time taken to generate a report to be
195 considerably longer.
196 --log-size
198 Places a limit on the size of collected logs and output in MiB.
199 Note that this causes sos to capture the last X amount of the
200 file or command output collected.
201 By default, this is set to 25 MiB and applies to all files and
203 command output collected with the exception of journal collec‐
204 tions, which are limited to 100 MiB.
205 Setting this value to 0 removes all size limitations, and any
207 files or commands collected will be collected in their entirety,
208 which may drastically increase the size of the final sos report
209 tarball and the memory usage of sos during collection of com‐
210 mands, such as very large journals that may be several GiB in
211 size.
212 --all-logs
215 Tell plugins to collect all possible log data ignoring any size
216 limits and including logs in non-default locations. This option
217 may significantly increase the size of reports.
218 --since YYYYMMDD[HHMMSS]
220 Limits the collection of log archives to those newer than this
221 date. A log archive is any file not found in /etc, that has ei‐
222 ther a numeric or a compression-type file extension for example
223 ".zip". ".1", ".gz" etc.). This also affects --all-logs. The
224 date string will be padded with zeros if HHMMSS is not speci‐
225 fied.
226 --skip-commands COMMANDS
228 A comma delimited list of commands to skip execution of, but
229 still allowing the rest of the plugin that calls the command to
230 run. This will generally need to be some form of UNIX shell-
231 style wildcard matching. For example, using a value of hostname
232 will skip only that single command, while using hostname* will
233 skip all commands with names that begin with the string "host‐
234 name".
235 --skip-files FILES
237 A comma delimited list of files or filepath wildcard matches to
238 skip collection of. Values may either be exact filepaths or
239 paths using UNIX shell-style wildcards, for example /etc/sos/*.
240 --allow-system-changes
242 Run commands even if they can change the system (e.g. load ker‐
243 nel modules).
244 -z, --compression-type METHOD
246 Override the default compression type specified by the active
247 policy.
248 --encrypt-key KEY
250 Encrypts the resulting archive that sosreport produces using
251 GPG. KEY must be an existing key in the user's keyring as GPG
252 does not allow for keyfiles. KEY can be any value accepted by
253 gpg's 'recipient' option.
254 Note that the user running sosreport must match the user owning
256 the keyring from which keys will be obtained. In particular this
257 means that if sudo is used to run sosreport, the keyring must
258 also be set up using sudo (or direct shell access to the ac‐
259 count).
260 Users should be aware that encrypting the final archive will re‐
262 sult in sos using double the amount of temporary disk space -
263 the encrypted archive must be written as a separate, rather than
264 replacement, file within the temp directory that sos writes the
265 archive to. However, since the encrypted archive will be the
266 same size as the original archive, there is no additional space
267 consumption once the temporary directory is removed at the end
268 of execution.
269 This means that only the encrypted archive is present on disk
271 after sos finishes running.
272 If encryption fails for any reason, the original unencrypted ar‐
274 chive is preserved instead.
275 --encrypt-pass PASS
277 The same as --encrypt-key, but use the provided PASS for symmet‐
278 ric encryption rather than key-pair encryption.
279 --batch
281 Generate archive without prompting for interactive input.
282 --name NAME
284 Deprecated. See --label
285 --label LABEL
287 Specify an arbitrary identifier to associate with the archive.
288 Labels will be appended after the system's short hostname and
289 may contain alphanumeric characters.
290 --threads THREADS
292 Specify the number of threads sosreport will use for concur‐
293 rency. Defaults to 4.
294 --plugin-timeout TIMEOUT
296 Specify a timeout in seconds to allow each plugin to run for. A
297 value of 0 means no timeout will be set. A value of -1 is used
298 to indicate the default timeout of 300 seconds.
299 Note that this option sets the timeout for all plugins. If you
301 want to set a timeout for a specific plugin, use the 'timeout'
302 plugin option available to all plugins - e.g. '-k logs.time‐
303 out=600'.
304 The plugin-specific timeout option will override this option.
306 For example, using ´--plugin-timeout=60 -k logs.timeout=600´
307 will set a timeout of 600 seconds for the logs plugin and 60
308 seconds for all other enabled plugins.
309 --cmd-timeout TIMEOUT
311 Specify a timeout limit in seconds for a command execution. Same
312 defaults logic from --plugin-timeout applies here.
313 This option sets the command timeout for all plugins. If you
315 want to set a cmd timeout for a specific plugin, use the 'cmd-
316 timeout' plugin option available to all plugins - e.g. '-k
317 logs.cmd-timeout=600'.
318 Again, the same plugin/global precedence logic as for --plugin-
320 timeout applies here.
321 Note that setting --cmd-timeout (or -k logs.cmd-timeout) high
323 should be followed by increasing the --plugin-timeout equiva‐
324 lent, otherwise the plugin can easily timeout on slow commands
325 execution.
326 --namespaces NAMESPACES
328 For plugins that iterate collections over namespaces that exist
329 on the system, for example the networking plugin collecting `ip`
330 command output for each network namespace, use this option to
331 limit the number of namespaces that will be collected.
332 Use '0' (default) for no limit - all namespaces will be used for
334 collections.
335 Note that specific plugins may provide a similar `namespaces`
337 plugin option. If the plugin option is used, it will override
338 this option. --case-id NUMBER Specify a case identifier to as‐
339 sociate with the archive. Identifiers may include alphanumeric
340 characters, commas and periods ('.').
341 --build
343 Do not archive copied data. Causes sosreport to leave an uncom‐
344 pressed archive as a temporary file or directory tree.
345 --debug
347 Enable interactive debugging using the python debugger. Excep‐
348 tions in sos or plug-in code will cause a trap to the pdb shell.
349 --dry-run
351 Execute plugins as normal, but do not collect any file content,
352 command output, or string data from the system. The resulting
353 logs may be used to understand the actions that sos would have
354 taken without the dry run option.
355 --upload
357 If specified, attempt to upload the resulting archive to a ven‐
358 dor defined location.
359 This option is implied if --upload-url is used.
361 You may be prompted for a username and password if these are not
363 defined by the vendor as well. If these credentials are not pro‐
364 vided, sos will still run and create an archive but will not at‐
365 tempt an automatic upload, instead relying on the end user to
366 upload it as needed.
367 The sosreport archive will still remain on the local filesystem
369 even after a successful upload.
370 Note that depending on the distribution sos is being run on, or
372 the vendor policy detected during execution, there may be depen‐
373 dencies that are not strictly required by the package at instal‐
374 lation time.
375 For example, for HTTPS uploads the python-requests library must
377 be available. If this library is not available, HTTPS uploads
378 will not be attempted.
379 --upload-url URL
381 If a vendor does not provide a default upload location, or if
382 you would like to upload the archive to a different location,
383 specify the address here.
384 A support protocol MUST be specified in this URL. Currently up‐
386 loading is supported for HTTPS, SFTP, and FTP protocols.
387 If your destination server listens on a non-standard port, spec‐
389 ify the listening port in the URL.
390 --upload-user USER
392 If a vendor does not provide a default user for uploading, spec‐
393 ify the username here.
394 If this option is unused and upload is request, and a vendor de‐
396 fault is not set, you will be prompted for one. If --batch is
397 used and this option is omitted, no username will be collected
398 and thus uploads will fail if no vendor default is set.
399 You also have the option of providing this value via the SOSU‐
401 PLOADUSER environment variable. If this variable is set, then no
402 username prompt will occur and --batch may be used provided all
403 other required values (case number, upload password) are pro‐
404 vided.
405 --upload-pass PASS
408 Specify the password to use for authentication with the destina‐
409 tion server.
410 If this option is omitted and upload is requested, you will be
412 prompted for one.
413 If --batch is used, this prompt will not occur, so any uploads
415 are likely to fail unless this option is used.
416 Note that this will result in the plaintext string appearing in
418 `ps` output that may be collected by sos and be in the archive.
419 If a password must be provided by you for uploading, it is
420 strongly recommended to not use --batch and enter the password
421 when prompted rather than using this option.
422 You also have the option of providing this value via the SOSU‐
424 PLOADPASSWORD environment variable. If this variable is set,
425 then no password prompt will occur and --batch may be used pro‐
426 vided all other required values (case number, upload user) are
427 provided.
428 --upload-directory DIR
431 Specify a directory to upload to, if one is not specified by a
432 vendor default location or if your destination server does not
433 allow writes to '/'.
434 --upload-method METHOD
436 Specify the HTTP method to use for uploading to the provided
437 --upload-url. Valid values are 'auto' (default), 'put', or
438 'post'. The use of 'auto' will default to the method required by
439 the policy-default upload location, if one exists.
440 This option has no effect on upload protocols other than HTTPS.
442 --upload-no-ssl-verify
444 Disable SSL verification for HTTPS uploads. This may be used to
445 allow uploading to locations that have self-signed certificates,
446 or certificates that are otherwise untrusted by the local sys‐
447 tem.
448 Default behavior is to perform SSL verification against all up‐
450 load locations.
451 --upload-protocol PROTO
453 Manually specify the protocol to use for uploading to the target
454 upload-url.
455 Normally this is determined via the upload address, assuming
457 that the protocol is part of the address provided, e.g.
458 'https://example.com'. By using this option, sos will skip the
459 protocol check and use the method defined for the specified
460 PROTO.
461 For RHEL systems, setting this option to sftp will skip the ini‐
463 tial attempt to upload to the Red Hat Customer Portal, and only
464 attempt an upload to Red Hat's SFTP server, which is typically
465 used as a fallback target.
466 Valid values for PROTO are: 'auto' (default), 'https', 'ftp',
468 'sftp'.
469 --experimental
471 Enable plugins marked as experimental. Experimental plugins may
472 not have been tested for this port or may still be under active
473 development.
474 --help Display usage message.
476
478 sos(1) sos-clean(1) sos-collect(1) sos.conf(5)
479
482 Jake Hunsaker <jhunsake@redhat.com>
483
485 See AUTHORS file in the package documentation.
486
488 Translations are handled by transifex (https://fedorahosted.org/transifex/)
489Mon Mar 25 2013 1 SOS(REPORT)