# certbot.plugins.common module

Plugin common functions.

certbot.plugins.common.option_namespace(name)

  ArgumentParser options namespace (prefix of all options).

certbot.plugins.common.dest_namespace(name)

  ArgumentParser dest namespace (prefix of all destinations).

class certbot.plugins.common.Plugin(config, name)

  Bases: `certbot.interfaces.Plugin`

  Generic plugin.

  abstract classmethod add_parser_arguments(add)

    Add plugin arguments to the CLI argument parser.

    Parameters

      add (callable) – Function that proxies calls to `argparse.ArgumentParser.add_argument` prepending options with unique plugin name prefix.

  classmethod inject_parser_options(parser, name)

    Inject parser options.

    See `inject_parser_options` for docs.

  property option_namespace

    ArgumentParser options namespace (prefix of all options).

  option_name(name)

    Option name (include plugin namespace).

  property dest_namespace

    ArgumentParser dest namespace (prefix of all destinations).

  dest(var)

    Find a destination for given variable `var`.

  conf(var)

    Find a configuration value for variable `var`.

  auth_hint(failed_achalls: List[certbot.achallenges.AnnotatedChallenge]) → str

    Human-readable string to help the user troubleshoot the authenticator.

    Shown to the user if one or more of the attempted challenges were not a success.

    Should describe, in simple language, what the authenticator tried to do, what went wrong and what the user should try as their “next steps”.

    TODO: auth_hint belongs in Authenticator but can’t be added until the next major version of Certbot. For now, it lives in .Plugin and auth_handler will only call it on authenticators that subclass .Plugin. For now, inherit from `Plugin` to implement and/or override the method.

    Parameters

      failed_achalls (list) – List of one or more failed challenges (`achallenges.AnnotatedChallenge` subclasses).

    Rtype str

class certbot.plugins.common.Installer(*args, **kwargs)

  Bases: `certbot.interfaces.Installer`, `certbot.plugins.common.Plugin`

  An installer base class with reverter and ssl_dhparam methods defined.

  Installer plugins do not have to inherit from this class.

  add_to_checkpoint(save_files, save_notes, temporary=False)

    Add files to a checkpoint.

    Parameters

      - save_files (set) – set of filepaths to save

      - save_notes (str) – notes about changes during the save

      - temporary (bool) – True if the files should be added to a temporary checkpoint rather than a permanent one. This is usually used for changes that will soon be reverted.

    Raises

      errors.PluginError – when unable to add to checkpoint

  finalize_checkpoint(title)

    Timestamp and save changes made through the reverter.

    Parameters

      title (str) – Title describing checkpoint

    Raises

      errors.PluginError – when an error occurs

  recovery_routine()

    Revert all previously modified files.

    Reverts all modified files that have not been saved as a checkpoint

    Raises

      errors.PluginError – If unable to recover the configuration

  revert_temporary_config()

    Rollback temporary checkpoint.

    Raises

      errors.PluginError – when unable to revert config

  rollback_checkpoints(rollback=1)

    Rollback saved checkpoints.

    Parameters

      rollback (int) – Number of checkpoints to revert

    Raises

      errors.PluginError – If there is a problem with the input or the function is unable to correctly revert the configuration

  property ssl_dhparams

    Full absolute path to ssl_dhparams file.

  property updated_ssl_dhparams_digest

    Full absolute path to digest of updated ssl_dhparams file.

  install_ssl_dhparams()

    Copy Certbot’s ssl_dhparams file into the system’s config dir if required.

class certbot.plugins.common.Addr(tup, ipv6=False)

  Bases: `object`

  Represents an virtual host address.

  Parameters

    - addr (str) – addr part of vhost address

    - port (str) – port number or *, or “”

  classmethod fromstring(str_addr)

    Initialize Addr from string.

  normalized_tuple()

    Normalized representation of addr/port tuple

  get_addr()

    Return addr part of Addr object.

  get_port()

    Return port.

  get_addr_obj(port)

    Return new address object with same addr and new port.

  get_ipv6_exploded()

    Return IPv6 in normalized form

class certbot.plugins.common.ChallengePerformer(configurator)

  Bases: `object`

  Abstract base for challenge performers.

  Variables

    - configurator – Authenticator and installer plugin

    - achalls (`list` of `KeyAuthorizationAnnotatedChallenge`) – Annotated challenges

    - indices (`list` of `int`) – Holds the indices of challenges from a larger array so the user of the class doesn’t have to.

  add_chall(achall, idx=None)

    Store challenge to be performed when perform() is called.

    Parameters

      - achall (KeyAuthorizationAnnotatedChallenge) – Annotated challenge.

      - idx (int) – index to challenge in a larger array

  perform()

    Perform all added challenges.

    Returns

      challenge responses

    Return type

      `list` of `acme.challenges.KeyAuthorizationChallengeResponse`

certbot.plugins.common.install_version_controlled_file(dest_path, digest_path, src_path, all_hashes)

  Copy a file into an active location (likely the system’s config dir) if required.

  Parameters

    - dest_path (str) – destination path for version controlled file

    - digest_path (str) – path to save a digest of the file in

    - src_path (str) – path to version controlled file found in distribution

    - all_hashes (list) – hashes of every released version of the file

certbot.plugins.common.dir_setup(test_dir, pkg)

  Setup the directories necessary for the configurator.