sos(1)

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

💖 sos(1) — the manual, but make it a group chat 💖

okay bestie, come sit with me, we're gonna talk about sos from the General Commands Manual. this is the unified tool for collecting system logs and other debug info, and honestly? she ate. 🍓

✨ NAME ✨

sos — a unified tool for collecting system logs and other debug information. periodt. 💅

🦋 SYNOPSIS 🦋

sos component [options]

that's it. that's the whole vibe. you pick a component, you give it options, she does the thing. 🌸

👑 DESCRIPTION 👑

so sos is a diagnostic data collection utility, and the girlies using it are system administrators, support representatives, and, like, people in that whole ecosystem — it's there to help troubleshoot issues with a system or, honestly, a whole group of systems. 🫶

the most well known function? that's sos report. iconic. everyone knows her.

an sos archive is typically requested by support organizations so they can collect baseline configuration and system data to, like, begin the troubleshooting process. it's the opening scene of the whole investigation. 🔥

🎀 COMPONENTS 🎀

sos supports several subcommands, aka components. each one hands you a different set of info. the supported ones are, and I quote the universe:

  • report — report generates an archive of system information including configuration files and command output. what goes into that report is based on plugins that get activated automatically when certain criteria is detected — stuff like installed packages, files, services, or system architecture.

see sos report --help and man sos-report for more info.

may also be invoked via the alias rep. (short queen energy.)

  • collect — collect is used to capture reports on multiple systems simultaneously. these systems can either be defined by the user at the command line and/or defined by clustering software that exists either on the local system or on a "primary" system that is able to inform about other nodes in the cluster. so like, she'll go ask everyone. no cap.

when running collect, sos report will be run on the remote nodes, and then the resulting archives get copied from those nodes over to the local system that's running sos collect. after that, the archives are removed from the remote systems. clean up after yourself bestie 💅

see sos collect --help and man sos-collect for more info.

may also be invoked via the alias sos collector or the deprecated command sos-collector.

  • clean|cleaner|mask — this subcommand takes input of either 1) an sos report tarball, 2) a collection of sos report tarballs such as from collect, or 3) the unpackaged directory of an sos report — and then it obfuscates potentially sensitive system information that is not covered by the standard postprocessing of sos report. she's covering the gaps, okay? 🧚

such data includes IP addresses, networks, MAC addresses, and more. data obfuscated by this command will remain consistent throughout the report and across reports provided in the same invocation. plus, care is taken to maintain network topology relationships between matched data items. consistent and thorough, she's giving main character energy. ✨

see sos clean --help and man sos-clean for more info.

may be invoked via either sos clean, sos cleaner, sos mask, or via the --clean, --cleaner or --mask options for report and collect.

  • help — this subcommand is used to retrieve more detailed information on the various SoS commands and components than is directly available in either other manpages or --help output. so when --help isn't enough, she's the bigger sister. 🙈

see sos help --help and man sos-help for more info.

  • upload — this subcommand uploads an input file to either a distribution-defined or a user-defined target. the file can be an SOS archive, or literally any other type of file, such as a vmcore or log file. send it, bestie. 🚀

see sos upload --help and man sos-upload for more info.

💅 GLOBAL OPTIONS 💅

sos components provide their own set of options, however the following ones are available to be set across all components. universal icons, if you will. 👑

  • --batch — do not prompt interactively; the user will not be prompted for any data. no questions, no vibe check, just go. 💀
  • --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. remember that.

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 info. ⬇️

  • --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). so like, be consistent or it's not gonna work. 😭

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. phew. 🫶

  • --encrypt-pass PASS — the same as --encrypt-key, but use the provided PASS for symmetric encryption rather than key-pair encryption.
  • --config-file CONFIG — specify alternate configuration file.
  • -s, --sysroot SYSROOT — specify an alternate root file system path.
  • --tmp-dir DIRECTORY — specify alternate temporary directory to copy data during execution.
  • --threads THREADS — specify the number of threads sos report will use for concurrency. defaults to 4.
  • -v, --verbose — increase logging verbosity. may be specified multiple times to enable additional debugging messages.

the following table summarizes the effects of different verbosity levels:

  • 1 (-v) — enable debug messages for sos.log. show individual plugins starting.
  • 2 (-vv) — also print debug messages to console.
  • 3 (-vvv) — enable debug messages for archive file operations. note this will dramatically increase the amount of logging. 💀 (fr fr, she is not kidding)
  • -q, --quiet — only log fatal errors to stderr.
  • -z, --compression-type {auto|xz|gzip|none} — compression type to use when compressing the final archive output. if the value none is given, the tar archive will be written directly with no compression.
  • --help — display usage message.

🐚 SHELL COMPLETION 🐚

completion for bash is installed to /usr/share/bash-completion/completions/sos. candidates, such as plugin names, presets, profiles and help topics, are generated by sos itself on the local system and do not require root privileges. you don't need to be That Girl to tab-complete, bestie. 🌈

🌸 SEE ALSO 🌸

🦋 MAINTAINER 🦋

maintained on GitHub at https://github.com/sosreport/sos — go say hi, star the repo, it's free. ⭐

💜 AUTHORS & CONTRIBUTORS 💜

see AUTHORS file in the package documentation. the whole squad is in there. 👑

okay that's the whole page!! this bad girl is from the General Commands Manual, and the footer lowkey says April 2020 — so yeah, sos(1), April 2020, and she's still serving. go collect some logs, bestie, ily, bye!! 💖✨🎀

📦 where this page comes from