sos gathers a system's support data into one archive, and it must run as root

A collector for distributions, not a script you write yourself

sos is described as an extensible, portable, support data collection tool primarily aimed at Linux distributions and other UNIX-like operating systems. The one line summary in the setup script calls it a set of tools to gather troubleshooting information from a system.

That framing explains the design. The output of sos is an archive that a support engineer can open on their own machine, days later, without access to the original host. Everything in the design follows from that: the collection is broad by default, the archive is self-describing, and the tool is built to run as root so that it can read the places where interesting problems live.

The distribution angle is the important one. A user filing a bug against a Linux distribution does not have a shell on the machine, and the distribution's support engineer needs one artefact rather than a checklist of things to ask for. sos is the mechanism that makes that exchange work, and the reason it lives in every major distribution's package repository is that it is the agreed format for that handover.

The packaging badges in the README make the reach explicit, with the project published as a Fedora package, an Ubuntu source package, a Debian package for distribution, a Snap, and a Python 3.8 or newer requirement. The project is GPL-2.0, the primary language is Python, and the last push was on 2026-10-19, with 4.12.1 released the same day as the 4.12.0 release in August.

Plugins and policies are how sos decides what to collect

The extension mechanism is the heart of the project, and the README links three separate guides for it: how to write a plugin, how to write a policy, and plugin options.

A plugin is a unit of collection. A policy is the mechanism that decides which plugins run and how they are configured. That two-layer structure is what lets a distribution support differ from the upstream defaults, and it is why the README points people who want to support a new distribution at those pages rather than at the source.

The plugin set is broad in practice, which is the point of a support collector. The repository layout reflects a tool with many moving parts: a sos package directory, a bin directory, a docs directory, a man directory with man pages, a po directory for translations, a debian directory, a snap directory, a completions directory with bash completion, a tmpfiles directory, a tests directory, and a setup.py that installs several man pages, the configuration file, the bash completion and, on non-Debian and non-Ubuntu systems, the licence and documentation.

The setup file also shows how the tool is composed of more than one command. The installed man pages are sos-report.1, sos.1, sos-collect.1, sos-clean.1, sos-mask.1, sos-help.1 and sos-upload.1, alongside sos.conf.5 for the configuration file, and the entry point installed as a script is bin/sos. The runtime dependencies are small: pexpect, pyyaml, and packaging on recent Python versions, with a comment in the setup file explaining that the packaging dependency is only declared on recent Python versions to avoid a packaging dependency on older RHEL releases.

Running a report, and the fact that it needs root

The installation section leads with the manual route, and it is genuinely manual: you can run the tool straight from a git checkout without installing anything.

$ sudo ./bin/sos report -l

That particular invocation is the plugin listing rather than a collection, and the README presents it as the way to see a list of all available plugins and plugin options. The plain report command is the same form without the -l flag.

Two things are worth drawing out. The first is the sudo. The tool reads system logs, service configuration, kernel state and hardware inventory, and most of that is not world readable, so a full report is a root operation by construction. The second is the plugin listing as a first-class step, because it is how you find out what will be collected before you collect it.

The pre-built packaging routes are the ones most users will actually take. Fedora and RHEL users install with dnf, Debian users with apt using the sosreport package name, Ubuntu 14.04 LTS and above with sudo apt install sosreport, and there is a Snap route with snap install sosreport --classic. The Debian and Ubuntu package names differ from the upstream project name, which is worth knowing when you write runbooks.

There is also a source install path with python3 setup.py install, run as root.

The other half of the tool set: collect, clean, mask and upload

The man page list is a better description of the tool's scope than the phrase support data collection, because it names the separate operations.

sos report is the collector, and it is the one most people invoke. sos collect is the variant that runs a series of collection steps, which is what you want when a single snapshot is not enough. sos clean removes the collected data, which matters on a host you are about to hand back. sos mask is the redaction step, and it is the one that deserves attention. sos upload sends the archive somewhere, and sos help is the entry point for the rest.

The masking operation is the part of the design that a security review should focus on. A support archive is full of things that should not leave a site: hostnames, addresses, keys in configuration files, user names. A masking step exists precisely because a raw archive is not safe to hand over, and a workflow that treats the archive as safe to send without running the mask step first is a workflow that will eventually leak something.

