SOS_REPORT(1)

📦
version 4.11.2 · 4 versions
, in ubuntu jammy, ubuntu noble

✨ SOS_REPORT(1) · sos_report 🎀

okay bestie, this is the manual page for sos report, the sos subcommand that gathers diagnostic and support data 💅. it's from the General Commands Manual, and we're doing it in three parts, so stay with me 🫶

🌸 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]
          [--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]
          [--all-logs]
          [--since YYYYMMDD[HHMMSS]]
          [--skip-commands commands]
          [--skip-files files]
          [--allow-system-changes]
          [--low-priority]
          [-z|--compression-type method]
          [--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]
          [--experimental]
          [-h|--help]

💖 DESCRIPTION

okay so report is an sos subcommand that makes an archive of configuration and diagnostic info from the running system ✨. the archive can be stored locally or centrally for recording or tracking, or it can be sent to tech support reps, developers or sysadmins to help with fault-finding and debugging 🔍. it's giving main character energy 👑

sos is modular in design, so it can collect data from a wide range of subsystems and whatever packages happen to be installed 🌈. an HTML report summarizing the collected info is optionally generated and stored inside the archive 🦋.

💀 Note: the sosreport command has been deprecated and will be removed in sos-4.9. use the new sos report syntax instead 😭

🎀 OPTIONS

  • -l, --list-plugins — list every available plugin and its options 📋. plugins that the current configuration wouldn't enable get listed separately 🙈.
  • -n, --skip-plugins PLUGNAME[,PLUGNAME] — disable the plugin(s) you name 🚫. you can pass several by repeating the option or with a comma-separated list 💅.
  • -e, --enable-plugins PLUGNAME[,PLUGNAME] — enable plugin(s) 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 won't enable any extra plugins 🙅‍♀️. use -o, --only-plugins to extend the list of plugins that profiles enable instead.

  • -o, --only-plugins PLUGNAME[,PLUGNAME] — enable only the plugin(s) you name, and disable everything else 🎯. repeat the option or use a comma-separated list.
  • -k PLUGNAME.PLUGOPT[=VALUE], --plugin-option=PLUGNAME.PLUGOPT[=VALUE], --plugopts=PLUGNAME.PLUGOPT[=VALUE] — set plugin options 🧁. this turns PLUGOPT on, or sets it to the value you give, inside the plugin PLUGNAME.
  • -a, --alloptions — set every boolean option to True for all enabled plugins 🔥.
  • -v, --verbose — bump up the logging verbosity 📢. you can repeat it to get extra debugging messages 🔎.
  • -q, --quiet — only log fatal errors to stderr 🤫.
  • --no-report — skip writing the HTML report 🙅‍♀️.
  • --config-file CONFIG — point sos at an alternate configuration file 📁.
  • --no-postproc — turn off postprocessing globally for every plugin 🧨. the catch is that data won't be obfuscated or sanitized out of the archive during collection.
😱 Bestie, this one's serious: passwords, SSH keys, certificates, etc... will be collected in plain text 🙈.

if you only want to skip postprocessing for one plugin, use the postproc plugin option that every plugin has, e.g. -k podman.postproc=off 🫶.

  • --preset PRESET — use an existing preset for your sos options 🎀.

presets are pre-set bundles of options for both sos and its plugins 💜. a preset might enable a certain group of plugins, disable others, or turn on specific plugin options. presets can also set sos options like log-size or package verification 🌸. user-defined presets are saved under /etc/sos/presets.d as JSON-formatted files 📂.

  • --add-preset ADD_PRESET [options] — make a new preset called ADD_PRESET that applies the [options] whenever it's used 🛠️.

for example, sos report --add-preset mypreset --log-size=50 -n logs lets you run sos report --preset mypreset later, and that'll set the max log size to 50 and disable the logs plugin ✨.

📝 to add a description that shows up with --list-presets, use the --desc option.

📝 to add a behaviour note for the preset, use the --note option.

