sos.report.plugins — Plugin Interface

This exports methods available for use by plugins for sos

class sos.report.plugins.AzurePlugin

Bases: PluginDistroTag

Tagging class for Azure Linux

class sos.report.plugins.CosPlugin

Bases: PluginDistroTag

Tagging class for Container-Optimized OS

class sos.report.plugins.DebianPlugin

Bases: PluginDistroTag

Tagging class for Debian Linux

class sos.report.plugins.ExperimentalPlugin

Bases: PluginDistroTag

Tagging class that indicates that this plugin is experimental

class sos.report.plugins.IndependentPlugin

Bases: PluginDistroTag

Tagging class for plugins that can run on any platform

class sos.report.plugins.OpenEulerPlugin

Bases: PluginDistroTag

Tagging class for openEuler linux distributions

class sos.report.plugins.Plugin(commons)

Bases: object

This is the base class for sos report plugins. Plugins should subclass this and set the class variables where applicable.

Parameters:

commons (dict) – A set of information that is shared internally so that plugins may access the same dataset. This is provided automatically by sos

Each Plugin() subclass should also subclass at least one tagging class, e.g. RedHatPlugin, to support that distribution. If different distributions require different collections, each distribution should have its own subclass of the Plugin that also subclasses the tagging class for their respective distributions.

Variables:

• plugin_name (str) – The name of the plugin, will be returned by name()

• packages (tuple) – Package name(s) that, if installed, enable this plugin

• files (tuple) – File path(s) that, if present, enable this plugin

• commands (tuple) – Executables that, if present, enable this plugin

• kernel_mods (tuple) – Kernel module(s) that, if loaded, enable this plugin

• services (tuple) – Service name(s) that, if running, enable this plugin

• architectures (tuple, or None) – Architecture(s) this plugin is enabled for. Defaults to ‘none’ to enable on all arches.

• profiles (tuple) – Name(s) of profile(s) this plugin belongs to

• plugin_timeout (int) – Timeout in seconds for this plugin as a whole

• cmd_timeout (int) – Timeout in seconds for individual commands

add_alert(alertstring)

Add an alert to the collection of alerts for this plugin. These will be displayed in the report

Parameters:

alertstring (str) – The text to add as an alert

add_cmd_output(cmds, suggest_filename=None, root_symlink=None, timeout=None, stderr=True, chroot=True, runat=None, env=None, binary=False, sizelimit=None, pred=None, subdir=None, changes=False, foreground=False, tags=[], priority=10, cmd_as_tag=False, container=None, to_file=False, runas=None, snap_cmd=False, runtime=None)

Run a program or a list of programs and collect the output

Output will be limited to sizelimit, collecting the last X amount of command output matching sizelimit. Unless suggest_filename is set, the file that the output is saved to will match the command as it was executed, and will be saved under sos_commands/$plugin

Parameters:

• cmds (str or a list of strings) – The command(s) to execute

• suggest_filename (str) – Override the name of the file output is saved to within the archive

• root_symlink (str) – If set, create a symlink with this name in the archive root

• timeout (int) – Timeout in seconds to allow each cmd to run for

• stderr (bool) – Should stderr output be collected

• chroot (bool) – Should sos chroot the cmds being run

• runat (str) – Run the cmds from this location in the filesystem

• env (dict) – Set environment variables for the cmds being run

• binary (bool) – Is the command expected to produce binary output

• sizelimit (int) – Maximum amount of output in MB to save

• pred (SoSPredicate) – A predicate to gate if cmds should be collected or not

• subdir (str) – Save output to this subdirectory, within the plugin’s directory under sos_commands

• changes (int) – Do cmds have the potential to change system state

• foreground (bool) – Should the cmds be run in the foreground, with an attached TTY

• tags (str or a list of strings) – A tag or set of tags to add to the metadata entries for the cmds being run

• priority (int) – The priority with which this command should be run, lower values will run before higher values

• cmd_as_tag (bool) – Should the command string be automatically formatted to a tag?

• container (str) – Run the specified cmds inside a container with this ID or name

• to_file (bool) – Should command output be written directly to a new file rather than stored in memory?

• runas (str) – Run the cmd as the runas user

• snap_cmd (bool) – Are the commands being run from a snap?

• runtime (str) – Specific runtime to use to run container cmd

