SOS_REPORT(1)

📦
version 4.12.1 · 7 versions
, in fedora 43, fedora 44

🌸 SOS_REPORT(1) — the sos_report era, General Commands Manual, but make it cute 🌸

okay bestie, so sos_report is the manual name here, and this is the whole vibe: it collects and packages your diagnostic + support data. let's get into it 💖

✨ NAME ✨

sos_report — Collect and package diagnostic and support data 🎀

🦋 SYNOPSIS 🦋

sos report
          [-l|--list-plugins]
          [-n|--skip-plugins plugin-names]
          [-e|--enable-plugins plugin-names]
          [-o|--only-plugins plugin-names]
          [-a|--alloptions] [-v|--verbose]
          [-k plug.opt|--plugin-option plug.opt]|--plugopts plug.opt
          [--no-report] [--config-file conf]
          [--no-postproc]
          [--preset preset] [--add-preset add_preset]
          [--note note]
          [--del-preset del_preset] [--desc description]
          [--batch] [--build] [--debug] [--dry-run]
          [--estimate-only] [--label label] [--case-id id]
          [--threads threads]
          [--plugin-timeout TIMEOUT]
          [--cmd-timeout TIMEOUT]
          [--namespaces NAMESPACES]
          [--container-runtime RUNTIME]
          [-s|--sysroot SYSROOT]
          [-c|--chroot {auto|always|never}
          [--tmp-dir directory]
          [-p|--profile profile-name]
          [--list-profiles]
          [--verify]
          [--log-size]
          [--journal-size]
          [--no-env-vars]
          [--all-logs]
          [--since YYYYMMDD[HHMMSS]]
          [--skip-commands commands]
          [--skip-files files]
          [--pack-dir directories]
          [--allow-system-changes]
          [--low-priority]
          [-z|--compression-type method]
          [--clean|--mask]
          [--encrypt]
          [--encrypt-key KEY]
          [--encrypt-pass PASS]
          [--upload] [--upload-url url] [--upload-user user]
          [--upload-directory dir] [--upload-pass pass]
          [--upload-no-ssl-verify] [--upload-method]
          [--upload-protocol protocol]
          [--upload-s3-endpoint endpoint]
          [--upload-s3-region region]
          [--upload-s3-bucket bucket]
          [--upload-s3-access-key key]
          [--upload-s3-secret-key key]
          [--upload-s3-object-prefix prefix]
          [--upload-threads threads]
          [--experimental]
          [-h|--help]

so many flags bestie. it's giving options menu at a boba shop 🧋💅

💜 DESCRIPTION 💜

okay so report is an sos subcommand (a lil baby command that lives inside the big sos one, iykyk) and what it does is generate an archive of configuration and diagnostic information from the system that's currently running. like, it's taking a lil snapshot of everything 👑

that archive can be stored locally or centrally — for recording or tracking purposes, or it can get sent off to technical support representatives, developers, or system administrators so they can help with technical fault-finding and debugging. it's basically the "send help, here's everything" button 🫶

Sos is modular in design (very main character architecture ✨) and it's able to collect data from a wide range of subsystems and packages that may be installed. and then — an HTML report summarizing all the collected info is optionally generated and stored inside the archive. cute, right? 🎀

⚠️ Note: the sosreport command has been deprecated and will be removed in sos-4.9. Use the new sos report syntax instead. no cap, please migrate bestie 😭

💅 OPTIONS 💅

  • -l, --list-plugins — Lists every plugin that's available, plus their options. Plug-ins that wouldn't be enabled by the current configuration get listed separately, so you can tell the difference 👀
  • -n, --skip-plugins PLUGNAME[,PLUGNAME] — Turn OFF the plugin(s) you name. You can stack multiple plug-ins by repeating the option, or just smush them into one comma-separated list 🚫✨
  • -e, --enable-plugins PLUGNAME[,PLUGNAME] — Turn ON the plugin(s) you name that would otherwise be disabled. Same deal: repeat the option or use a comma-separated list 💖
heads up: if you're using -p, --profile, this option will not enable further plugins. Use -o, --only-plugins to extend the list of plugins enabled by profiles. okay? okay 🫶
  • -o, --only-plugins PLUGNAME[,PLUGNAME] — Enable only the plugin(s) you name, and everything else should be disabled. all eyes on you, chosen plugins 👑 again: repeat the option or comma-separate them.
  • -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE], --plugopts=PLUGNAME.PLUGOPT[=VALUE] — Specify plug-in options. The option PLUGOPT gets enabled, or gets set to the value you specify, inside the plug-in PLUGNAME 🎛️
  • -a, --alloptions — Set every boolean option to True for all enabled plug-ins. yes, all of them. go off 💅
  • -v, --verbose — Turn the logging verbosity up. You can pass it multiple times to unlock additional debugging messages 🔥
  • -q, --quiet — Only log fatal errors to stderr. shhh 🤫
  • --no-report — Disable HTML report writing. no HTML bestie, we're going raw 🌸
  • --config-file CONFIG — Specify an alternate configuration file 📄
  • --no-postproc — Disable postprocessing globally for all plugins. This means data is not obfuscated/sanitized from the archive during collection.
