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.

abstractmethod classmethod add_parser_arguments(add: Callable[[...], None]) → None[source]
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[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.

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)[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.

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[source]
Timestamp and save changes made through the reverter.

Parameters:
title (str) – Title describing checkpoint

Raises:
.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

Raises:
.errors.PluginError – If unable to recover the configuration

revert_temporary_config() → None[source]
Rollback temporary checkpoint.

Raises:
.errors.PluginError – when unable to revert config

rollback_checkpoints(rollback: int = 1) → None[source]
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[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.

Parameters:

• addr (str) – addr part of vhost address

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

classmethod fromstring(str_addr: str) → GenericAddr[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.

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[source]
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][source]
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[source]
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][source]
Setup the directories necessary for the configurator.