add_cmd_tags(tagdict)

Retroactively add tags to any commands that have been run by this plugin that match a given regex

Parameters:

tagdict (dict) – A dict containing the command regex and associated tags

tagdict takes the form of {cmd_regex: tags}, for example to tag all commands starting with foo with the tag bar, use {‘foo.*’: [‘bar’]}

add_container_logs(containers, get_all=False, **kwargs)

Helper to get the logs output for a given container or list of container names and/or regexes.

Supports passthru of add_cmd_output() options

Parameters:

• containers (str or list of strs) – The name of the container to retrieve logs from, may be a single name or a regex

• get_all (bool) – Should non-running containers also be queried? Default: False

• kwargs – Any kwargs supported by add_cmd_output() are supported here

add_copy_spec(copyspecs, sizelimit=None, maxage=None, tailit=True, pred=None, tags=[], container=None, runas=None)

Add a file, directory, or globs matching filepaths to the archive

Parameters:

• copyspecs (str or a list of strings) – Files, directories, or globs matching filepaths

• sizelimit (int) – Limit the total size of collections from copyspecs to this size in MB

• maxage (int) – Collect files with mtime not older than this many hours

• tailit (bool) – Should a file that exceeds sizelimit be tail’ed to fit the remaining space to meet sizelimit

• pred (SoSPredicate) – A predicate to gate if copyspecs should be collected

• tags (str or a list of strings) – A tag or set of tags to add to the metadata information for this collection

• container (str or a list of strings) – Container(s) from which this file should be copied

• runas (str) – When collecting data from a container, run it under this user.

copyspecs will be expanded and/or globbed as appropriate. Specifying a directory here will cause the plugin to attempt to collect the entire directory, recursively.

If container is specified, copyspecs may only be explicit paths, not globs as currently container runtimes do not support glob expansion as part of the copy operation.

Note that sizelimit is applied to each copyspec, not each file individually. For example, a copyspec of ['/etc/foo', '/etc/bar.conf'] and a sizelimit of 25 means that sos will collect up to 25MB worth of files within /etc/foo, and will collect the last 25MB of /etc/bar.conf.

add_custom_text(text)

Append text to the custom text that is included in the report. This is freeform and can include html.

Parameters:

text (str) – The text to include in the report

add_default_cmd_environment(env_vars)

Add or modify a specific environment variable in the set of default environment variables used by this Plugin.

Parameters:

env_vars (dict) – The environment variables to add to the current set of env vars in use

add_default_collections()

Based on the class attrs defined for plugin enablement, add a standardized set of collections before we call the plugin’s own setup() method.

add_device_cmd(cmds, devices, timeout=None, sizelimit=None, chroot=True, runat=None, env=None, binary=False, prepend_path=None, whitelist=[], blacklist=[], tags=[], priority=10, subdir=None)

Run a command or list of commands against devices discovered during sos initialization.

Any commands specified by cmd will be iterated over the list of the specified devices. Commands passed to this should include a ‘%(dev)s’ variable for substitution.

Parameters:

• cmds (str or a list of strings) – The command(s) to run against the list of devices

• devices (str or a list of devices or device paths.) – The device paths to run cmd against. This should be either a list of devices/device paths or a key in the devices dict discovered by sos during initialization.

• timeout (int) – Timeout in seconds to allow each cmd to run

• sizelimit (int) – Maximum amount of output to collect, in MB

• chroot (bool) – Should sos chroot the command(s) being run

• runat (str) – Set the filesystem location to execute the command from

• env (dict) – Set environment variables for the command(s) being run

• binary (bool) – Is the output collected going to be binary data

• prepend_path (str or None) – The leading path for block device names

• whitelist (list of str) – Limit the devices the cmds will be run against to devices matching these item(s)

• blacklist (list of str) – Do not run cmds against devices matching these item(s)

• subdir (str) – Write the command output to this subdir within the Plugin directory

add_dir_listing(paths, tree=False, recursive=False, chroot=True, env=None, sizelimit=None, pred=None, subdir=None, tags=[], runas=None, container=None, suggest_filename=None, extra_opts=None)

Used as a way to standardize our collections of directory listings, either as an output of ls or tree depending on if the tree parameter is set to True.

