diff options
| -rw-r--r-- | docs/plugins.rst | 1 | ||||
| -rw-r--r-- | sos/report/plugins/__init__.py | 834 |
2 files changed, 689 insertions, 146 deletions
diff --git a/docs/plugins.rst b/docs/plugins.rst index 9df84227..a1fb0627 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -4,5 +4,4 @@ .. automodule:: sos.report.plugins :noindex: :members: - :undoc-members: :show-inheritance: diff --git a/sos/report/plugins/__init__.py b/sos/report/plugins/__init__.py index 46fa7286..bc601d12 100644 --- a/sos/report/plugins/__init__.py +++ b/sos/report/plugins/__init__.py @@ -78,13 +78,42 @@ _cert_replace = "-----SCRUBBED" class SoSPredicate(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. + 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. + + :param owner: The ``Plugin`` object creating the predicate + :type owner: ``Plugin`` + + :param dry_run: Is sos running in dry_run mode? + :type dry_run: ``bool`` + + :param kmods: Kernel module name(s) to check presence of + :type kmods: ``list``, or ``str`` of single name + + :param services: Service name(s) to check if running + :type services: ``list``, or ``str`` of single name + + :param packages: Package name(s) to check presence of + :type packages: ``list``, or ``str`` of single name + + :param cmd_outputs: Command to run, with output string to check + :type cmd_outputs: ``list`` of ``dict``s, or single ``dict`` taking form + {'cmd': <command to run>, + 'output': <string that output should contain>} + :param arch: Architecture(s) that the local system is matched + against + :type arch: ``list``, or ``str`` of single architecture + + :param required: For each parameter provided, should the checks + require all items, no items, or any items provided + :type required: ``dict``, with keys matching parameter names and values + being either 'any', 'all', or 'none. Default 'any'. - Predicates may be used to control conditional data collection - without the need for explicit conditional blocks in plugins. """ #: The plugin that owns this predicate _owner = None @@ -320,7 +349,7 @@ class SoSPredicate(object): def __init__(self, owner, dry_run=False, kmods=[], services=[], packages=[], cmd_outputs=[], arch=[], required={}): - """Initialise a new SoSPredicate object. + """Initialise a new SoSPredicate object """ self._owner = owner self.kmods = list(kmods) @@ -371,25 +400,53 @@ class SoSCommand(object): class Plugin(object): - """ This is the base class for sosreport plugins. Plugins should subclass + """This is the base class for sosreport plugins. Plugins should subclass this and set the class variables where applicable. - plugin_name is a string returned by plugin.name(). If this is set to None - (the default) class\\_.__name__.tolower() will be returned. Be sure to set - this if you are defining multiple plugins that do the same thing on - different platforms. + :param commons: A set of information that is shared internally so that + plugins may access the same dataset. This is provided + automatically by sos + :type commons: ``dict`` + + 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. + + :cvar plugin_name: The name of the plugin, will be returned by `name()` + :vartype plugin_name: ``str`` + + :cvar version: The version of the plugin, defaults to 'unversioned' + :vartype version: ``str`` + + :cvar packages: Package name(s) that, if installed, enable this plugin + :vartype packages: ``tuple`` + + :cvar files: File path(s) that, if present, enable this plugin + :vartype files: ``tuple`` - version is a string representing the version of the plugin. This can be - useful for post-collection tooling. + :cvar commands: Executables that, if present, enable this plugin + :vartype commands: ``tuple`` - packages (files) is an iterable of the names of packages (the paths - of files) to check for before running this plugin. If any of these packages - or files is found on the system, the default implementation of - check_enabled will return True. + :cvar kernel_mods: Kernel module(s) that, if loaded, enable this plugin + :vartype kernel_mods: ``tuple`` - profiles is an iterable of profile names that this plugin belongs to. - Whenever any of the profiles is selected on the command line the plugin - will be enabled (subject to normal check_enabled tests). + :cvar services: Service name(s) that, if running, enable this plugin + :vartype services: ``tuple`` + + :cvar architectures: Architecture(s) this plugin is enabled for. Defaults + to 'none' to enable on all arches. + :vartype architectures: ``tuple``, or ``None`` + + :cvar profiles: Name(s) of profile(s) this plugin belongs to + :vartype profiles: ``tuple`` + + :cvar plugin_timeout: Timeout in seconds for this plugin as a whole + :vartype plugin_timeout: ``int`` + + :cvar cmd_timeout: Timeout in seconds for individual commands + :vartype cmd_timeout: ``int`` """ plugin_name = None @@ -456,6 +513,9 @@ class Plugin(object): def set_plugin_manifest(self, manifest): """Pass in a manifest object to the plugin to write to + + :param manifest: The manifest that the plugin will add metadata to + :type manifest: ``SoSManifest`` """ self.manifest = manifest # add these here for organization when they actually get set later @@ -511,15 +571,18 @@ class Plugin(object): 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. + :returns: ``True`` if timeout has been hit, else ``False`` + :rtype: ``bool`` """ return self._timeout_hit @classmethod def name(cls): - """Returns the plugin's name as a string. This should return a - lowercase string. + """Get the name of the plugin + + :returns: The name of the plugin, in lowercase + :rtype: ``str`` """ if cls.plugin_name: return cls.plugin_name @@ -541,11 +604,27 @@ class Plugin(object): self.soslog.debug(self._format_msg(msg)) def join_sysroot(self, path): + """Join a given path with the configured sysroot + + :param path: The filesystem path that needs to be joined + :type path: ``str`` + + :returns: The joined filesystem path + :rtype: ``str`` + """ if path[0] == os.sep: path = path[1:] return os.path.join(self.sysroot, path) def strip_sysroot(self, path): + """Remove the configured sysroot from a filesystem path + + :param path: The filesystem path to strip sysroot from + :type path: ``str`` + + :returns: The stripped filesystem path + :rtype: ``str`` + """ if not self.use_sysroot(): return path if path.startswith(self.sysroot): @@ -553,61 +632,134 @@ class Plugin(object): return path def use_sysroot(self): + """Determine if the configured sysroot needs to be used + + :returns: ``True`` if sysroot is not `/`, else ``False`` + :rtype: ``bool`` + """ return self.sysroot != os.path.abspath(os.sep) def tmp_in_sysroot(self): + """Check if sysroot is within the archive's temp directory + + :returns: ``True`` if sysroot is in the archive's temp directory, else + ``False`` + :rtype: ``bool`` + """ paths = [self.sysroot, self.archive.get_tmp_dir()] return os.path.commonprefix(paths) == self.sysroot def is_installed(self, package_name): - """Is the package $package_name installed?""" + """Is the package $package_name installed? + + :param package_name: The name of the package to check + :type package_name: ``str`` + + :returns: ``True`` id the package is installed, else ``False`` + :rtype: ``bool`` + """ return self.policy.pkg_by_name(package_name) is not None def is_service(self, name): - """Does the service $name exist on the system?""" + """Does the service $name exist on the system? + + :param name: The name of the service to check + :type name: ``str`` + + :returns: ``True`` if service is present on the system, else ``False`` + :rtype: ``bool`` + """ return self.policy.init_system.is_service(name) def is_service_enabled(self, name): - """Is the service $name enabled?""" + """Is the service $name enabled? + + :param name: The name of the service to check + :type name: ``str`` + + :returns: ``True if service is enabled on the system, else ``False`` + :rtype: ``bool`` + """ return self.policy.init_system.is_enabled(name) def is_service_disabled(self, name): - """Is the service $name disabled?""" + """Is the service $name disabled? + + :param name: The name of the service to check + :type name: ``str`` + + :returns: ``True`` if service is disabled on the system, else ``False`` + :rtype: ``bool`` + """ return self.policy.init_system.is_disabled(name) def is_service_running(self, name): - """Is the service $name currently running?""" + """Is the service $name currently running? + + :param name: The name of the service to check + :type name: ``str`` + + :returns: ``True`` if the service is running on the system, else + ``False`` + :rtype: ``bool`` + """ return self.policy.init_system.is_running(name) def get_service_status(self, name): - """Return the reported status for service $name""" + """Return the reported status for service $name + + :param name: The name of the service to check + :type name: ``str`` + + :returns: The state of the service according to the init system + :rtype: ``str`` + """ return self.policy.init_system.get_service_status(name)['status'] def get_service_names(self, regex): - """Get all service names matching regex""" + """Get all service names matching regex + + :param regex: A regex to match service names against + :type regex: ``str`` + + :returns: All service name(s) matching the given `regex` + :rtype: ``list`` + """ return self.policy.init_system.get_service_names(regex) def set_predicate(self, pred): """Set or clear the default predicate for this plugin. + + :param pred: The predicate to use as the default for this plugin + :type pred: ``SoSPredicate`` """ self.predicate = pred def set_cmd_predicate(self, 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. + """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. + + :param pred: The predicate to use as the default command predicate + :type pred: ``SoSPredicate`` """ self.cmd_predicate = pred def get_predicate(self, cmd=False, pred=None): - """Get the current default `Plugin` or command predicate. If the - `cmd` argument is `True`, the current command predicate is - returned if set, otherwise the default `Plugin` predicate - will be returned (which may be `None`). + """Get the current default `Plugin` or command predicate. + + :param cmd: If a command predicate is set, should it be used. + :type cmd: ``bool`` - If no default predicate is set and a `pred` value is passed - it will be returned. + :param pred: An optional predicate to pass if no command or plugin + predicate is set + :type pred: ``SoSPredicate`` + + :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``). + :rtype: ``SoSPredicate`` or ``None`` """ if pred is not None: return pred @@ -618,10 +770,14 @@ class Plugin(object): def test_predicate(self, cmd=False, pred=None): """Test the current predicate and return its value. - :param cmd: ``True`` if the predicate is gating a command or - ``False`` otherwise. - :param pred: An optional predicate to override the current - ``Plugin`` or command predicate. + :param cmd: ``True`` if the predicate is gating a command or + ``False`` otherwise. + :param 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 + :rtype: ``bool`` """ pred = self.get_predicate(cmd=cmd, pred=pred) if pred is not None: @@ -632,12 +788,27 @@ class Plugin(object): 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. + 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. + + :param pred: The predicate that caused the command to be skipped + :type pred: ``SoSPredicate`` + + :param cmd: The command that was skipped + :type cmd: ``str`` + + :param kmods: Did kernel modules cause the command to be skipped + :type kmods: ``bool`` + + :param services: Did services cause the command to be skipped + :type services: ``bool`` + + :param changes: Is the `--allow-system-changes` enabled + :type changes: ``bool`` """ msg = "skipped command '%s': %s" % (cmd, pred.report_failure()) @@ -647,12 +818,18 @@ class Plugin(object): self._log_warn(msg) def do_cmd_private_sub(self, cmd, desc=""): - """Remove certificate and key output archived by sosreport. cmd - is the command name from which output is collected (i.e. exlcuding - parameters). Any matching instances are replaced with: '-----SCRUBBED' - and this function does not take a regexp or substituting string. + """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. + + :param cmd: The name of the binary to scrub certificate output from + :type cmd: ``str`` + + :param desc: An identifier to add to the `SCRUBBED` header line + :type desc: ``str`` - This function returns the number of replacements made. + :returns: Number of replacements made + :rtype: ``int`` """ if not self.executed_commands: return 0 @@ -666,14 +843,25 @@ class Plugin(object): def do_cmd_output_sub(self, cmd, regexp, subst): """Apply a regexp substitution to command output archived by sosreport. - cmd is the command name from which output is collected (i.e. excluding - parameters). The regexp can be a string or a compiled re object. The - substitution string, subst, is a string that replaces each occurrence - of regexp in each file collected from cmd. Internally 'cmd' is treated - as a glob with a leading and trailing '*' and each matching file from - the current module's command list is subjected to the replacement. - This function returns the number of replacements made. + This is used to obfuscate sensitive information captured by command + output collection via plugins. + + :param cmd: The command name/binary name for collected output that + needs to be obfuscated. Internally globbed with a leading + and trailing `*` + :type cmd: ``str`` + + :param regexp: A regex to match the contents of the command output + against + :type regexp: ``str`` or compile ``re`` object + + :param subst: The substitution string used to replace matches from + `regexp` + :type subst: ``str`` + + :returns: Number of replacements made + :rtype: ``int`` """ globstr = '*' + cmd + '*' pattern = regexp.pattern if hasattr(regexp, "pattern") else regexp @@ -718,9 +906,11 @@ class Plugin(object): "-----SCRUBBED RSA PRIVATE KEY" so that support representatives can at least be informed of what type of content it was originally. - Positional arguments: - :param pathregex: A string or regex of a filename to match against - :param desc: A description of the replaced content + :param pathregex: A string or regex of a filename to match against + :type pathregex: ``str`` + + :param desc: A description of the replaced content + :type desc: ``str`` """ self._log_debug("Scrubbing certs and keys for paths matching %s" % pathregex) @@ -735,11 +925,19 @@ class Plugin(object): def do_file_sub(self, srcpath, regexp, subst): """Apply a regexp substitution to a file archived by sosreport. - srcpath is the path in the archive where the file can be found. regexp - can be a regexp string or a compiled re object. subst is a string to - replace each occurance of regexp in the content of srcpath. - This function returns the number of replacements made. + :param srcpath: Path in the archive where the file can be found + :type srcpath: ``str`` + + :param regexp: A regex to match the contents of the file + :type regexp: ``str`` or compiled ``re`` object + + :param subst: The substitution string to be used to replace matches + within the file + :type subst: ``str`` + + :returns: Number of replacements made + :rtype: ``int`` """ try: path = self._get_dest_for_srcpath(srcpath) @@ -773,10 +971,17 @@ class Plugin(object): def do_path_regex_sub(self, 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 which may be a regular - expression string or compiled re object. The portion of the file - to be replaced is specified via regexp and the replacement string - is passed in subst.""" + collected file pathnames against `pathexp`. + + :param pathexp: A regex to match filenames within the archive + :type pathexp: ``str`` or compiled ``re`` object + + :param regexp: A regex to match against the contents of each file + :type regexp: ``str`` or compiled ``re`` object + + :param subst: The substituion string to be used to replace matches + :type subst: ``str`` + """ if not hasattr(pathexp, "match"): pathexp = re.compile(pathexp) match = pathexp.match @@ -943,8 +1148,11 @@ class Plugin(object): }) def add_forbidden_path(self, forbidden): - """Specify a path, or list of paths, to not copy, even if it's - part of a copy_specs[] entry. + """Specify a path, or list of paths, to not copy, even if it's part of + an ``add_copy_spec()`` call + + :param forbidden: A filepath to forbid collection from + :type forbidden: ``str`` or a ``list`` of strings """ if isinstance(forbidden, str): forbidden = [forbidden] @@ -962,8 +1170,16 @@ class Plugin(object): return (self.opt_names, self.opt_parms) def set_option(self, optionname, value): - """Set the named option to value. Ensure the original type - of the option value is preserved. + """Set the named option to value. Ensure the original type of the + option value is preserved + + :param optioname: The name of the option to set + :type optioname: ``str`` + + :param value: The value to set the option to + + :returns: ``True`` if the option is successfully set, else ``False`` + :rtype: ``bool`` """ for name, parms in zip(self.opt_names, self.opt_parms): if name == optionname: @@ -980,12 +1196,20 @@ class Plugin(object): return False def get_option(self, optionname, default=0): - """Returns the first value that matches 'optionname' in parameters - passed in via the command line or set via set_option or via the - global_plugin_options dictionary, in that order. + """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. + + :param optionname: The name of the option to retrieve the value of + :type optionname: ``str`` - optionaname may be iterable, in which case the first option that - matches any of the option names is returned. + :param 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` """ global_options = ( @@ -1070,11 +1294,39 @@ class Plugin(object): def add_copy_spec(self, copyspecs, sizelimit=None, maxage=None, tailit=True, pred=None, tags=[]): - """Add a file or glob but limit it to sizelimit megabytes. Collect - files with mtime not older than maxage hours. - If fname is a single file the file will be tailed to meet sizelimit. - If the first file in a glob is too large it will be tailed to meet - the sizelimit. + """Add a file, directory, or regex matching filepaths to the archive + + :param copyspecs: A file, directory, or regex matching filepaths + :type copyspecs: ``str`` or a ``list`` of strings + + :param sizelimit: Limit the total size of collections from `copyspecs` + to this size in MB + :type sizelimit: ``int`` + + :param maxage: Collect files with `mtime` not older than this many + hours + :type maxage: ``int`` + + :param tailit: Should a file that exceeds `sizelimit` be tail'ed to fit + the remaining space to meet `sizelimit` + :type tailit: ``bool`` + + :param pred: A predicate to gate if `copyspecs` should be collected + :type pred: ``SoSPredicate`` + + :param tags: A tag or set of tags to add to the metadata information + for this collection + :type tags: ``str`` or a ``list`` of strings + + `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. + + 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`. """ since = None if self.get_option('since'): @@ -1230,16 +1482,42 @@ class Plugin(object): specified devices. Commands passed to this should include a '%(dev)s' variable for substitution. - devices - Either 'block', 'fibre', or a list of device paths to - run against. If set to 'block' or 'fibre', the commands - will be run against the matching list of discovered - devices. - prepend_path - the leading path for block device names, e.g. - '/dev/' or '/sys/block/'. - whitelist - limit the devices iterated over. May be a str or list - of strings (e.g. regexes) - blacklist - exclude the devices iterated over. May be a str or list - of strings (e.g. regexes) + :param cmds: The command(s) to run against the list of devices + :type cmds: ``str`` or a ``list`` of strings + + :param devices: The device paths to run `cmd` against. If set to + `block` or `fibre`, the commands will be run against + the matching list of discovered devices + :type devices: ``str`` or a ``list`` of device paths + + :param timeout: Timeout in seconds to allow each `cmd` to run + :type timeout: ``int`` + + :param sizelimit: Maximum amount of output to collect, in MB + :type sizelimit: ``int`` + + :param chroot: Should sos chroot the command(s) being run + :type chroot: ``bool`` + + :param runat: Set the filesystem location to execute the command from + :type runat: ``str`` + + :param env: Set environment variables for the command(s) being run + :type env: ``dict`` + + :param binary: Is the output collected going to be binary data + :type binary: ``bool`` + + :param prepend_path: The leading path for block device names + :type prepend_path: ``str`` or ``None`` + + :param whitelist: Limit the devices the `cmds` will be run against to + devices matching these item(s) + :type whitelist: ``list`` of ``str`` + + :param blacklist: Do not run `cmds` against devices matching these + item(s) + :type blacklist: ``list`` of ``str`` """ _dev_tags = [] if isinstance(tags, str): @@ -1312,7 +1590,63 @@ class Plugin(object): chroot=True, runat=None, env=None, binary=False, sizelimit=None, pred=None, subdir=None, changes=False, foreground=False, tags=[]): - """Run a program or a list of programs and collect the output""" + """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` + + :param cmds: The command(s) to execute + :type cmds: ``str`` or a ``list`` of strings + + :param suggest_filename: Override the name of the file output is saved + to within the archive + :type suggest_filename: ``str`` + + :param root_symlink: If set, create a symlink with this name in the + archive root + :type root_symlink: ``str`` + + :param timeout: Timeout in seconds to allow each `cmd` to run for + :type timeout: ``int`` + + :param stderr: Should stderr output be collected + :type stderr: ``bool`` + + :param chroot: Should sos chroot the `cmds` being run + :type chroot: ``bool`` + + :param runat: Run the `cmds` from this location in the filesystem + :type runat: ``str`` + + :param env: Set environment variables for the `cmds` being run + :type env: ``dict`` + + :param binary: Is the command expected to produce binary output + :type binary: ``bool`` + + :param sizelimit: Maximum amount of output in MB to save + :type sizelimit: ``int`` + + :param pred: A predicate to gate if `cmds` should be collected or not + :type pred: ``SoSPredicate`` + + :param subdir: Save output to this subdirectory, within the plugin's + directory under sos_commands + :type subdir: ``str`` + + :param changes: Do `cmds` have the potential to change system state + :type changes: ``int`` + + :param foreground: Should the `cmds` be run in the foreground, with an + attached TTY + :type foreground: ``bool`` + + :param tags: A tag or set of tags to add to the metadata entries for + the `cmds` being run + :type tags: ``str`` or a ``list`` of strings + """ if isinstance(cmds, str): cmds = [cmds] if len(cmds) > 1 and (suggest_filename or root_symlink): @@ -1360,8 +1694,18 @@ class Plugin(object): return [] def get_cmd_output_path(self, name=None, make=True): - """Return a path into which this module should store collected - command output + """Get the path where this plugin will save command output + + :param name: Optionally specify a filename to use as part of the + command output path + :type name: ``str`` or ``None`` + + :param make: Attempt to create the command output path + :type make: ``bool`` + + :returns: The path where the plugin will write command output data + within the archive + :rtype: ``str`` """ cmd_output_path = os.path.join(self.archive.get_tmp_dir(), 'sos_commands', self.name()) @@ -1373,9 +1717,16 @@ class Plugin(object): return cmd_output_path def file_grep(self, regexp, *fnames): - """Returns lines matched in fnames, where fnames can either be - pathnames to files to grep through or open file objects to grep through - line by line. + """Grep through file(s) for a specific string or regex + + :param regexp: The string or regex to search for + :type regexp: ``str`` + + :param fnames: Paths to grep through + :type fnames: ``str``, ``list`` of string, or open file objects + + :returns: Lines matching `regexp` + :rtype: ``str`` """ return grep(regexp, *fnames) @@ -1414,9 +1765,12 @@ class Plugin(object): def add_env_var(self, name): """Add an environment variable to the list of to-be-collected env vars. - Accepts either a single variable name or a list of names. Any value - given will be added as provided to the method, as well as an upper- - and lower- cased version. + 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 + + :param name: The name of the environment variable to collect + :type name: ``str`` """ if not isinstance(name, list): name = [name] @@ -1427,7 +1781,18 @@ class Plugin(object): self._env_vars.update([env, env.upper(), env.lower()]) def add_string_as_file(self, content, filename, pred=None): - """Add a string to the archive as a file named `filename`""" + """Add a string to the archive as a file + + :param content: The string to write to the archive + :type content: ``str`` + + :param filename: The name of the file to write `content` to + :type filename: ``str`` + + :param pred: A predicate to gate if the string should be added to the + archive or not + :type pred: ``SoSPredicate`` + """ # Generate summary string for logging summary = content.splitlines()[0] if content else '' @@ -1574,7 +1939,53 @@ class Plugin(object): binary=False, sizelimit=None, pred=None, subdir=None, tags=[]): """Execute a command and save the output to a file for inclusion in the - report. + report, then return the results for further use by the plugin + + :param cmd: The command to run + :type cmd: ``str`` + + :param suggest_filename: Filename to use when writing to the + archive + :param suggest_filename: ``str`` + + :param root_symlink: Create a symlink in the archive root + :type root_symlink: ``bool`` + + :param timeout: Time in seconds to allow a cmd to run + :type timeout: ``int`` + + :param stderr: Write stderr to stdout? + :type stderr: ``bool`` + + :param chroot: Perform chroot before running cmd? + :type chroot: ``bool`` + + :param runat: Run the command from this location, + overriding chroot + :type runat: ``str`` + + :param env: Environment vars to set for the cmd + :type env: ``dict`` + + :param binary: Is the output in binary? + :type binary: ``bool`` + + :param sizelimit: Maximum size in MB of output to save + :type sizelimit: ``int`` + + :param subdir: Subdir in plugin directory to save to + :type subdir: ``str`` + + :param changes: Does this cmd potentially make a change + on the system? + :type changes: ``bool`` + + :param tags: Add tags in the archive manifest + :type tags: ``str`` or a ``list`` of strings + + :returns: `cmd` exit status, output, and the filepath within the + archive output was saved to + :rtype: ``dict`` """ if not self.test_predicate(cmd=True, pred=pred): self._log_info("skipped cmd output '%s' due to predicate (%s)" % @@ -1600,6 +2011,41 @@ class Plugin(object): 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(). + + :param cmd: The command to run + :type cmd: ``str`` + + :param timeout: Time in seconds to allow a cmd to run + :type timeout: ``int`` + + :param stderr: Write stderr to stdout? + :type stderr: ``bool`` + + :param chroot: Perform chroot before running cmd? + :type chroot: ``bool`` + + :param runat: Run the command from this location, + overriding chroot + :type runat: ``str`` + + :param env: Environment vars to set for the cmd + :type env: ``dict`` + + :param binary: Is the output in binary? + :type binary: ``bool`` + + :param pred: A predicate to gate execution of the `cmd` + :type pred: ``SoSPredicate`` + + :param foreground: Run the `cmd` in the foreground with a TTY + :type foreground: ``bool`` + + :param container: Execute this command in a container with + this name + :type container: ``str`` + + :returns: Command exit status and output + :rtype: ``dict`` """ _default = {'status': None, 'output': ''} if not self.test_predicate(cmd=True, pred=pred): @@ -1641,6 +2087,12 @@ class Plugin(object): def container_exists(self, name): """If a container runtime is present, check to see if a container with a given name is currently running + + :param name: The name of the container to check presence of + :type name: ``str`` + + :returns: ``True`` if `name` exists, else ``False`` + :rtype: ``bool`` """ _runtime = self._get_container_runtime() if _runtime is not None: @@ -1649,17 +2101,35 @@ class Plugin(object): return False def get_container_by_name(self, name): + """Get the container ID for a specific container + + :param name: The name of the container + :type name: ``str`` + + :returns: The ID of the container if it exists + :rtype: ``str`` or ``None`` + """ _runtime = self._get_container_runtime() if _runtime is not None: return _runtime.get_container_by_name(name) return None def get_containers(self, runtime=None, get_all=False): - """Return a list of all container IDs from the Policy's - ContainerRuntime. + """Return a list of all container IDs from the ``Policy`` + ``ContainerRuntime`` - If `runtime` is not provided, use the Policy default. If the specified - `runtime is not loaded, return empty. + If `runtime` is not provided, use the ``Policy`` default + + :param runtime: The container runtime to use, if not the default + runtime detected and loaded by the ``Policy`` + :type runtime: ``str`` + + :param get_all: Return all containers known to the `runtime`, even + those that have terminated + :type get_all: ``bool`` + + :returns: All container IDs found by the ``ContainerRuntime`` + :rtype: ``list`` """ _runtime = self._get_container_runtime(runtime=runtime) if _runtime is not None: @@ -1674,7 +2144,14 @@ class Plugin(object): ContainerRuntime If `runtime` is not provided, use the Policy default. If the specified - `runtime is not loaded, return empty. + `runtime` is not loaded, return empty. + + :param runtime: The container runtime to use, if not using the + default runtime detected by the ``Policy`` + :type runtime: ``str`` + + :returns: A list of container images known to the `runtime` + :rtype: ``list`` """ _runtime = self._get_container_runtime(runtime=runtime) if _runtime is not None: @@ -1686,7 +2163,14 @@ class Plugin(object): ContainerRuntime If `runtime` is not provided, use the Policy default. If the specified - `runtime is not loaded, return empty. + `runtime` is not loaded, return empty. + + :param runtime: The container runtime to use, if not using the + default runtime detected by the ``Policy`` + :type runtime: ``str`` + + :returns: A list of container volumes known to the `runtime` + :rtype: ``list`` """ _runtime = self._get_container_runtime(runtime=runtime) if _runtime is not None: @@ -1694,44 +2178,78 @@ class Plugin(object): return [] def get_container_logs(self, container, **kwargs): - """Helper to get the `logs` output for a given container + """Helper to get the ``logs`` output for a given container Supports passthru of add_cmd_output() options + + :param container: The name of the container to retrieve logs from + :type container: ``str`` + + :param kwargs: Any kwargs supported by ``add_cmd_output()`` are + supported here """ _runtime = self._get_container_runtime() if _runtime is not None: self.add_cmd_output(_runtime.get_logs_command(container), **kwargs) def fmt_container_cmd(self, container, cmd): + """Format a command to be executed by the loaded ``ContainerRuntime`` + in a specified container + + :param container: The name of the container to execute the `cmd` in + :type container: ``str`` + + :param cmd: The command to run within the container + :type cmd: ``str`` + + :returns: The command to execute so that the specified `cmd` will run + within the `container` and not on the host + :rtype: ``str`` + """ if self.container_exists(container): _runtime = self._get_container_runtime() return _runtime.fmt_container_cmd(container, cmd) return cmd def is_module_loaded(self, module_name): - """Return whether specified module as module_name is loaded or not""" + """Determine whether specified module is loaded or not + + :param module_name: Name of kernel module to check for presence + :type module_name: ``str`` + + :returns: ``True`` if the module is loaded, else ``False`` + :rtype: ``bool`` + """ return module_name in self.policy.kernel_mods # For adding output def add_alert(self, alertstring): """Add an alert to the collection of alerts for this plugin. These will be displayed in the report + + :param alertstring: The text to add as an alert + :type alertstring: ``str`` """ self.alerts.append(alertstring) def add_custom_text(self, text): """Append text to the custom text that is included in the report. This is freeform and can include html. + + :param text: The text to include in the report + :type text: ``str`` """ self.custom_text += text def add_service_status(self, services, **kwargs): - """Collect service status information based on the InitSystem used. + """Collect service status information based on the ``InitSystem`` used + + :param services: Service name(s) to collect statuses for + :type services: ``str`` or a ``list`` of strings - :param services: A string, or list of strings, specifying the services - to collect - :param kwargs Optional arguments to pass to _add_cmd_output + :param kwargs: Optional arguments to pass to _add_cmd_output (timeout, predicate, suggest_filename,..) + """ if isinstance(services, str): services = [services] @@ -1752,35 +2270,41 @@ class Plugin(object): sizelimit=None, pred=None, tags=[]): """Collect journald logs from one of more units. - :param units: A string, or list of strings specifying the - systemd units for which journal entries will be - collected. + :param units: Which journald units to collect + :type units: ``str`` or a ``list`` of strings - :param boot: A string selecting a boot index using the - journalctl syntax. The special values 'this' and - 'last' are also accepted. + :param boot: A boot index using the journalctl syntax. The special + values 'this' and 'last' are also accepted. + :type boot: ``str`` - :param since: A string representation of the start time for - journal messages. + :param since: Start time for journal messages + :type since: ``str`` - :param until: A string representation of the end time for - journal messages. + :param until: End time forjournal messages + :type until: ``str`` - :param lines: The maximum number of lines to be collected. + :param lines: The maximum number of lines to be collected + :type lines: ``int`` - :param allfields: A bool. Include all journal fields - regardless of size or non-printable - characters. + :param allfields: Include all journal fields regardless of size or + non-printable characters + :type allfields: ``bool`` - :param output: A journalctl output control string, for - example "verbose". + :param output: Journalctl output control string, for example "verbose" + :type output: ``str`` + + :param timeout: An optional timeout in seconds + :type timeout: ``int`` + + :param identifier: An optional message identifier + :type identifier: ``str`` + + :param catalog: Augment lines with descriptions from the system catalog + :type catalog: ``bool`` - :param timeout: An optional timeout in seconds. - :param identifier: An optional message identifier. - :param catalog: Bool. If True, augment lines with descriptions - from the system catalog. :param sizelimit: Limit to the size of output returned in MB. Defaults to the value of --log-size. + :type sizelimit: ``int`` """ journal_cmd = "journalctl --no-pager " unit_opt = " --unit %s" @@ -1922,7 +2446,7 @@ class Plugin(object): self._log_debug("collected plugin '%s' in %s" % fields) def get_description(self): - """ This function will return the description for the plugin""" + """This function will return the description for the plugin""" try: return self.short_desc except Exception: @@ -1944,6 +2468,10 @@ class Plugin(object): 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`` + :rtype: ``bool`` """ # some files or packages have been specified for this package if any([self.files, self.packages, self.commands, self.kernel_mods, @@ -2006,6 +2534,10 @@ class Plugin(object): """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`` + :rtype: ``bool`` """ if self.architectures is None: return True @@ -2055,7 +2587,13 @@ class Plugin(object): def check_process_by_name(self, process): """Checks if a named process is found in /proc/[0-9]*/cmdline. - Returns either True or False.""" + + :param process: The name of the process + :type process: ``str`` + + :returns: ``True`` if the process exists, else ``False`` + :rtype: ``bool`` + """ status = False cmd_line_glob = "/proc/[0-9]*/cmdline" try: @@ -2070,8 +2608,14 @@ class Plugin(object): return status def get_process_pids(self, process): - """Returns PIDs of all processes with process name. - If the process doesn't exist, returns an empty list""" + """Get a list of all PIDs that match a specified name + + :param process: The name of the process the get PIDs for + :type process: ``str`` + + :returns: A list of PIDs + :rtype: ``list`` + """ pids = [] cmd_line_glob = "/proc/[0-9]*/cmdline" cmd_line_paths = glob.glob(cmd_line_glob) |