certbot.plugins.common module

Plugin common functions.

certbot.plugins.common.option_namespace(name: str) str[source]

ArgumentParser options namespace (prefix of all options).

certbot.plugins.common.dest_namespace(name: str) str[source]

ArgumentParser dest namespace (prefix of all destinations).

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

Bases: Plugin

Generic plugin.

abstract classmethod add_parser_arguments(add: Callable[[...], None]) None[source]

Add plugin arguments to the CLI argument parser.


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[source]

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[source]

Option name (include plugin namespace).

property dest_namespace: str

ArgumentParser dest namespace (prefix of all destinations).

dest(var: str) str[source]

Find a destination for given variable var.

conf(var: str) Any[source]

Find a configuration value for variable var.

auth_hint(failed_achalls: List[AnnotatedChallenge]) str[source]

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.


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

Rtype str:

class certbot.plugins.common.Installer(*args: Any, **kwargs: Any)[source]

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[source]

Add files to a checkpoint.

  • 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.


.errors.PluginError – when unable to add to checkpoint

finalize_checkpoint(title: str) None[source]

Timestamp and save changes made through the reverter.


title (str) – Title describing checkpoint


.errors.PluginError – when an error occurs

recovery_routine() None[source]

Revert all previously modified files.

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


.errors.PluginError – If unable to recover the configuration

revert_temporary_config() None[source]

Rollback temporary checkpoint.


.errors.PluginError – when unable to revert config

rollback_checkpoints(rollback: int = 1) None[source]

Rollback saved checkpoints.


rollback (int) – Number of checkpoints to revert


.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[source]

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

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

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)[source]

Bases: object

Represents an virtual host address.

  • addr (str) – addr part of vhost address

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

classmethod fromstring(str_addr: str) GenericAddr | None[source]

Initialize Addr from string.

normalized_tuple() Tuple[str, str][source]

Normalized representation of addr/port tuple

get_addr() str[source]

Return addr part of Addr object.

get_port() str[source]

Return port.

get_addr_obj(port: str) GenericAddr[source]

Return new address object with same addr and new port.

get_ipv6_exploded() str[source]

Return IPv6 in normalized form

class certbot.plugins.common.ChallengePerformer(configurator: Configurator)[source]

Bases: object

Abstract base for challenge performers.

  • 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[source]

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

  • achall (.KeyAuthorizationAnnotatedChallenge) – Annotated challenge.

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

perform() List[KeyAuthorizationChallengeResponse][source]

Perform all added challenges.


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[source]

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

  • 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][source]

Setup the directories necessary for the configurator.