This is ultimately a wrapper around add_cmd_output() and supports several, but not all, of the options for that method.

Parameters:

• paths (str or a list of ``str``s) – The path(s) to collect a listing for

• tree (bool (default: False)) – Collect output with tree instead of ls

• recursive (bool (default: False)) – Recursively list directory contents with ls

add_env_var(name)

Add an environment variable to the list of to-be-collected env vars.

Collected environment variables will be saved to an environment file in the archive root, and any variable specified for collection will be collected in lowercase, uppercase, and the form provided

Parameters:

name (str) – The name of the environment variable to collect

add_file_tags(tagdict)

Apply a tag to a file matching a given regex, for use when a file is copied by a more generic copyspec.

Parameters:

tagdict (dict) – A dict containing the filepatterns to match and the tag(s) to apply to those files

tagdict takes the form {file_pattern: tag}, E.G. to match all bond devices from /proc/net/bonding with the tag bond, use {‘/proc/net/bonding/bond.*’: [‘bond’]}

add_forbidden_path(forbidden)

Specify a path, or list of paths, to not copy, even if it’s part of an add_copy_spec() call

Parameters:

forbidden (str or a list of strings) – A filepath to forbid collection from

add_journal(units=None, boot=None, since=None, until=None, lines=None, allfields=False, output=None, timeout=None, identifier=None, catalog=None, sizelimit=None, pred=None, tags=None, priority=10)

Collect journald logs from one of more units.

Parameters:

• units (str or a list of strings) – Which journald units to collect

• boot (str) – A boot index using the journalctl syntax. The special values ‘this’ and ‘last’ are also accepted.

• since (str) – Start time for journal messages

• until (str) – End time forjournal messages

• lines (int) – The maximum number of lines to be collected

• allfields (bool) – Include all journal fields regardless of size or non-printable characters

• output (str) – Journalctl output control string, for example “verbose”

• timeout (int) – An optional timeout in seconds

• identifier (str) – An optional message identifier

• catalog (bool) – Augment lines with descriptions from the system catalog

• sizelimit (int) – Limit to the size of output returned in MB. Defaults to the value of –log-size.

add_service_status(services, **kwargs)

Collect service status information based on the InitSystem used

Parameters:

• services (str or a list of strings) – Service name(s) to collect statuses for

• kwargs – Optional arguments to pass to add_cmd_output (timeout, predicate, suggest_filename,..)

add_string_as_file(content, filename, pred=None, plug_dir=False, tags=[])

Add a string to the archive as a file

Parameters:

• content (str) – The string to write to the archive

• filename (str) – The name of the file to write content to

• pred (SoSPredicate) – A predicate to gate if the string should be added to the archive or not

• plug_dir (bool) – Should the string be saved under the plugin’s dir in sos_commands/? If false, save to sos_strings/

• tags (str or a list of strings) – A tag or set of tags to add to the manifest entry for this collection

architectures = None

archive = None

check_enabled()

This method will be used to verify that a plugin should execute given the condition of the underlying environment.

The default implementation will return True if none of class.files, class.packages, nor class.commands is specified. If any of these is specified the plugin will check for the existence of any of the corresponding paths, packages or commands and return True if any are present.

For plugins with more complex enablement checks this method may be overridden.

Returns:

True if the plugin should be run for this system, else False

Return type:

bool

check_is_architecture()

Checks whether or not the system is running on an architecture that the plugin allows. If not architecture is set, assume plugin can run on all arches.

Returns:

True if the host’s architecture allows the plugin to run, else False

Return type:

bool

check_process_by_name(process)

Checks if a named process is found in /proc/[0-9]*/cmdline.

Parameters:

process (str) – The name of the process

Returns:

True if the process exists, else False

Return type:

bool

check_timeout()

Checks to see if the plugin has hit its timeout.

This is set when the sos.collect_plugin() method hits a timeout and terminates the thread. From there, a Popen() call can still continue to run, and we need to manually terminate it. Thus, check_timeout() should only be called in sos_get_command_output().

Since sos_get_command_output() is not plugin aware, this method is handed to that call to use as a polling method, to avoid passing the entire plugin object.

Returns:

True if timeout has been hit, else False

Return type:

bool

cmd_predicate = None

cmd_timeout = 300

cmdtags = {}

property cmdtimeout

