Plugin options

Plugins can define command line options that allow the user to modify the plugin's behaviour. There are also a a set of global command line options exposed to all plugins.

Running a plugin with options

To run sosreport and pass an option to a plugin use the -k, or --plugin-option switches:

# sosreport -kxfs.logprint

# sosreport --plugin-option filesys.lsof

# sosreport -kfilesys.lsof,filesys.dumpe2fs

Adding an option to a plugin

Adding an option is simple. A plugin just needs to define a class variable named option_list which is a list of option tuples. An option tuple consists of four elements: `("", "", "fast|slow", default_value) (although there is a proposal to remove the "fast|slow" member - see (Issue #)

class MyPlugin(Plugin, RedHatPlugin, DebianPlugin):

    plugin_name = "myplugin"
    option_list = [("foo", "enable foo support", "fast", False)]

    def setup(self):
        if self.get_option("foo"):
            self.add_cmd_output("foo")
        self.add_cmd_output("bar")

To add more options just extend the list with further tuples and then test for their presence in the plugin's methods. Option values are strings or booleans.

class MyPlugin(Plugin, RedHatPlugin, DebianPlugin):

    plugin_name = "myplugin"
    option_list = [
        ("foo", "enable foo support", "fast", False),
        ("baz", "number of baz to collect", "slow", 10),
        ("qux", "enable qux support", "fast", True),
    ]

    def setup(self):
        if self.get_option("foo"):
            self.add_cmd_output("foo")
        self.add_cmd_output("bar")

Option lines can get quite long so the recommended style is as shown: put the opening bracket of the list on the same line as the option_list variable and the first and subsequent option tuples on their own line indented one level deeper than the variable name. The closing bracket is indented to the same level as the option list. For plugins with a single option with a short description it's fine to put the whole list on one line.

Global options

Global plugin options are normal command line switches that are exposed for all plugins to use. There are currently three defined global plugin options:

• --verify, causes plugins to perform plugin-specific data verification where possible (e.g. package manager verification. May greatly increase runtime).
• --all-logs, causes plugins to attempt to collect all available log data (may greatly increase the size of reports).
• --log-size, specify a limit for per-log file data collection

Plugins access these via the same get_option() method used for plugin specific options. Any dashes in the option name are replaced with underscores:

        limit = self.get_option("log_size")
        self.add_copy_spec_limit("/var/log/foo.log", sizelimit=limit)
        if self.get_option("all_logs"):
            self.add_copy_spec("/var/log/foo.log*")

        if self.get_option("verify"):
            self.add_cmd_output("foo --verify")

See the existing plugins for more examples of plugin options in use:

         if self.get_option("verify"):
            if self.get_option("rpmva"):
                self.add_cmd_output("rpm -Va", root_symlink = "rpm-Va", timeout = 3600)
            else:
                pkgs_by_regex = self.policy().package_manager.all_pkgs_by_name_regex
                verify_list = map(pkgs_by_regex, self.verify_list)
                verify_pkgs = ""
                for pkg_list in verify_list:
                    for pkg in pkg_list:
                        if 'debuginfo' in pkg or 'devel' in pkg:
                            continue
                        verify_pkgs = "%s %s" % (verify_pkgs, pkg)
                self.add_cmd_output("rpm -V %s" % verify_pkgs)