⚠️ If sos is running inside a container, the root filesystem (as sos sees it) has to be writable to save presets with this option.
  • --del-preset DEL_PRESET — delete the preset named DEL_PRESET from the filesystem so nobody can use it anymore 🗑️.
  • --list-presets — show all the available presets and the options each one carries 📜.
  • --desc DESCRIPTION — used alongside --add-preset, this adds the description that --list-presets will display 💬.
  • -s, --sysroot SYSROOT — set an alternate root filesystem path 🌳. super handy for collecting reports from containers and images 📦.
  • -c, --chroot {auto|always|never} — set the chroot mode 🪄. when --sysroot is in use, commands run with SYSROOT as their root directory by default (unless a specific plugin turns that off). you can override this by setting --chroot to "always" (always chroot) or "never" (always run in the host namespace) 💅.
  • --tmp-dir DIRECTORY — pick an alternate temporary directory for copying data and for the compressed report 🗂️.
  • --list-profiles — show all the available profiles and which plugins each one enables 📚.
  • -p, --profile, --profiles NAME — only run the plugins that match the profile you give 🎯. you can list several profiles separated by commas, and the plugins that run are the union of each profile's plugin set 🫧.

if there are plugins outside the profile(s) you'd still like, use -o, --only-plugins to add them to the list 💖.

check sos report --list-profiles for the currently supported profiles 🌈.

  • --verify — tell plugins to do plugin-specific verification while collecting data 🔐. that can include package manager verification, log integrity testing, or other plugin-defined behaviour.
🐢 --verify can make report generation take a lot longer.
  • --log-size — put a limit (in MiB) on the size of collected logs and output 📏. sos captures the last X amount of each file or command output it collects 🧾.

by default this is 25 MiB, and it applies to every file and command output collected, except journal collections, which are limited by --journal-size instead 📓.

setting this to 0 removes all size limits 🌊. every file or command then gets collected in full, which can drastically grow the final sos report tarball and the memory sos uses while collecting commands 🥵.

  • --journal-size — put a limit (in MiB) on the size of collected journals 📖. sos captures the last X amount of the journal.