Returns either the default command timeout value, the value as provided on the commandline via -k plugin.cmd-timeout=value, or the value of the global –cmd-timeout option.

collect()

If a plugin needs to manually compile some data for a collection, that should be specified here by overriding this method.

These collections are run last during a plugin’s execution, and as such are more likely to be interrupted by timeouts than file or command output collections.

collect_cmd_output(cmd, suggest_filename=None, root_symlink=False, timeout=None, stderr=True, chroot=True, runat=None, env=None, binary=False, sizelimit=None, pred=None, changes=False, foreground=False, subdir=None, tags=[], runas=None)

Execute a command and save the output to a file for inclusion in the report, then return the results for further use by the plugin

Parameters:

• cmd (str) – The command to run

• suggest_filename – Filename to use when writing to the archive

• suggest_filename – str

• root_symlink (bool) – Create a symlink in the archive root

• timeout (int) – Time in seconds to allow a cmd to run

• stderr (bool) – Write stderr to stdout?

• chroot (bool) – Perform chroot before running cmd?

• runat (str) – Run the command from this location, overriding chroot

• env (dict) – Environment vars to set for the cmd

• binary (bool) – Is the output in binary?

• sizelimit (int) – Maximum size in MB of output to save

• subdir (str) – Subdir in plugin directory to save to

• changes (bool) – Does this cmd potentially make a change on the system?

• foreground (bool) – Run the cmd in the foreground with a TTY

• tags (str or a list of strings) – Add tags in the archive manifest

• runas (str) – Run the cmd as the runas user

Returns:

cmd exit status, output, and the filepath within the archive output was saved to

Return type:

dict

collect_plugin()

Collect the data for a plugin.

collection_file(fname, subdir=None, tags=[])

Handles creating and managing files within a plugin’s subdirectory within the archive, and is intended to be used to save manually compiled data generated during a plugin’s _collect_manual() step of the collection phase.

Plugins should call this method using a with context manager.

Parameters:

• fname (str) – The name of the file within the plugin directory

• subdir (str) – If needed, specify a subdir to write the file to

• tags (str or list of str) – Tags to be added to this file in the manifest

commands = ()

container_exists(name, runtime=None)

If a container runtime is present, check to see if a container with a given name is currently running

Parameters:

• name (str) – The name or ID of the container to check presence of

• runtime (str) – The runtime to use

Returns:

True if name exists, else False

Return type:

bool

container_path_exists(path, container, runas=None)

Check if a path exists inside a container before collecting a dir listing

Parameters:

• path (str) – The canonical path for a specific file/directory in a container

• container (str) – The container where to check for the path

Returns:

True if the path exists in the container, else False

Return type:

bool

containers = ()

default_enabled()

This decides whether a plugin should be automatically loaded or only if manually specified in the command line.

classmethod display_help(section)

classmethod display_plugin_help(section)

classmethod display_self_help(section)

do_cmd_output_sub(cmd, regexp, subst)

Apply a regexp substitution to command output archived by sos

This is used to obfuscate sensitive information captured by command output collection via plugins.

Parameters:

• cmd (str) – The command name/binary name for collected output that needs to be obfuscated. Internally globbed with a leading and trailing *

• regexp (str or compile re object) – A regex to match the contents of the command output against

• subst (str) – The substitution string used to replace matches from regexp

Returns:

Number of replacements made

Return type:

int

do_cmd_private_sub(cmd, desc='')

Remove certificate and key output archived by sos report. Any matching instances are replaced with: ‘—–SCRUBBED’ and this function does not take a regexp or substituting string.

Parameters:

• cmd (str) – The name of the binary to scrub certificate output from

• desc (str) – An identifier to add to the SCRUBBED header line

Returns:

Number of replacements made

Return type:

int

do_file_private_sub(pathregex, desc='')

Scrub certificate/key/etc information from files collected by sos.

Files matching the provided pathregex are searched for content that resembles certificate, ssh keys, or similar information. Any matches are replaced with “—–SCRUBBED $desc” where desc is a description of the specific type of content being replaced, e.g. “—–SCRUBBED RSA PRIVATE KEY” so that support representatives can at least be informed of what type of content it was originally.

Parameters:

• pathregex (str) – A string or regex of a filename to match against

• desc (str) – A description of the replaced content