The configuration file is sos.conf, with a man page of its own at sos.conf.5, and the setup script installs it into the config directory along with a tmpfiles configuration, tmpfilesd-sos-rh.conf, which is the systemd mechanism for creating and cleaning up files under /tmp. That detail says something about the tool's assumptions: it is expected to leave temporary data on the host, and to clean it up.

The commands are also documented in the shell completion file, which the setup script installs into share/bash-completion/completions, so that a user tab-completing sos sees the subcommands and the plugin listing option.

The upstream workflow, and how a change is validated

The README is unusually explicit about how a contribution is checked, and that is a reasonable proxy for how a serious project operates.

Before sending a pull request, it is advisable to check your contribution against the flake8 and pylint linter, the unit tests and the stage one avocado test suite. The commands are run from within the git checkout, and the stage one suite is run as root:

$ tox -e flake8
$ tox -e pylint
$ tox -e unit_tests

The README notes that the avocado test suite will generate and remove several reports over its execution, and that no changes are made to your local system. All contributions must pass the entire test suite before being accepted.

The contribution mechanics are also spelled out. Patches can be submitted via the mailing list or as GitHub pull requests, and if using GitHub you are asked to make sure your branch applies to the current main branch as a fast forward merge, without creating a merge commit, using the git rebase command to update your branch if necessary. There is a contributor guidelines page referenced for formatting patches and commit messages.

Development happens on the main branch, and the clone command is git clone [email protected]:sosreport/sos.git. The documentation is generated with Sphinx and published through Read the Docs, and to generate the HTML locally you run tox -e docs, which by default builds into docs/_build.

Communication happens in Matrix and Libera.Chat, in the #sosreport:matrix.org and #sos rooms respectively, and the README notes the two are bridged so joining either is sufficient. It also records that the Freenode #sos room is no longer used by the project, which is a small but real piece of onboarding information for anyone following an old thread.

Where sos is the wrong tool

Three limits, and they are worth stating plainly because the tool is widely used and its scope is easy to over-read.

The first is that it is a one-shot collector, not an agent. There is no long-running process watching a host, and no history. A support engineer who receives a report has a snapshot of one moment, and a problem that only appears under load or at a particular hour needs that context gathered differently, by the monitoring stack rather than by sos.

The second is the root requirement, and it is not a small one. Because a full report reads system-wide locations, it runs as root, which means it can also read things it does not need, and the archive it produces can contain secrets from configuration files that nobody intended to share. The masking step exists to manage that, but it is a step, and a workflow that skips it has a data leak with a support ticket attached.

The third is that the plugin and policy model is a maintenance commitment for whoever ships it. The whole point of the extension mechanism is that distributions and support organisations customise what is collected, and that is also a burden: policies drift, plugins need updating as a platform's layout changes, and a policy that was correct for one distribution release can quietly collect the wrong files for the next. The tool is well suited to the organisations that already maintain packaging for their distribution, and less suited to a small team that just wants to grab some logs once.

The alternative approach, and it is the one to consider for a one-off, is to gather the specific artefacts yourself with a short script and a tar command. The difference in approach is that you get exactly what you need and nothing else, at the cost of not having a standard format, a plugin catalogue, or the coverage of a maintained collector. For a support organisation handling many machines and many platforms, that standardisation is worth the root requirement and the policy upkeep. For one engineer with one broken server, it is not.

Editorial conclusion

Adopt sos if you support Linux systems and need a reproducible, archivable snapshot of a machine's state that a developer can inspect offline, since the plugin and policy model is what makes the output consistent across distributions and a support engineer can extend it for their own platform. Do not adopt it as a monitoring agent, because it is a one-shot collector rather than a daemon, and do not run it on a production host without checking what the enabled plugins collect, because the tool's own nature is to read broadly. Verify first that the version you run matches the one your distribution ships, since 4.12.1 is the current release, that the plugins enabled on your platform match what you intend to share, and that the masking step is applied before an archive leaves your site, because the report is designed to contain everything a support engineer needs.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. sosreport/sos on GitHub