by default this is 100 MiB 💯. setting it to 0 removes all size limits, and so does using --all-logs 🙌. this can drastically increase the size of the final sos report tarball 😵.

  • --all-logs — tell plugins to collect all possible log data 🗃️. that ignores any size limits and includes logs from non-default locations too. this option can significantly bloat reports 🎈.
  • --since YYYYMMDD[HHMMSS] — only collect log archives newer than this date 🗓️. a log archive is any file that isn't in /etc and has either a numeric or a compression-type file extension, for example ".zip". ".1", ".gz" etc.). this also affects --all-logs. the date string gets padded with zeros if HHMMSS isn't specified ⏰.
  • --skip-commands COMMANDS — a comma-delimited list of commands to skip running 🙅‍♀️. the rest of the plugin that calls those commands still runs, though 💖. this will generally need to be some kind of UNIX shell-style wildcard matching. for example, hostname skips only that one command, while hostname* skips every command whose name begins with the string "hostname" 🔍.
  • --skip-files FILES — a comma-delimited list of files or filepath wildcard matches to skip collecting 🚷. values can be exact filepaths or paths using UNIX shell-style wildcards, for example /etc/sos/* 🗂️.
  • --allow-system-changes — run commands even if they can change the system (e.g. loading kernel modules) ⚠️. use with care, bestie 🫣.
  • --low-priority — run sos as a low priority process so it doesn't mess with everything else on the system 🐌. some distributions set their own constraints, but by default this means setting process niceness to 19 and, if it's available, setting an idle IO class via ionice 🧘‍♀️.
  • -z, --compression-type METHOD — override the default compression type that the active policy specifies 🗜️.

That's the first third, besties 🌈💖✨ more is coming up next, so don't go anywhere 🫶

  • --encrypt — 🔐 Encrypts the finished archive! The encryption method is picked either by a prompt or by environment variables, so you can choose your vibe.

When you run it with --batch, sos goes hunting for the SOSENCRYPTKEY or SOSENCRYPTPASS environment variables. If one is set, it quietly turns on --encrypt-key or --encrypt-pass with that value, so you don't need to put anything in a config file or your command line. ✨ If both are around, the key wins over the passphrase, periodt.

Without --batch, sos asks you to pick a method: [P]assphrase, [K]ey, [E]nv vars, or [N]o encryption. Passphrase and key will ask you for the actual value. Env vars means sos grabs the info the way we just talked about. And [N] turns encryption off entirely 🙈

Check the sections on --encrypt-key and --encrypt-pass below for more deets 💜

  • --encrypt-key KEY — 🗝️ Encrypts the archive with GPG. The KEY has to be a key that already exists in the user's keyring, because GPG doesn't do keyfiles. KEY can be anything that gpg's recipient option accepts.

The person running sos report has to be the same person who owns the keyring. So if you use sudo to run it, the keyring also has to be set up through sudo (or by direct shell access to that account). Main character rules 💅

Heads up! Encrypting the final archive means sos needs double the temp disk space. The encrypted copy gets written as a separate file in the temp directory, not as a replacement. The good news is the encrypted archive is the same size as the original, so there's no extra space hanging around once the temp directory gets cleaned up at the end. 🧹

After sos finishes, only the encrypted archive is left on disk. And if encryption fails for any reason, the original unencrypted archive is kept instead 🫶

  • --encrypt-pass PASS — 🔑 Same as --encrypt-key, except it uses the PASS you give it for symmetric encryption instead of key-pair encryption.
  • --batch — 🤖 Makes the archive without asking you for any interactive input.
  • --name NAME — 🥀 Deprecated, so please don't use it. Use --label instead.
  • --label LABEL — 🏷️ Attaches an arbitrary identifier to the archive. The label gets tacked on after the system's short hostname and can have alphanumeric characters in it.
  • --threads THREADS — 🧵 Sets how many threads sos report uses for concurrency. It defaults to 4.
  • --plugin-timeout TIMEOUT — ⏱️ Sets how many seconds each plugin is allowed to run. 0 means no timeout at all, and -1 gives you the default timeout of 300 seconds.

This sets the timeout for every plugin at once. If you want one specific plugin to have its own timeout, use the timeout plugin option (every plugin has it!). For example: -k logs.timeout=600.

A plugin-specific timeout beats this option. So with --plugin-timeout=60 -k logs.timeout=600, the logs plugin gets 600 seconds and every other enabled plugin gets 60 seconds. Ultra precise, bestie ✨

  • --cmd-timeout TIMEOUT — ⏳ Sets a timeout in seconds for each command execution. It follows the same defaults logic as --plugin-timeout.

This sets the command timeout for all plugins. If you want a command timeout for just one plugin, use the cmd-timeout plugin option, which every plugin has too. For example: -k logs.cmd-timeout=600.

Same deal as before: the plugin-specific setting wins over the global one, the same precedence logic as --plugin-timeout.

⚠️ If you crank --cmd-timeout (or -k logs.cmd-timeout) way up, you should also bump up the matching --plugin-timeout. Otherwise slow commands can easily make the plugin time out 😭
  • --namespaces NAMESPACES — 🌐 For plugins that loop over the namespaces on the system (like the networking plugin collecting ip command output for each network namespace), this limits how many namespaces get collected.

0 is the default and means no limit, so every namespace gets used.

Some plugins have their own namespaces plugin option too. If you use that, it overrides this one 🦋

  • --container-runtime RUNTIME — 📦 Forces the RUNTIME you name to be the default runtime that plugins use to pull data from containers and container images. The default is auto, which lets the local policy decide which runtime is the default (useful when you have several runtimes installed and active).

If no container runtimes are active, this option gets ignored. But if there are active runtimes and none of them match RUNTIME, sos will abort 💀

Setting it to none, off, or disabled tells plugins to NOT use any active runtimes for collection. Runtime-specific plugins (like the podman or docker plugins) will still collect general info about the runtime when disabled, they just won't look at existing containers or images.

Default: auto (policy determined)

  • --case-id NUMBER — 🗂️ Attaches a case identifier to the archive. Identifiers can include alphanumeric characters, commas, and periods (.).
  • --build — 🧱 Skips archiving the copied data. This leaves an uncompressed archive sitting around as a temporary file or directory tree.
  • --debug — 🐛 Turns on interactive debugging with the Python debugger. If there's an exception in sos or plugin code, it'll drop you into the pdb shell 🔍
  • --dry-run — 👀 Runs the plugins as normal, but doesn't collect any file content, command output, or string data from the system. The resulting logs still show what sos would have done without the dry run option, so it's great for previewing.
  • --estimate-only — 📏 Estimates how much disk space sos report will need. This is a lifesaver for stopping the sos report working dir from eating all your free disk space. There's no plugin data available at the end, though.

Plugins get collected one at a time. The size of the collected files and command outputs is calculated, and each plugin's files get deleted right before the next plugin starts. Even so, this can still eat all your free space, so be careful!

Heads up: the estimates might not be super accurate on heavily used systems, since things can change between the estimate and the real run. There's also some difference between how the estimate is done (using the stat command) and the other commands used (like du).

Rule of thumb: reserve at least double the estimate 🫶

  • --upload — ☁️ If you use this, sos tries to upload the finished archive to a vendor-defined location.

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

You might get prompted for a username and password if the vendor hasn't defined them. If you don't provide credentials, sos still runs and makes the archive, it just skips the automatic upload and leaves it to you to upload manually.

The archive stays on your local filesystem even after a successful upload 📁

Depending on your distro or the vendor policy sos detects, there might be dependencies that aren't strictly required when the package gets installed. For example, HTTPS uploads need the python-requests library. Without it, HTTPS uploads just won't be attempted 🥲

  • --upload-url URL — 🔗 If a vendor doesn't give you a default upload location, or you'd like to send the archive somewhere else, put the address here.

The URL MUST include a protocol. Right now, uploading works over HTTPS, SFTP, and FTP.

If your destination server listens on a non-standard port, put that port in the URL too 🎀

  • --upload-user USER — 👤 If a vendor doesn't set a default user for uploads, you can specify your username here.

If you don't use this option, you ask for an upload, and there's no vendor default, you'll get prompted for a username. If you use --batch and leave this out, no username gets collected, so uploads will fail when there's no vendor default. Oof 😭

You can also set the username with the SOSUPLOADUSER environment variable. When that's set, sos won't prompt for a username, so you can use --batch as long as all the other required values (case number, upload password) are provided too 💖

This option gets ignored when uploading to the Red Customer Portal or the Red Hat Secure FTP server, since those use web token authentication instead 🌸

  • --upload-pass PASS — 🤫 Sets the password for authenticating with the destination server.

If you leave this out and request an upload, you'll get prompted for a password.

With --batch, that prompt doesn't happen. So uploads will probably fail unless you use this option.

🚨 Be careful! This can put the plaintext password in ps output, and sos might collect that output and stick it in the archive. If you need to provide a password for uploading, it's strongly recommended that you DON'T use --batch, and instead type the password in when prompted rather than passing it with this option 🙈

You can also pass this value through the SOSUPLOADPASSWORD environment variable 🔐 If that's set, sos won't prompt you for a password at all, so --batch works too, as long as you've also given it every other required value (case number and upload user) 💖

This option gets ignored when you're uploading to the Red Customer Portal or the Red Hat Secure FTP server. Those use web token authentication instead ✨

  • --upload-directory DIR — Pick the directory you want to upload to 📂 You'll need this if there's no vendor default location, or if your destination server doesn't let you write to / 🙈
  • --upload-method METHOD — Choose the HTTP method for uploading to the --upload-url you gave. The valid values are 'auto' (the default), 'put', and 'post' 🦋 With 'auto', sos uses whatever method the policy-default upload location requires, if there is one 💅
This option does nothing for upload protocols other than HTTPS, so don't expect it to change anything for FTP or SFTP 🙅‍♀️
  • --upload-no-ssl-verify — Turn off SSL verification for HTTPS uploads 🔓 This is handy when you need to upload somewhere with a self-signed certificate, or a certificate your local system just doesn't trust 🥺

By default, sos verifies SSL against every upload location, so you're safe unless you opt out 🛡️

  • --upload-protocol PROTO — Manually set the protocol for the target upload-url 🌈 Usually sos figures this out from the address, as long as the protocol is actually in it, like 'https://example.com' 🔍 When you use this option, sos skips that check and uses the method for whichever PROTO you picked 🎯

On RHEL systems, setting this to sftp skips the first try at the Red Hat Customer Portal and only uploads to Red Hat's SFTP server, which is usually the fallback target 🫶

The valid values for PROTO are 'auto' (the default), 'https', 'ftp', and 'sftp' 💜

  • --experimental — Turns on plugins marked as experimental 🧪 Heads up, these might not have been tested on this port yet, or they could still be in active development, so they may be a little unpredictable 💀
  • --help — Shows the usage message 📖

✨ SEE ALSO ✨

Check these out for more 🧚

💌 MAINTAINER

This one lives on GitHub at https://github.com/sosreport/sos 🐙

🎀 AUTHORS & CONTRIBUTORS

Everyone who helped is listed in the AUTHORS file in the package documentation 🫶

Okay bestie, that's the whole page 🌸 Thanks for reading all the way through, you're literally the best 💖 SOS_REPORT(1), last touched Mon Mar 25 2013, and I'm obsessed with you for sticking around 💅✨

📦 where this page comes from