do_file_sub(srcpath, regexp, subst)

Apply a regexp substitution to a file archived by sos report.

Parameters:

• srcpath (str) – Path in the archive where the file can be found

• regexp (str or compiled re object) – A regex to match the contents of the file

• subst (str) – The substitution string to be used to replace matches within the file

Returns:

Number of replacements made

Return type:

int

do_path_regex_sub(pathexp, regexp, subst)

Apply a regexp substituation to a set of files archived by sos. The set of files to be substituted is generated by matching collected file pathnames against pathexp.

Parameters:

• pathexp (str or compiled re object) – A regex to match filenames within the archive

• regexp (str or compiled re object) – A regex to match against the contents of each file

• subst (str) – The substituion string to be used to replace matches

do_paths_http_sub(pathspecs)

Obfuscate Basic_AUTH URL credentials in all files in the given list. Proxy setting without protocol is ignored, since that is not recommended setting and obfuscating that one can hit false positives.

Parameters:

pathspecs (str or a list of strings) – A filepath to obfuscate credentials in

do_regex_find_all(regex, fname)

exec_cmd(cmd, timeout=None, stderr=True, chroot=True, runat=None, env=None, binary=False, pred=None, foreground=False, container=False, quotecmd=False, runas=None, runtime=None)

Execute a command right now and return the output and status, but do not save the output within the archive.

Use this method in a plugin’s setup() if command output is needed to build subsequent commands added to a report via add_cmd_output().

Parameters:

• cmd (str) – The command to run

• timeout (int) – Time in seconds to allow a cmd to run

• stderr (bool) – Write stderr to stdout?

• chroot (bool) – Perform chroot before running cmd?

• runat (str) – Run the command from this location, overriding chroot

• env (dict) – Environment vars to set for the cmd

• binary (bool) – Is the output in binary?

• pred (SoSPredicate) – A predicate to gate execution of the cmd

• foreground (bool) – Run the cmd in the foreground with a TTY

• container (str) – Execute this command in a container with this name

• quotecmd (bool) – Whether the cmd should be quoted.

• runas (str) – Run the cmd as the runas user

• runtime (str) – Specific runtime to use to execute the container command

Returns:

Command exit status and output

Return type:

dict

file_grep(regexp, *fnames)

Grep through file(s) for a specific string or regex

Parameters:

• regexp (str) – The string or regex to search for

• fnames (str, list of string, or open file objects) – Paths to grep through

Returns:

Lines matching regexp

Return type:

str

files = ()

filetags = {}

filter_namespaces(ns_list, ns_pattern=None, ns_max=None)

Filter a list of namespaces by regex pattern or max number of namespaces (options originally present in the networking plugin.)

fmt_container_cmd(container, cmd, quotecmd=False, runtime=None, runas=None)

Format a command to be executed by the loaded ContainerRuntime in a specified container

Parameters:

• container (str) – The name of the container to execute the cmd in

• cmd (str) – The command to run within the container

• quotecmd (bool) – Whether the cmd should be quoted.

• runtime (str) – The specific runtime to use to run the command within the container

• runas (str) – What user runs the container. If set, we trust the container really runs (we dont keep them atm)

Returns:

The command to execute so that the specified cmd will run within the container and not on the host

Return type:

str

generate_copyspec_tags()

After file collections have completed, retroactively generate manifest entries to apply tags to files copied by generic copyspecs

get_all_containers_by_regex(regex, get_all=False)

Get a list of all container names and ID matching a regex

Parameters:

• regex (str) – The regular expression to match

• get_all (bool) – Return all containers found, even terminated ones

Returns:

All container IDs and names matching regex

Return type:

list of tuples as (id, name)

get_cmd_output_path(name=None, make=True)

Get the path where this plugin will save command output

Parameters:

• name (str or None) – Optionally specify a filename to use as part of the command output path

• make (bool) – Attempt to create the command output path

Returns:

The path where the plugin will write command output data within the archive

Return type:

str

get_container_by_name(name, runtime=None)

Get the container ID for a specific container

Parameters:

• name (str) – The name of the container

• runtime (str) – The runtime to use

Returns:

The ID of the container if it exists

Return type:

str or None

get_container_images(runtime=None)

Return a list of all image names from the Policy’s ContainerRuntime

