1SOSREPORT(1) General Commands Manual SOSREPORT(1)
2
6 sosreport - Collect and package diagnostic and support data
7
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]
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 [--skip-commands commands]
34 [--skip-files files]
35 [--allow-system-changes]
36 [-z|--compression-type method]
37 [--encrypt-key KEY]
38 [--encrypt-pass PASS]
39 [--upload] [--upload-url url] [--upload-user user]
40 [--upload-directory dir] [--upload-pass pass]
41 [--experimental]
42 [-h|--help]
43
46 sosreport generates an archive of configuration and diagnostic informa‐
47 tion from the running system. The archive may be stored locally or cen‐
48 trally for recording or tracking purposes or may be sent to technical
49 support representatives, developers or system administrators to assist
50 with technical fault-finding and debugging.
51 Sos is modular in design and is able to collect data from a wide range
53 of subsystems and packages that may be installed. An HTML report summa‐
54 rizing the collected information is optionally generated and stored
55 within the archive.
56
58 -l, --list-plugins
59 List all available plugins and their options. Plug-ins that
60 would not be enabled by the current configuration are listed
61 separately.
62 -n, --skip-plugins PLUGNAME[,PLUGNAME]
64 Disable the specified plugin(s). Multiple plug-ins may be speci‐
65 fied by repeating the option or as a comma-separated list.
66 -e, --enable-plugins PLUGNAME[,PLUGNAME]
68 Enable the specified plugin(s). Multiple plug-ins may be speci‐
69 fied by repeating the option or as a comma-separated list.
70 -o, --only-plugins PLUGNAME[,PLUGNAME]
72 Enable the specified plugin(s) only (all other plugins should be
73 disabled). Multiple plugins may be specified by repeating the
74 option or as a comma-separated list.
75 -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE]
77 Specify plug-in options. The option PLUGOPT is enabled, or set
78 to the specified value in the plug-in PLUGNAME.
79 -a, --alloptions
81 Set all boolean options to True for all enabled plug-ins.
82 -v, --verbose
84 Increase logging verbosity. May be specified multiple times to
85 enable additional debugging messages.
86 -q, --quiet
88 Only log fatal errors to stderr.
89 --no-report
91 Disable HTML report writing.
92 --config-file CONFIG
94 Specify alternate configuration file.
95 --no-postproc
97 Disable postprocessing globally for all plugins. This will mean
98 data is not obfuscated/sanitized from the archive during collec‐
99 tion.
100 Note that this means data such as password, SSH keys, certifi‐
102 cates, etc... will be collected in plain text.
103 To selectively disable postprocessing on a per-plugin basis, use
105 the 'postproc' plugin option available to all plugins, e.g. '-k
106 podman.postproc=off'.
107 --preset PRESET
109 Specify an existing preset to use for sos options.
110 Presets are pre-configured sets of options for both sos and sos
112 plugins. For example a preset may enable a certain set of plug‐
113 ins, disable others, or enable specific plugin options. They may
114 also specify sos options such as log-size or package verifica‐
115 tion.
116 User defined presets are saved under /var/lib/sos/presets as
118 JSON-formatted files.
119 --add-preset ADD_PRESET [options]
121 Add a preset with name ADD_PRESET that enables [options] when
122 called.
123 For example, 'sosreport --add-preset mypreset --log-size=50 -n
125 logs' will enable a user to run 'sosreport --preset mypreset'
126 that sets the maximum log size to 50 and disables the logs
127 plugin.
128 Note: to set a description for the preset that is displayed with
130 --list-presets, use the --desc option.
131 Note: to set a behaviour note of the preset, use --note option.
133 Note: The root filesystem, as seen by sos if running within a
135 container, must be writable to save presets using this option.
136 --del-preset DEL_PRESET
138 Deletes the preset with name DEL_PRESET from the filesystem so
139 that it can no longer be used.
140 --list-presets
142 Display a list of available presets and what options they carry.
143 --desc DESCRIPTION
145 When using --add-preset use this option to add a description of
146 the preset that will be displayed when using --list-presets.
147 -s, --sysroot SYSROOT
149 Specify an alternate root file system path. Useful for collect‐
150 ing reports from containers and images.
151 -c, --chroot {auto|always|never}
153 Set the chroot mode. When --sysroot is used commands default to
154 executing with SYSROOT as the root directory (unless disabled by
155 a specific plugin). This can be overridden by setting --chroot
156 to "always" (always chroot) or "never" (always run in the host
157 namespace).
158 --tmp-dir DIRECTORY
160 Specify alternate temporary directory to copy data as well as
161 the compressed report.
162 --list-profiles
164 Display a list of available profiles and the plugins that they
165 enable.
166 -p, --profile, --profiles NAME
168 Only run plugins that correspond to the given profile. Multiple
169 profiles may be specified as a comma-separated list; the set of
170 plugins executed is the union of each of the profile's plugin
171 sets. Currently defined profiles include: boot, cluster, desk‐
172 top, debug, hardware, identity, network, openstack, packageman‐
173 ager, security, services, storage, sysmgmt, system, performance,
174 virt, and webserver.
175 --verify
177 Instructs plugins to perform plugin-specific verification during
178 data collection. This may include package manager verification,
179 log integrity testing or other plugin defined behaviour. Use of
180 --verify may cause the time taken to generate a report to be
181 considerably longer.
182 --log-size
184 Places a global limit on the size (in MiB) of any collected set
185 of logs. The limit is applied separately for each set of logs
186 collected by any plugin.
187 --all-logs
189 Tell plugins to collect all possible log data ignoring any size
190 limits and including logs in non-default locations. This option
191 may significantly increase the size of reports.
192 --since YYYYMMDD[HHMMSS]
194 Limits the collection of log archives to those newer than this
195 date. A log archive is any file not found in /etc, that has ei‐
196 ther a numeric or a compression-type file extension for example
197 ".zip". ".1", ".gz" etc.). This also affects --all-logs. The
198 date string will be padded with zeros if HHMMSS is not speci‐
199 fied.
200 --skip-commands COMMANDS
202 A comma delimited list of commands to skip execution of, but
203 still allowing the rest of the plugin that calls the command to
204 run. This will generally need to be some form of UNIX shell-
205 style wildcard matching. For example, using a value of hostname
206 will skip only that single command, while using hostname* will
207 skip all commands with names that begin with the string "host‐
208 name".
209 --skip-files FILES
211 A comma delimited list of files or filepath wildcard matches to
212 skip collection of. Values may either be exact filepaths or
213 paths using UNIX shell-style wildcards, for example /etc/sos/*.
214 --allow-system-changes
216 Run commands even if they can change the system (e.g. load ker‐
217 nel modules).
218 -z, --compression-type METHOD
220 Override the default compression type specified by the active
221 policy.
222 --encrypt-key KEY
224 Encrypts the resulting archive that sosreport produces using
225 GPG. KEY must be an existing key in the user's keyring as GPG
226 does not allow for keyfiles. KEY can be any value accepted by
227 gpg's 'recipient' option.
228 Note that the user running sosreport must match the user owning
230 the keyring from which keys will be obtained. In particular this
231 means that if sudo is used to run sosreport, the keyring must
232 also be set up using sudo (or direct shell access to the ac‐
233 count).
234 Users should be aware that encrypting the final archive will re‐
236 sult in sos using double the amount of temporary disk space -
237 the encrypted archive must be written as a separate, rather than
238 replacement, file within the temp directory that sos writes the
239 archive to. However, since the encrypted archive will be the
240 same size as the original archive, there is no additional space
241 consumption once the temporary directory is removed at the end
242 of execution.
243 This means that only the encrypted archive is present on disk
245 after sos finishes running.
246 If encryption fails for any reason, the original unencrypted ar‐
248 chive is preserved instead.
249 --encrypt-pass PASS
251 The same as --encrypt-key, but use the provided PASS for symmet‐
252 ric encryption rather than key-pair encryption.
253 --batch
255 Generate archive without prompting for interactive input.
256 --name NAME
258 Deprecated. See --label
259 --label LABEL
261 Specify an arbitrary identifier to associate with the archive.
262 Labels will be appended after the system's short hostname and
263 may contain alphanumeric characters.
264 --threads THREADS
266 Specify the number of threads sosreport will use for concur‐
267 rency. Defaults to 4.
268 --plugin-timeout TIMEOUT
270 Specify a timeout in seconds to allow each plugin to run for. A
271 value of 0 means no timeout will be set. A value of -1 is used
272 to indicate the default timeout of 300 seconds.
273 Note that this options sets the timeout for all plugins. If you
275 want to set a timeout for a specific plugin, use the 'timeout'
276 plugin option available to all plugins - e.g. '-k logs.time‐
277 out=600'.
278 The plugin-specific timeout option will override this option.
280 For example, using ´--plugin-timeout=60 -k logs.timeout=600´
281 will set a timeout of 600 seconds for the logs plugin and 60
282 seconds for all other enabled plugins.
283 --case-id NUMBER
285 Specify a case identifier to associate with the archive. Iden‐
286 tifiers may include alphanumeric characters, commas and periods
287 ('.').
288 --build
290 Do not archive copied data. Causes sosreport to leave an uncom‐
291 pressed archive as a temporary file or directory tree.
292 --debug
294 Enable interactive debugging using the python debugger. Excep‐
295 tions in sos or plug-in code will cause a trap to the pdb shell.
296 --dry-run
298 Execute plugins as normal, but do not collect any file content,
299 command output, or string data from the system. The resulting
300 logs may be used to understand the actions that sos would have
301 taken without the dry run option.
302 --upload
304 If specified, attempt to upload the resulting archive to a ven‐
305 dor defined location.
306 This option is implied if --upload-url is used.
308 You may be prompted for a username and password if these are not
310 defined by the vendor as well. If these credentials are not pro‐
311 vided, sos will still run and create an archive but will not at‐
312 tempt an automatic upload, instead relying on the end user to
313 upload it as needed.
314 The sosreport archive will still remain on the local filesystem
316 even after a successful upload.
317 Note that depending on the distribution sos is being run on, or
319 the vendor policy detected during execution, there may be depen‐
320 dencies that are not strictly required by the package at instal‐
321 lation time.
322 For example, for HTTPS uploads the python-requests library must
324 be available. If this library is not available, HTTPS uploads
325 will not be attempted.
326 --upload-url URL
328 If a vendor does not provide a default upload location, or if
329 you would like to upload the archive to a different location,
330 specify the address here.
331 A support protocol MUST be specified in this URL. Currently up‐
333 loading is supported for HTTPS, SFTP, and FTP protocols.
334 If your destination server listens on a non-standard port, spec‐
336 ify the listening port in the URL.
337 --upload-user USER
339 If a vendor does not provide a default user for uploading, spec‐
340 ify the username here.
341 If this option is unused and upload is request, and a vendor de‐
343 fault is not set, you will be prompted for one. If --batch is
344 used and this option is omitted, no username will be collected
345 and thus uploads will fail if no vendor default is set.
346 You also have the option of providing this value via the SOSU‐
348 PLOADUSER environment variable. If this variable is set, then no
349 username prompt will occur and --batch may be used provided all
350 other required values (case number, upload password) are pro‐
351 vided.
352 --upload-pass PASS
355 Specify the password to use for authentication with the destina‐
356 tion server.
357 If this option is omitted and upload is requested, you will be
359 prompted for one.
360 If --batch is used, this prompt will not occur, so any uploads
362 are likely to fail unless this option is used.
363 Note that this will result in the plaintext string appearing in
365 `ps` output that may be collected by sos and be in the archive.
366 If a password must be provided by you for uploading, it is
367 strongly recommended to not use --batch and enter the password
368 when prompted rather than using this option.
369 You also have the option of providing this value via the SOSU‐
371 PLOADPASSWORD environment variable. If this variable is set,
372 then no password prompt will occur and --batch may be used pro‐
373 vided all other required values (case number, upload user) are
374 provided.
375 --upload-directory DIR
378 Specify a directory to upload to, if one is not specified by a
379 vendor default location or if your destination server does not
380 allow writes to '/'.
381 --experimental
383 Enable plugins marked as experimental. Experimental plugins may
384 not have been tested for this port or may still be under active
385 development.
386 --help Display usage message.
388
390 Bryn M. Reeves <bmr@redhat.com>
391
393 See AUTHORS file in the package documentation.
394
396 Translations are handled by transifex (https://fedorahosted.org/transifex/)
397 Mon Mar 25 2013 SOSREPORT(1)