`certbot.interfaces`¶

Certbot client interfaces.

class certbot.interfaces.AccountStorage[source]¶

Bases: object

Accounts storage interface.

find_all()[source]¶

Find all accounts.

Returns:	All found accounts.
Return type:	list

load(account_id)[source]¶

Load an account by its id.

Raises:	AccountNotFound – if account could not be found AccountStorageError – if account could not be loaded

save(account, client)[source]¶

Save account.

Raises:	AccountStorageError – if account could not be saved

interface certbot.interfaces.IPluginFactory[source]¶

IPlugin factory.

Objects providing this interface will be called without satisfying any entry point “extras” (extra dependencies) you might have defined for your plugin, e.g (excerpt from setup.py script):

setup(
    ...
    entry_points={
        'certbot.plugins': [
            'name=example_project.plugin[plugin_deps]',
        ],
    },
    extras_require={
        'plugin_deps': ['dep1', 'dep2'],
    }
)

Therefore, make sure such objects are importable and usable without extras. This is necessary, because CLI does the following operations (in order):

loads an entry point,

calls inject_parser_options,

requires an entry point,

creates plugin instance (__call__).

description¶: Short plugin description

__call__(config, name)¶

Create new IPlugin.

Parameters:	config (IConfig) – Configuration. name (str) – Unique plugin name.

inject_parser_options(parser, name)¶

Inject argument parser options (flags).

1. Be nice and prepend all options and destinations with option_namespace and dest_namespace.

2. Inject options (flags) only. Positional arguments are not allowed, as this would break the CLI.

Parameters:	parser (ArgumentParser) – (Almost) top-level CLI parser. name (str) – Unique plugin name.

interface certbot.interfaces.IPlugin[source]¶

Certbot plugin.

prepare()¶

Prepare the plugin.

Finish up any additional initialization.

Raises:

PluginError – when full initialization cannot be completed.
MisconfigurationError – when full initialization cannot be completed. Plugin will be displayed on a list of available plugins.
NoInstallationError – when the necessary programs/files cannot be located. Plugin will NOT be displayed on a list of available plugins.
NotSupportedError – when the installation is recognized, but the version is not currently supported.

more_info()¶

Human-readable string to help the user.

Should describe the steps taken and any relevant info to help the user decide which plugin to use.

Rtype str:

interface certbot.interfaces.IAuthenticator[source]¶

Extends: certbot.interfaces.IPlugin

Generic Certbot Authenticator.

Class represents all possible tools processes that have the ability to perform challenges and attain a certificate.

get_chall_pref(domain)¶

Return collections.Iterable of challenge preferences.

Parameters:	domain (str) – Domain for which challenge preferences are sought.
Returns:	`collections.Iterable` of challenge types (subclasses of `acme.challenges.Challenge`) with the most preferred challenges first. If a type is not specified, it means the Authenticator cannot perform the challenge.
Return type:	`collections.Iterable`

perform(achalls)¶

Perform the given challenge.

Parameters:	achalls (list) – Non-empty (guaranteed) list of `AnnotatedChallenge` instances, such that it contains types found within `get_chall_pref()` only.
Returns:	`collections.Iterable` of ACME `ChallengeResponse` instances or if the `Challenge` cannot be fulfilled then: `None` Authenticator can perform challenge, but not at this time. `False` Authenticator will never be able to perform (error).
Return type:	`collections.Iterable` of `acme.challenges.ChallengeResponse`, where responses are required to be returned in the same order as corresponding input challenges
Raises:	PluginError – If challenges cannot be performed

cleanup(achalls)¶

Revert changes and shutdown after challenges complete.

This method should be able to revert all changes made by perform, even if perform exited abnormally.

Parameters:	achalls (list) – Non-empty (guaranteed) list of `AnnotatedChallenge` instances, a subset of those previously passed to `perform()`.
Raises:	PluginError – if original configuration cannot be restored

interface certbot.interfaces.IConfig[source]¶

Certbot user-supplied configuration.

Warning

The values stored in the configuration have not been filtered, stripped or sanitized.

server¶: ACME Directory Resource URI.

email¶: Email used for registration and recovery contact. (default: Ask)

rsa_key_size¶: Size of the RSA key.

must_staple¶: Adds the OCSP Must Staple extension to the certificate. Autoconfigures OCSP Stapling for supported setups (Apache version >= 2.3.3 ).

config_dir¶: Configuration directory.

work_dir¶: Working directory.

accounts_dir¶: Directory where all account information is stored.