If runtime is not provided, use the Policy default. If the specified runtime is not loaded, return empty.

Parameters:

runtime (str) – The container runtime to use, if not using the default runtime detected by the Policy

Returns:

A list of container images known to the runtime

Return type:

list

get_container_volumes(runtime=None)

Return a list of all volume names from the Policy’s ContainerRuntime

If runtime is not provided, use the Policy default. If the specified runtime is not loaded, return empty.

Parameters:

runtime (str) – The container runtime to use, if not using the default runtime detected by the Policy

Returns:

A list of container volumes known to the runtime

Return type:

list

get_containers(runtime=None, get_all=False)

Return a list of all container IDs from the Policy ContainerRuntime

If runtime is not provided, use the Policy default

Parameters:

• runtime (str) – The container runtime to use, if not the default runtime detected and loaded by the Policy

• get_all (bool) – Return all containers known to the runtime, even those that have terminated

Returns:

All container IDs found by the ContainerRuntime

Return type:

list

get_default_plugin_opts()

get_description()

This function will return the description for the plugin

get_network_namespaces(ns_pattern=None, ns_max=None)

get_option(optionname, default=0)

Retrieve the value of the requested option, searching in order: parameters passed from the command line, set via set_option(), or the global_plugin_options dict.

optionname may be iterable, in which case this function will return the first match.

Parameters:

• optionname (str) – The name of the option to retrieve the value of

• default – Optionally provide a default value to return if no option matching optionname is found. Default 0

Returns:

The value of optionname if found, else default

get_predicate(cmd=False, pred=None)

Get the current default Plugin or command predicate.

Parameters:

• cmd (bool) – If a command predicate is set, should it be used.

• pred (SoSPredicate) – An optional predicate to pass if no command or plugin predicate is set

Returns:

pred if neither a command predicate or plugin predicate is set. The command predicate if one is set and cmd is True, else the plugin default predicate (which may be None).

Return type:

SoSPredicate or None

get_process_pids(process)

Get a list of all PIDs that match a specified name

Parameters:

process (str) – The name or regex of the process the get PIDs for

Returns:

A list of PIDs

Return type:

list

get_service_names(regex)

Get all service names matching regex

Parameters:

regex (str) – A regex to match service names against

Returns:

All service name(s) matching the given regex

Return type:

list

get_service_status(name)

Return the reported status for service $name

Parameters:

name (str) – The name of the service to check

Returns:

The state of the service according to the init system

Return type:

str

get_tags_for_cmd(cmd)

Get the tag(s) that should be associated with the given command

Parameters:

cmd (str) – The command that tags should be applied to

Returns:

Any tags associated with the command

Return type:

list

get_tags_for_file(fname)

Get the tags that should be associated with a file matching a given regex

Parameters:

fname (str) – A regex for filenames to be matched against

Returns:

The tag(s) associated with fname

Return type:

list of strings

is_installed(package_name)

Is the package $package_name installed?

Parameters:

package_name (str) – The name of the package to check

Returns:

True id the package is installed, else False

Return type:

bool

is_module_loaded(module_name)

Determine whether specified module is loaded or not

Parameters:

module_name (str) – Name of kernel module to check for presence

Returns:

True if the module is loaded, else False

Return type:

bool

is_service(name)

Does the service $name exist on the system?

Parameters:

name (str) – The name of the service to check

Returns:

True if service is present on the system, else False

Return type:

bool

is_service_disabled(name)

Is the service $name disabled?

Parameters:

name (str) – The name of the service to check

Returns:

True if service is disabled on the system, else False

Return type:

bool

is_service_enabled(name)

Is the service $name enabled?

Parameters:

name (str) – The name of the service to check

Returns:

True if service is enabled on the system, else ``False

Return type:

bool

is_service_running(name)

Is the service $name currently running?

Parameters:

name (str) – The name of the service to check

Returns:

True if the service is running on the system, else False

Return type:

bool

is_snap = False

is_snap_installed(package_name)

Is the snap package $package_name installed?

Parameters:

package_name (str) – The name of the package to check

Returns:

True if the snap package is installed, else False

Return type:

bool

kernel_mods = ()

listdir(path)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

path (str) – The canonical path for a specific file/directory

Returns:

Contents of path, if it is a directory