🚨 Note that this means data such as password, SSH keys, certificates, etc… will be collected in plain text. like, glaringly plain text. be so serious about this one 😭

To selectively disable postprocessing on a per-plugin basis, use the 'postproc' plugin option available to all plugins, e.g. '-k podman.postproc=off'. 🎀

  • --preset PRESET — Specify an existing preset to use for sos options.

Presets are pre-configured sets of options for both sos and sos plugins. Like, a preset might enable a certain set of plugins, disable others, or enable specific plugin options. They may also specify sos options such as log-size or package verification. it's giving "saved settings" but make it powerful ✨

User defined presets are saved under /etc/sos/presets.d as JSON-formatted files. 💾

  • --add-preset ADD_PRESET [options] — Add a preset with the name ADD_PRESET that enables [options] when it's called.

For example, 'sos report --add-preset mypreset --log-size=50 -n logs' will enable a user to run 'sos report --preset mypreset' that sets the maximum log size to 50 and disables the logs plugin. iconic behavior honestly 🫶

Note: to set a description for the preset that's displayed with --list-presets, use the --desc option.
Note: to set a behaviour note of the preset, use --note option.
Note: the root filesystem, as seen by sos if running within a container, must be writable to save presets using this option. no write access, no preset, sorry bestie 🙈
  • --del-preset DEL_PRESET — Deletes the preset with the name DEL_PRESET from the filesystem so that it can no longer be used. bye bye 👋
  • --list-presets — Display a list of available presets AND what options they carry. the full tea ☕
  • --desc DESCRIPTION — When using --add-preset, use this option to add a description of the preset that will be displayed when using --list-presets 💬
  • --note NOTE — When using --add-preset, use this option to add a behaviour note to the preset that will be displayed when using --list-presets.

