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