Return type:

list

log_skipped_cmd(cmd, pred, changes=False)

Log that a command was skipped due to predicate evaluation.

Emit a warning message indicating that a command was skipped due to predicate evaluation. If kmods or services are True then the list of expected kernel modules or services will be included in the log message. If allow_changes is True a message indicating that the missing data can be collected by using the “–allow-system-changes” command line option will be included.

Parameters:

• cmd (str) – The command that was skipped

• pred (SoSPredicate) – The predicate that caused the command to be skipped

• changes (bool) – Is the –allow-system-changes enabled

classmethod name()

Get the name of the plugin

Returns:

The name of the plugin, in lowercase

Return type:

str

option_list = []

packages = ()

path_exists(path)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

path (str) – The canonical path for a specific file/directory

Returns:

True if the path exists in sysroot, else False

Return type:

bool

path_isdir(path)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

path (str) – The canonical path for a specific file/directory

Returns:

True if the path is a dir, else False

Return type:

bool

path_isfile(path)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

path (str) – The canonical path for a specific file/directory

Returns:

True if the path is a file, else False

Return type:

bool

path_islink(path)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

path (str) – The canonical path for a specific file/directory

Returns:

True if the path is a link, else False

Return type:

bool

path_join(path, *p)

Helper to call the sos.utilities wrapper that allows the corresponding os call to account for sysroot

Parameters:

• path (str) – The leading path passed to os.path.join()

• p (str) – Following path section(s) to be joined with path, an empty parameter will result in a path that ends with a separator

plugin_name = None

plugin_timeout = 300

postproc()

Perform any postprocessing. To be replaced by a plugin if required.

predicate = None

profiles = ()

runtime = None

services = ()

set_cmd_predicate(pred)

Set or clear the default predicate for command collection for this plugin. If set, this predecate takes precedence over the Plugin default predicate for command and journal data collection.

Parameters:

pred (SoSPredicate) – The predicate to use as the default command predicate

set_default_cmd_environment(env_vars)

Specify a collection of environment variables that should always be passed to commands being executed by this plugin.

Parameters:

env_vars (dict{ENV_VAR_NAME: ENV_VAR_VALUE}) – The environment variables and their values to set

set_option(optionname, value)

Set the named option to value. Ensure the original type of the option value is preserved

Parameters:

• optioname (str) – The name of the option to set

• value – The value to set the option to

Returns:

True if the option is successfully set, else False

Return type:

bool

set_plugin_manifest(manifest)

Pass in a manifest object to the plugin to write to

Parameters:

manifest (SoSManifest) – The manifest that the plugin will add metadata to

set_predicate(pred)

Set or clear the default predicate for this plugin.

Parameters:

pred (SoSPredicate) – The predicate to use as the default for this plugin

set_timeout_hit()

setup()

Collect the list of files declared by the plugin. This method may be overridden to add further copy_specs, forbidden_paths, and external programs if required.

setup_verify()

short_desc = '<no description available>'

signal_process_usr1(process)

Send a SIGUSR1 to the pid(s) associated with the specified process name. Callers should be aware that a 1-second delay per signalled pid, up to 5 seconds at most, is expected as to allow sufficient time for the signalled process(es) to react to the received signal.

Parameters:

process (str) – The name or regex pattern of the process(es) to signal

Returns:

A list of pids that were successfully signalled

Return type:

list

strip_sysroot(path)

Remove the configured sysroot from a filesystem path

Parameters:

path (str) – The filesystem path to strip sysroot from

Returns:

The stripped filesystem path

Return type:

str

sysroot = '/'

test_predicate(cmd=False, pred=None)

Test the current predicate and return its value.

Parameters:

• cmd – True if the predicate is gating a command or False otherwise.

• pred – An optional predicate to override the current Plugin or command predicate.

Returns:

True or False based on predicate evaluation, or False if no predicate

Return type:

bool

property timeout

Returns either the default plugin timeout value, the value as provided on the commandline via -k plugin.timeout=value, or the value of the global –plugin-timeout option.

timeout_from_options(optname, plugoptname, default_timeout)

Get the timeout value for either the plugin or a command, as determined by either the value provided via the plugin.timeout or plugin.cmd-timeout option, the global timeout or cmd-timeout options, or the default value set by the plugin or the collection, in that order of precendence.

