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 Note: The root filesystem, as seen by sos if running within a
133 container, must be writable to save presets using this option.
134 --del-preset DEL_PRESET
136 Deletes the preset with name DEL_PRESET from the filesystem so
137 that it can no longer be used.
138 --list-presets
140 Display a list of available presets and what options they carry.
141 --desc DESCRIPTION
143 When using --add-preset use this option to add a description of
144 the preset that will be displayed when using --list-presets.
145 -s, --sysroot SYSROOT
147 Specify an alternate root file system path. Useful for collect‐
148 ing reports from containers and images.
149 -c, --chroot {auto|always|never}
151 Set the chroot mode. When --sysroot is used commands default to
152 executing with SYSROOT as the root directory (unless disabled by
153 a specific plugin). This can be overridden by setting --chroot
154 to "always" (always chroot) or "never" (always run in the host
155 namespace).
156 --tmp-dir DIRECTORY
158 Specify alternate temporary directory to copy data as well as
159 the compressed report.
160 --list-profiles
162 Display a list of available profiles and the plugins that they
163 enable.
164 -p, --profile NAME
166 Only run plugins that correspond to the given profile. Multiple
167 profiles may be specified as a comma-separated list; the set of
168 plugins executed is the union of each of the profile's plugin
169 sets. Currently defined profiles include: boot, cluster, desk‐
170 top, debug, hardware, identity, network, openstack, packageman‐
171 ager, security, services, storage, sysmgmt, system, performance,
172 virt, and webserver.
173 --verify
175 Instructs plugins to perform plugin-specific verification during
176 data collection. This may include package manager verification,
177 log integrity testing or other plugin defined behaviour. Use of
178 --verify may cause the time taken to generate a report to be
179 considerably longer.
180 --log-size
182 Places a global limit on the size (in MiB) of any collected set
183 of logs. The limit is applied separately for each set of logs
184 collected by any plugin.
185 --all-logs
187 Tell plugins to collect all possible log data ignoring any size
188 limits and including logs in non-default locations. This option
189 may significantly increase the size of reports.
190 --since YYYYMMDD[HHMMSS]
192 Limits the collection of log archives to those newer than this
193 date. A log archive is any file not found in /etc, that has
194 either a numeric or a compression-type file extension for exam‐
195 ple ".zip". ".1", ".gz" etc.). This also affects --all-logs.
196 The date string will be padded with zeros if HHMMSS is not spec‐
197 ified.
198 --allow-system-changes
200 Run commands even if they can change the system (e.g. load ker‐
201 nel modules).
202 -z, --compression-type METHOD
204 Override the default compression type specified by the active
205 policy.
206 --encrypt-key KEY
208 Encrypts the resulting archive that sosreport produces using
209 GPG. KEY must be an existing key in the user's keyring as GPG
210 does not allow for keyfiles. KEY can be any value accepted by
211 gpg's 'recipient' option.
212 Note that the user running sosreport must match the user owning
214 the keyring from which keys will be obtained. In particular this
215 means that if sudo is used to run sosreport, the keyring must
216 also be set up using sudo (or direct shell access to the
217 account).
218 Users should be aware that encrypting the final archive will
220 result in sos using double the amount of temporary disk space -
221 the encrypted archive must be written as a separate, rather than
222 replacement, file within the temp directory that sos writes the
223 archive to. However, since the encrypted archive will be the
224 same size as the original archive, there is no additional space
225 consumption once the temporary directory is removed at the end
226 of execution.
227 This means that only the encrypted archive is present on disk
229 after sos finishes running.
230 If encryption fails for any reason, the original unencrypted ar‐
232 chive is preserved instead.
233 --encrypt-pass PASS
235 The same as --encrypt-key, but use the provided PASS for symmet‐
236 ric encryption rather than key-pair encryption.
237 --batch
239 Generate archive without prompting for interactive input.
240 --name NAME
242 Deprecated. See --label
243 --label LABEL
245 Specify an arbitrary identifier to associate with the archive.
246 Labels will be appended after the system's short hostname and
247 may contain alphanumeric characters.
248 --threads THREADS
250 Specify the number of threads sosreport will use for concur‐
251 rency. Defaults to 4.
252 --plugin-timeout TIMEOUT
254 Specify a timeout in seconds to allow each plugin to run for. A
255 value of 0 means no timeout will be set.
256 Note that this options sets the timeout for all plugins. If you
258 want to set a timeout for a specific plugin, use the 'timeout'
259 plugin option available to all plugins - e.g. '-k logs.time‐
260 out=600'.
261 The plugin-specific timeout option will override this option.
263 For example, using ´--plugin-timeout=60 -k logs.timeout=600´
264 will set a timeout of 600 seconds for the logs plugin and 60
265 seconds for all other enabled plugins.
266 --case-id NUMBER
268 Specify a case identifier to associate with the archive. Iden‐
269 tifiers may include alphanumeric characters, commas and periods
270 ('.'). Synonymous with --ticket-number.
271 --ticket-number NUMBER
273 Specify a ticket number or other identifier to associate with
274 the archive. Identifiers may include alphanumeric characters,
275 commas and periods ('.'). Synonymous with --case-id.
276 --build
278 Do not archive copied data. Causes sosreport to leave an uncom‐
279 pressed archive as a temporary file or directory tree.
280 --debug
282 Enable interactive debugging using the python debugger. Excep‐
283 tions in sos or plug-in code will cause a trap to the pdb shell.
284 --dry-run
286 Execute plugins as normal, but do not collect any file content,
287 command output, or string data from the system. The resulting
288 logs may be used to understand the actions that sos would have
289 taken without the dry run option.
290 --upload
292 If specified, attempt to upload the resulting archive to a ven‐
293 dor defined location.
294 This option is implied if --upload-url is used.
296 You may be prompted for a username and password if these are not
298 defined by the vendor as well. If these credentials are not pro‐
299 vided, sos will still run and create an archive but will not
300 attempt an automatic upload, instead relying on the end user to
301 upload it as needed.
302 The sosreport archive will still remain on the local filesystem
304 even after a successful upload.
305 Note that depending on the distribution sos is being run on, or
307 the vendor policy detected during execution, there may be depen‐
308 dencies that are not strictly required by the package at instal‐
309 lation time.
310 For example, for HTTPS uploads the python-requests library must
312 be available. If this library is not available, HTTPS uploads
313 will not be attempted.
314 --upload-url URL
316 If a vendor does not provide a default upload location, or if
317 you would like to upload the archive to a different location,
318 specify the address here.
319 A support protocol MUST be specified in this URL. Currently
321 uploading is supported for HTTPS, SFTP, and FTP protocols.
322 If your destination server listens on a non-standard port, spec‐
324 ify the listening port in the URL.
325 --upload-user USER
327 If a vendor does not provide a default user for uploading, spec‐
328 ify the username here.
329 If this option is unused and upload is request, and a vendor
331 default is not set, you will be prompted for one. If --batch is
332 used and this option is omitted, no username will be collected
333 and thus uploads will fail if no vendor default is set.
334 --upload-pass PASS
336 Specify the password to use for authentication with the destina‐
337 tion server.
338 If this option is omitted and upload is requested, you will be
340 prompted for one.
341 If --batch is used, this prompt will not occur, so any uploads
343 are likely to fail unless this option is used.
344 Note that this will result in the plaintext string appearing in
346 `ps` output that may be collected by sos and be in the archive.
347 If a password must be provided by you for uploading, it is
348 strongly recommended to not use --batch and enter the password
349 when prompted rather than using this option.
350 --upload-directory DIR
352 Specify a directory to upload to, if one is not specified by a
353 vendor default location or if your destination server does not
354 allow writes to '/'.
355 --experimental
357 Enable plugins marked as experimental. Experimental plugins may
358 not have been tested for this port or may still be under active
359 development.
360 --help Display usage message.
362
364 Bryn M. Reeves <bmr@redhat.com>
365
367 See AUTHORS file in the package documentation.
368
370 Translations are handled by transifex (https://fedorahosted.org/transifex/)
371 Mon Mar 25 2013 SOSREPORT(1)