# certbot.plugins.common module

Plugin common functions.

certbot.plugins.common.option_namespace(name: str) → str

  ArgumentParser options namespace (prefix of all options).

certbot.plugins.common.dest_namespace(name: str) → str

  ArgumentParser dest namespace (prefix of all destinations).

class certbot.plugins.common.Plugin(config: NamespaceConfig, name: str)

  Bases: `Plugin`

  Generic plugin.

  abstractmethod classmethod add_parser_arguments(add: Callable[[...], None]) → None

    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: ArgumentParser, name: str) → None

    Inject parser options.

    See `inject_parser_options` for docs.

  property option_namespace: str

    ArgumentParser options namespace (prefix of all options).

  option_name(name: str) → str

    Option name (include plugin namespace).

  property dest_namespace: str

    ArgumentParser dest namespace (prefix of all destinations).

  dest(var: str) → str

    Find a destination for given variable `var`.

  conf(var: str) → Any

    Find a configuration value for variable `var`.

  auth_hint(failed_achalls: list[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: Any, **kwargs: Any)

  Bases: `Installer`, `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: set[str], save_notes: str, temporary: bool = False) → None

    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: str) → None

    Timestamp and save changes made through the reverter.

    Parameters:

      title (str) – Title describing checkpoint

    Raises:

      .errors.PluginError – when an error occurs

  recovery_routine() → None

    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() → None

    Rollback temporary checkpoint.

    Raises:

      .errors.PluginError – when unable to revert config

  rollback_checkpoints(rollback: int = 1) → None

    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: str

    Full absolute path to ssl_dhparams file.

  property updated_ssl_dhparams_digest: str

    Full absolute path to digest of updated ssl_dhparams file.

  install_ssl_dhparams() → None

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

class certbot.plugins.common.Configurator(*args: Any, **kwargs: Any)

  Bases: `Installer`, `Authenticator`

  A plugin that extends certbot.plugins.common.Installer and implements certbot.interfaces.Authenticator

class certbot.plugins.common.Addr(tup: tuple[str, str], ipv6: bool = 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: str) → GenericAddr

    Initialize Addr from string.

  normalized_tuple() → tuple[str, str]

    Normalized representation of addr/port tuple

  get_addr() → str

    Return addr part of Addr object.

  get_port() → str

    Return port.

  get_addr_obj(port: str) → GenericAddr

    Return new address object with same addr and new port.

  get_ipv6_exploded() → str

    Return IPv6 in normalized form

class certbot.plugins.common.ChallengePerformer(configurator: 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: KeyAuthorizationAnnotatedChallenge, idx: int | None = None) → 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() → list[KeyAuthorizationChallengeResponse]

    Perform all added challenges.

    Returns:

      challenge responses

    Return type:

      `list` of `acme.challenges.KeyAuthorizationChallengeResponse`

certbot.plugins.common.install_version_controlled_file(dest_path: str, digest_path: str, src_path: str, all_hashes: Iterable[str]) → None

  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: str, pkg: str) → tuple[str, str, str]

  Setup the directories necessary for the configurator.