Parameters:

• optname (str) – The name of the cmdline option being checked, either ‘plugin_timeout’ or ‘timeout’

• plugoptname (str) – The name of the plugin option name being checked, either ‘timeout’ or ‘cmd-timeout’

• default_timeout (int) – The timeout to default to if determination is inconclusive or hits an error

Returns:

The timeout value in seconds

Return type:

int

tmp_in_sysroot()

Check if sysroot is within the archive’s temp directory

Returns:

True if sysroot is in the archive’s temp directory, else False

Return type:

bool

use_sysroot()

Determine if the configured sysroot needs to be used

Returns:

True if sysroot is not /, else False

Return type:

bool

class sos.report.plugins.PluginDistroTag

Bases: object

The base tagging class for distro-specific classes used to signify that a Plugin is written for that distro.

Use IndependentPlugin for plugins that are distribution agnostic

class sos.report.plugins.PluginOpt(name='undefined', default=None, desc='', long_desc='', val_type=None)

Bases: object

This is used to define options available to plugins. Plugins will need to define options alongside their distro-specific classes in order to add support for user-controlled changes in Plugin behavior.

Parameters:

• name (str) – The name of the plugin option

• default (Any) – The default value of the option

• desc (str) – A short description of the effect of the option

• long_desc (str) – A detailed description of the option. Will be used by sos info

• val_type (A single type or a list of types) – The type of object the option accepts for values. If not provided, auto-detect from the type of default

default = None

desc = ''

enabled = False

long_desc = ''

name = ''

plugin = ''

set_value(val)

val_type = [None]

value = None

class sos.report.plugins.RedHatPlugin

Bases: PluginDistroTag

Tagging class for Red Hat’s Linux distributions

class sos.report.plugins.SoSCommand(**kwargs)

Bases: object

A class to represent a command to be collected.

A SoSCommand() object is instantiated for each command handed to an _add_cmd_output() call, so that we no longer need to pass around a very long tuple to handle the parameters.

Any option supported by _add_cmd_output() is passed to the SoSCommand object and converted to an attribute. SoSCommand.__dict__ is then passed to _get_command_output_now() for each command to be collected.

class sos.report.plugins.SoSPredicate(owner, dry_run=False, kmods=[], services=[], packages=[], cmd_outputs=[], arch=[], required={})

Bases: object

A class to implement collection predicates.

A predicate gates the collection of data by an sos plugin. For any add_cmd_output(), add_copy_spec() or add_journal() call, the passed predicate will be evaulated and collection will proceed if the result is True, and not otherwise.

Predicates may be used to control conditional data collection without the need for explicit conditional blocks in plugins.

Parameters:

• owner (Plugin) – The Plugin object creating the predicate

• dry_run (bool) – Is sos running in dry_run mode?

• kmods (list, or str of single name) – Kernel module name(s) to check presence of

• services (list, or str of single name) – Service name(s) to check if running

• packages (list, or str of single name) – Package name(s) to check presence of

• cmd_outputs (list of dict``s, or single ``dict taking form {‘cmd’: <command to run>, ‘output’: <string that output should contain>}) – Command to run, with output string to check

• arch (list, or str of single architecture) – Architecture(s) that the local system is matched against

• required (dict, with keys matching parameter names and values being either ‘any’, ‘all’, or ‘none. Default ‘any’.) – For each parameter provided, should the checks require all items, no items, or any items provided

arch = []

Allowed architecture(s) of the system

cmd_outputs = []

dry_run = False

Skip all collection?

kmods = []

Kernel module enablement list

packages = []

Package presence list

report_failure()

Used by Plugin() to obtain the error string based on if the reason was a failed check or a forbidden check

services = []

Services enablement list

class sos.report.plugins.SuSEPlugin

Bases: PluginDistroTag

Tagging class for SuSE Linux distributions

class sos.report.plugins.UbuntuPlugin

Bases: PluginDistroTag

Tagging class for Ubuntu Linux

sos.report.plugins.import_plugin(name, superclasses=None)

Import name as a module and return a list of all classes defined in that module. superclasses should be a tuple of valid superclasses to import, this defaults to (Plugin,).

sos.report.plugins.regex_findall(regex, fname)

Return a list of all non overlapping matches in the string(s)