Use sos help to inspect report plugins safely

You will learn how to use sos help to inspect the installed SoS command, its report plugins and distribution policies before collecting diagnostic data. This is a read-only workflow. It takes about five minutes, plus however long you need to follow a plugin's own notes.

Before you start

The examples below were checked against sosreport 4.10.2-0ubuntu0~24.04.1, installed as sos 4.10.2. The help catalogue is version-specific: plugin names and their detailed sections can change between releases and distributions.

You need the sos command in your PATH. Ordinary users can read help. Collecting a report is a separate operation and normally needs root privileges, so do not add sudo while you are only inspecting documentation.

Checkpoint: confirm the command and release

1. Check which executable will run and ask it for its version.

command -v sos
sos --version

On this installation the executable is /usr/bin/sos and the package is sosreport 4.10.2-0ubuntu0~24.04.1. If command -v prints nothing, stop here and install or enable the package through your normal system administration process. Do not copy a report command from another host until you know which release it uses.

Read the top-level report guidance

2. Ask for the detailed help section for the main reporting command.

sos help report

The section explains that sos report builds a troubleshooting archive from plugins. A plugin declares files to copy and commands to run, and the active distribution policy can alter what gets collected. It also points you towards report.plugins, a named plugin section and policies.

On a non-interactive shell, this command can appear to print nothing or can report a terminal-width error because the installed help renderer formats text for a terminal. Re-run it from a normal terminal. A reliable check is:

script -qec 'stty cols 120 rows 40; sos help report' /dev/null

That workaround allocates a temporary pseudo-terminal and changes no system configuration. The visible escape sequences in some captured output are terminal formatting, not part of the help topic.

Find the plugin naming pattern

3. Read the catalogue section before guessing a plugin name.

sos help report.plugins

The topic syntax is hierarchical: command.component.entity, with the component and entity optional. For report help, that means report describes the command, report.plugins describes plugin design, and report.plugins.PLUGIN asks for one plugin. The placeholder is not literal. Replace PLUGIN with a real module name from the installed SoS package or from the list shown by the catalogue.

For example, the installed package contains a kernel plugin. Inspect it like this:

script -qec 'stty cols 120 rows 40; sos help report.plugins.kernel' /dev/null

A successful section normally describes the plugin's purpose, the data it collects, options it accepts and any edge cases. That information is more useful than assuming that a plugin name means the same thing on every host.

Use help to answer a collection question

4. Start with the narrowest topic that matches the question you have.

• Use sos help report when you need the collection model or the boundary between help and report execution.
• Use sos help report.plugins when you need to understand how plugins contribute files and command output.
• Use sos help report.plugins.kernel, or another installed plugin name, when you need plugin-specific behaviour.
• Use sos help policies when the same command behaves differently across distributions.

To inspect another top-level command, use the command's topic directly. For example, the manpage documents sos help clean, sos help mask and sos help collect. The implementation maps clean and mask to the cleaner component, and collect to the collector component. This is why the help topic is not always the same as the internal module name.

Handle missing or misleading topics

5. Check the exact topic spelling and the installed package before treating a missing section as a software failure.

A missing plugin can produce a message such as No help section found for '...', while a module that cannot be imported can produce Could not load help for '...'. Both are diagnostic messages, not instructions to run a collection. Re-check the parent section, then compare the package version with the host where the topic was documented.

Some topics need a real terminal even when the command itself exits successfully. If output is empty, use the script form above. If the topic still fails, use sos help with no topic to display the help component's own search guidance, then try the hierarchy it shows. Do not invent a dot-separated suffix: only use names exposed by this installation.

Keep inspection separate from collection

sos help reads help metadata. It does not create an archive, copy configuration files or upload anything. The report command does all of those kinds of work, and its manpage warns that root privileges are required for collections.

Before moving from inspection to collection, read the relevant sos report --help output and the sos-report(1) manpage for the host. Treat a report as potentially sensitive: it can contain command output and configuration material. Check your organisation's handling rules before storing or sharing it. If you accidentally start a collection, stop it with Ctrl-C when safe, then check the current directory and the command's output for any archive it may already have created. Remove that archive only under your normal retention and approval process; deletion is not an automatic undo for a copy that was already uploaded elsewhere.