backup_dir¶: Configuration backups directory.

csr_dir¶: Directory where newly generated Certificate Signing Requests (CSRs) are saved.

in_progress_dir¶: Directory used before a permanent checkpoint is finalized.

key_dir¶: Keys storage.

temp_checkpoint_dir¶: Temporary checkpoint directory.

no_verify_ssl¶: Disable verification of the ACME server’s certificate.

tls_sni_01_port¶: Port used during tls-sni-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 443.

tls_sni_01_address¶: The address the server listens to during tls-sni-01 challenge.

http01_port¶: Port used in the http-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 80.

http01_address¶: The address the server listens to during http-01 challenge.

pref_challs¶: Sorted user specified preferred challengestype strings with the most preferred challenge listed first

allow_subset_of_names¶: When performing domain validation, do not consider it a failure if authorizations can not be obtained for a strict subset of the requested domains. This may be useful for allowing renewals for multiple domains to succeed even if some domains no longer point at this system. This is a boolean

strict_permissions¶: Require that all configuration files are owned by the current user; only needed if your config is somewhere unsafe like /tmp/.This is a boolean

interface certbot.interfaces.IInstaller[source]¶

Extends: certbot.interfaces.IPlugin

Generic Certbot Installer Interface.

Represents any server that an X509 certificate can be placed.

It is assumed that save() is the only method that finalizes a checkpoint. This is important to ensure that checkpoints are restored in a consistent manner if requested by the user or in case of an error.

Using certbot.reverter.Reverter to implement checkpoints, rollback, and recovery can dramatically simplify plugin development.

get_all_names()¶

Returns all names that may be authenticated.

Return type:	`collections.Iterable` of `str`

deploy_cert(domain, cert_path, key_path, chain_path, fullchain_path)¶

Deploy certificate.

Parameters:	domain (str) – domain to deploy certificate file cert_path (str) – absolute path to the certificate file key_path (str) – absolute path to the private key file chain_path (str) – absolute path to the certificate chain file fullchain_path (str) – absolute path to the certificate fullchain file (cert plus chain)
Raises:	PluginError – when cert cannot be deployed

enhance(domain, enhancement, options=None)¶

Perform a configuration enhancement.

Parameters:	domain (str) – domain for which to provide enhancement enhancement (str) – An enhancement as defined in `ENHANCEMENTS` options – Flexible options parameter for enhancement. Check documentation of `ENHANCEMENTS` for expected options for each enhancement.
Raises:	PluginError – If Enhancement is not supported, or if an error occurs during the enhancement.

supported_enhancements()¶

Returns a collections.Iterable of supported enhancements.

Returns:	supported enhancements which should be a subset of `ENHANCEMENTS`
Return type:	`collections.Iterable` of `str`

save(title=None, temporary=False)¶

Saves all changes to the configuration files.

Both title and temporary are needed because a save may be intended to be permanent, but the save is not ready to be a full checkpoint.

It is assumed that at most one checkpoint is finalized by this method. Additionally, if an exception is raised, it is assumed a new checkpoint was not finalized.

Parameters:	title (str) – The title of the save. If a title is given, the configuration will be saved as a new checkpoint and put in a timestamped directory. `title` has no effect if temporary is true. temporary (bool) – Indicates whether the changes made will be quickly reversed in the future (challenges)
Raises:	PluginError – when save is unsuccessful

rollback_checkpoints(rollback=1)¶

Revert rollback number of configuration checkpoints.

Raises:	PluginError – when configuration cannot be fully reverted

recovery_routine()¶

Revert configuration to most recent finalized checkpoint.

Remove all changes (temporary and permanent) that have not been finalized. This is useful to protect against crashes and other execution interruptions.

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

view_config_changes()¶

Display all of the LE config changes.

Raises:	PluginError – when config changes cannot be parsed

config_test()¶

Make sure the configuration is valid.

Raises:	MisconfigurationError – when the config is not in a usable state

restart()¶

Restart or refresh the server content.

Raises:	PluginError – when server cannot be restarted

interface certbot.interfaces.IDisplay[source]¶

Generic display.

notification(message, pause, wrap=True, force_interactive=False)¶

Displays a string message

Parameters:	message (str) – Message to display pause (bool) – Whether or not the application should pause for confirmation (if available) wrap (bool) – Whether or not the application should wrap text force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions

menu(message, choices, ok_label='OK', cancel_label='Cancel', help_label='', default=None, cli_flag=None, force_interactive=False)¶

Displays a generic menu.