This is useful for documenting specific behaviours, caveats, or use-cases for the preset beyond the basic description. like a lil sticky note on your fave preset 🍓

  • -s, --sysroot SYSROOT — Specify an alternate root file system path. Super useful for collecting reports from containers and images 🐳
  • -c, --chroot {auto|always|never} — Set the chroot mode. When --sysroot is used, commands default to executing with SYSROOT as the root directory (unless that's disabled by a specific plugin). You can override this by setting --chroot to "always" (always chroot) or "never" (always run in the host namespace). pick your fighter 🥊
  • --tmp-dir DIRECTORY — Specify an alternate temporary directory to copy data into, as well as where the compressed report goes 🗂️
  • --list-profiles — Display a list of available profiles and the plugins that they enable 🌈
  • -p, --profile, --profiles NAME — Only run plugins that correspond to the given profile. Multiple profiles may be specified as a comma-separated list; the set of plugins executed is the union of each of the profile's plugin sets. teamwork makes the dream work 💫
Note that if there are specific plugins outside of the profile(s) passed to this option that you'd also want to enable, use -o, --only-plugins to add those plugins to the list.

See sos report --list-profiles for a list of currently supported profiles 👑

  • --verify — Instructs plugins to perform plugin-specific verification during data collection. This may include package manager verification, log integrity testing, or other plugin defined behaviour. Use of --verify may cause the time taken to generate a report to be considerably longer. worth it? maybe. slow? yes 😭
  • --log-size — Places a limit on the size of collected logs and output, in MiB. Note that this causes sos to capture the last X amount of the file or command output collected.

By default, this is set to 25 MiB and applies to all files and command output collected — with the exception of journal collections, which are limited by the --journal-size option instead.

Setting this value to 0 removes all size limitations, and any files or commands collected will be collected in their entirety. which may drastically increase the size of the final sos report tarball and the memory usage of sos during collection of commands. huge. be careful 💀

  • --journal-size — Places a limit on the size of journals collected, in MiB. Note that this causes sos to capture the last X amount of the journal.

By default, this is set to 100 MiB. Setting this value to 0 removes all size limitations, as does the use of the --all-logs option. This may drastically increase the size of the final sos report tarball 😳

  • --all-logs — Tell plugins to collect all possible log data, ignoring any size limits and including logs in non-default locations. This option may significantly increase the size of reports. all the logs, no crumbs left 🧹✨
  • --no-env-vars — Do not collect environment variables in the report.

By default, sos report collects environment variables from the system, which may contain sensitive information. Use this option to exclude environment variable collection for privacy or security reasons. Note that this may limit the usefulness of the report for debugging environment-related issues — so it's a tradeoff, bestie ⚖️🙈

  • --since YYYYMMDD[HHMMSS] — Limits the collection of log archives to those newer than this date. A log archive is any file not found in /etc, that has either a numeric or a compression-type file extension for example ".zip", ".1", ".gz" etc.). This also affects --all-logs. The date string will be padded with zeros if HHMMSS is not specified. ⏰💖
  • --skip-commands COMMANDS — bestie this is a comma delimited list of commands to skip execution of, but (and this is the important bit) the rest of the plugin that calls the command still runs. 💅 This generally needs to be some form of UNIX shell-style wildcard matching. So like, a value of hostname skips only that single command, whereas hostname* skips every command whose name begins with the string "hostname". wildcards really said "I contain multitudes" ✨
  • --skip-files FILES — a comma delimited list of files or filepath wildcard matches to skip collection of. 🎀 Values may either be exact filepaths or paths using UNIX shell-style wildcards, for example /etc/sos/*. no cap, exact paths and vibes-paths are both valid here.
  • --pack-dir DIRECTORIES — a comma delimited list of collected directories to replace with a single tarball within the report, for example /proc/fs/. 🫶 The named directory gets packed into an uncompressed tarball alongside it (e.g. proc/fs/ becomes proc/fs.tar) and the original tree is removed; the rest of the report is unchanged. This is the moment for verbose trees holding a very large number of tiny little files, where extracting the report would otherwise have to recreate every single file on disk 😭. The tarball is not compressed here since the whole report gets compressed when packaged. Directories not collected as a directory are skipped. May be repeated. 👑
  • --allow-system-changes — run commands even if they can change the system (e.g. load kernel modules). she's dangerous but she's doing it on purpose 💀
  • --low-priority — set sos to execute as a low priority process so that it does not interfere with other processes running on the system. 🌸 Specific distributions may set their own constraints, but by default this involves setting process niceness to 19 and, if available, setting an idle IO class via ionice. respect the other processes bestie, they're also main characters.
  • --clean, --cleaner, --mask — enable inline obfuscation/cleaning of the generated report. ✨

When this option is used, the report will be processed to obfuscate sensitive information such as hostnames, IP addresses, MAC addresses, and user-specified keywords during generation, rather than as a separate post-processing step. (cleaning while generating?? she's multitasking, we love a girlboss 🎀)

Additional cleaning/masking options (such as --domains, --keywords, --map-file, --usernames, etc.) control the cleaning behavior. For documentation of all cleaning options, see sos-clean(1).

  • -z, --compression-type METHOD — override the default compression type specified by the active policy. 💅 the policy said one thing, you said another, and honestly? you're right.
  • --encrypt — encrypt the resulting archive, and determine the method by which that encryption is done by either a user prompt or environment variables. 🔐

When run with --batch, using this option will cause sos to look for either the SOSENCRYPTKEY or SOSENCRYPTPASS environment variables. If set, this will implicitly enable the --encrypt-key or --encrypt-pass options, respectively, to the values set by the environment variable. This enables the use of these options without directly setting those options in a config file or command line string. Note that use of an encryption key has precedence over a passphrase.

Otherwise, using this option will cause sos to prompt the user to choose the method of encryption to use. Choices will be [P]assphrase, [K]ey, [E]nv vars, or [N]o encryption. If passphrase or key the user will then be prompted for the respective value, env vars will cause sos to source the information in the manner stated above, and choosing no encryption will disable encryption.

See the sections on --encrypt-key and --encrypt-pass below for more information.

  • --encrypt-key KEY — encrypts the resulting archive that sos report produces using GPG. 🔐 KEY must be an existing key in the user's keyring as GPG does not allow for keyfiles. KEY can be any value accepted by gpg's 'recipient' option.

Note that the user running sos report must match the user owning the keyring from which keys will be obtained. In particular this means that if sudo is used to run sos report, the keyring must also be set up using sudo (or direct shell access to the account). 🫶

Users should be aware that encrypting the final archive will result in sos using double the amount of temporary disk space — the encrypted archive must be written as a separate, rather than replacement, file within the temp directory that sos writes the archive to. However, since the encrypted archive will be the same size as the original archive, there is no additional space consumption once the temporary directory is removed at the end of execution.

This means that only the encrypted archive is present on disk after sos finishes running.

If encryption fails for any reason, the original unencrypted archive is preserved instead. 😌 a safety net, periodt.

  • --encrypt-pass PASS — the same as --encrypt-key, but use the provided PASS for symmetric encryption rather than key-pair encryption. 💅
  • --batch — generate archive without prompting for interactive input. no questions, no waiting, she just goes. ✨
  • --name NAME — deprecated. See --label. 🚫 she's a legacy girl, retired.
  • --label LABEL — specify an arbitrary identifier to associate with the archive. Labels will be appended after the system's short hostname and may contain alphanumeric characters. 🎀
  • --threads THREADS — specify the number of threads sos report will use for concurrency. Defaults to 4. 🔥 parallel girlie activities.
  • --plugin-timeout TIMEOUT — specify a timeout in seconds to allow each plugin to run for. A value of 0 means no timeout will be set. A value of -1 is used to indicate the default timeout of 300 seconds. ⏰

Note that this option sets the timeout for all plugins. If you want to set a timeout for a specific plugin, use the 'timeout' plugin option available to all plugins — e.g. '-k logs.timeout=600'.

The plugin-specific timeout option will override this option. For example, using '--plugin-timeout=60 -k logs.timeout=600' will set a timeout of 600 seconds for the logs plugin and 60 seconds for all other enabled plugins.

  • --cmd-timeout TIMEOUT — specify a timeout limit in seconds for a command execution. Same defaults logic from --plugin-timeout applies here. ⏰

This option sets the command timeout for all plugins. If you want to set a cmd timeout for a specific plugin, use the 'cmd-timeout' plugin option available to all plugins — e.g. '-k logs.cmd-timeout=600'.

Again, the same plugin/global precedence logic as for --plugin-timeout applies here.

Note that setting --cmd-timeout (or -k logs.cmd-timeout) high should be followed by increasing the --plugin-timeout equivalent, otherwise the plugin can easily timeout on slow commands execution. 💀 don't skip this part bestie, she WILL abandon you mid-command.

  • --namespaces NAMESPACES — for plugins that iterate collections over namespaces that exist on the system, for example the networking plugin collecting ip command output for each network namespace, use this option to limit the number of namespaces that will be collected. 🌐

Use '0' (default) for no limit — all namespaces will be used for collections.

Note that specific plugins may provide a similar namespaces plugin option. If the plugin option is used, it will override this option.

  • --container-runtime RUNTIME — force the use of the specified RUNTIME as the default runtime that plugins will use to collect data from and about containers and container images. 🐳 By default, the setting of auto results in the local policy determining what runtime will be the default runtime (in configurations where multiple runtimes are installed and active).

If no container runtimes are active, this option is ignored. If there are runtimes active, but not one with a name matching RUNTIME, sos will abort. 😭

Setting this to none, off, or disabled will cause plugins to NOT leverage any active runtimes for collections. Note that if disabled, plugins specifically for runtimes (e.g. the podman or docker plugins) will still collect general data about the runtime, but will not inspect existing containers or images.

Default: 'auto' (policy determined).

  • --case-id NUMBER — specify a case identifier to associate with the archive. Identifiers may include alphanumeric characters, commas and periods ('.'). 🗂️
  • --build — do not archive copied data. Causes sos report to leave an uncompressed archive as a temporary file or directory tree. 🌈 no zip, no tar, just the raw tree sitting there.
  • --debug — enable interactive debugging using the python debugger. Exceptions in sos or plug-in code will cause a trap to the pdb shell. 🐛 we love a dramatic exit into a debugger
  • --dry-run — execute plugins as normal, but do not collect any file content, command output, or string data from the system. The resulting logs may be used to understand the actions that sos would have taken without the dry run option. ✨ a rehearsal, a lil dress rehearsal, no data actually touched.
  • --estimate-only — estimate disk space requirements when running sos report. This can be valuable to prevent sos report working dir to consume all free disk space. No plugin data is available at the end. 😬

Plugins will be collected sequentially, size of collected files and commands outputs will be calculated and the plugin files will be immediately deleted prior execution of the next plugin. This still can consume whole free disk space, though. 💀

Please note, size estimations may not be accurate for highly utilized systems due to changes between an estimate and a real execution. Also some difference between estimation (using stat command) and other commands used (i.e. du).

A rule of thumb is to reserve at least double the estimation. 🫶

  • --upload — if specified, attempt to upload the resulting archive to a vendor defined location. 📤

This option is implied if --upload-url is used.

You may be prompted for a username and password if these are not defined by the vendor as well. If these credentials are not provided, sos will still run and create an archive but will not attempt an automatic upload, instead relying on the end user to upload it as needed. 🌸

The sos report archive will still remain on the local filesystem even after a successful upload — like, it doesn't ghost you, it's still right there in your files. 💾

Also bestie, heads up: depending on what distribution sos is running on, or the vendor policy it sniffs out while executing, there might be dependencies that aren't, like, strictly required by the package at installation time. It's giving "we'll see when we get there." 🙈

For example, for HTTPS uploads the python-requests library has to be available. If it's not available, HTTPS uploads just won't be attempted. Periodt.

  • --upload-url URL — If a vendor doesn't hand you a default upload location, or if you wanna send the archive somewhere else entirely, drop the address right here. 💌 A support protocol MUST be specified in this URL, no cap. Currently uploading is supported for HTTPS, SFTP, and FTP protocols. And if your destination server listens on a non-standard port, specify the listening port in the URL.
  • --upload-user USER — If a vendor doesn't give a default user for uploading, put the username here. If this option isn't used and upload is requested, and there's no vendor default set, you'll get prompted for one. But if --batch is used and this option is omitted, no username will be collected at all, and thus uploads will fail if no vendor default is set. 💀 You can also slide this value in via the SOSUPLOADUSER environment variable — if that variable is set, no username prompt will occur and --batch may be used, provided all other required values (case number, upload password) are provided. This option is ignored when uploading to the Red Customer Portal or Red Hat Secure FTP server in favour of web token authentication.
  • --upload-pass PASS — Specify the password to use for authentication with the destination server. If this option is omitted and upload is requested, you'll be prompted for one. If --batch is used, that prompt will not happen, so any uploads are likely to fail unless this option is used.
⚠️ Real talk: this may result in the plaintext string showing up in ps output that may be collected by sos and end up in the archive. If you must provide a password for uploading, it is strongly recommended to not use --batch and instead enter the password when prompted rather than using this option. Protect yourself first, bestie. 🔐

You also have the option of providing this value via the SOSUPLOADPASSWORD environment variable. If that variable is set, no password prompt will occur and --batch may be used, provided all other required values (case number, upload user) are provided. This option is ignored when uploading to the Red Customer Portal or Red Hat Secure FTP server in favour of web token authentication.

  • --upload-directory DIR — Specify a directory to upload to, if one isn't specified by a vendor default location, or if your destination server doesn't allow writes to '/'. 🚫
  • --upload-method METHOD — Specify the HTTP method to use for uploading to the provided --upload-url. Valid values are 'auto' (default), 'put', or 'post'. Using 'auto' will default to the method required by the policy-default upload location, if one exists. This option has no effect on upload protocols other than HTTPS.
  • --upload-no-ssl-verify — Disable SSL verification for HTTPS uploads. This may be used to allow uploading to locations that have self-signed certificates, or certificates that are otherwise untrusted by the local system. 🔓 Default behavior is to perform SSL verification against all upload locations.
  • --upload-protocol PROTO — Manually specify the protocol to use for uploading to the target upload-url. Normally this is determined via the upload address, assuming the protocol is part of the address provided, e.g. 'https://example.com'. By using this option, sos will skip the protocol check and use the method defined for the specified PROTO. For RHEL systems, setting this option to sftp will skip the initial attempt to upload to the Red Hat Customer Portal, and only attempt an upload to Red Hat's SFTP server, which is typically used as a fallback target. Valid values for PROTO are: 'auto' (default), 'https', 'ftp', 'sftp', 's3'.
  • --upload-s3-endpoint ENDPOINT — Endpoint to upload to for S3 bucket.
  • --upload-s3-region REGION — Region to upload to for S3 bucket.
  • --upload-s3-bucket BUCKET — Name of the S3 bucket to upload to.
  • --upload-s3-access-key KEY — Access key for the S3 bucket.
  • --upload-s3-secret-key KEY — Secret key for the S3 bucket.
  • --upload-s3-object-prefix PREFIX — Prefix for the S3 object/key.
  • --upload-threads THREADS — Number of threads to use for multipart uploads (1-16, default: 4). When an archive exceeds a certain size, defined in the targets, it is uploaded in parallel chunks using this many threads. Higher values speed up the upload but consume more bandwidth and memory, as each thread holds a 128 MiB chunk in memory. 🏃‍♀️💨
  • --experimental — Enable plugins marked as experimental. Experimental plugins may not have been tested for this port or may still be under active development. 🧪
  • --help — Display usage message.

✨ SEE ALSO ✨

sos(1) sos-clean(1) sos-collect(1) sos.conf(5)

👑 MAINTAINER 👑

Maintained on GitHub at https://github.com/sosreport/sos

🫶 AUTHORS & CONTRIBUTORS 🫶

See AUTHORS file in the package documentation.

And that's the whole page, bestie — this version lives in SOS_REPORT(1) and it's dated Mon Mar 25 2013. Iconic from day one, no notes. 💅🌸✨

📦 where this page comes from