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.

abstract 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 | None

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.