certbot.util module

Utilities for all Certbot.

class certbot.util.Key(file: str | None, pem: bytes)[source]
Bases: NamedTuple

Container for an optional file path and contents for a PEM-formated private key.

file: str | None
Alias for field number 0

pem: bytes
Alias for field number 1

class certbot.util.CSR(file: str | None, data: bytes, form: str)[source]
Bases: NamedTuple

Container for an optional file path and contents for a PEM or DER-formatted CSR.

file: str | None
Alias for field number 0

data: bytes
Alias for field number 1

form: str
Alias for field number 2

class certbot.util.LooseVersion(version_string: str)[source]
Bases: object

A version with loose rules, i.e. any given string is a valid version number.

but regular comparison is not supported. Instead, the try_risky_comparison method is provided, which may return an error if two LooseVersions are ‘incomparible’. For example when integer and string version components are present in the same position.

Differences with old distutils.version.LooseVersion: (https://github.com/python/cpython/blob/v3.10.0/Lib/distutils/version.py#L269) Most version comparisons should give the same result. However, if a version has multiple trailing zeroes, not all of them are used in the comparison. This ensure that, for example, “2.0” and “2.0.0” are equal.

try_risky_comparison(other: LooseVersion) → int[source]
Compares the LooseVersion to another value.

If the other value is another LooseVersion, the version components are compared. Otherwise, an exception is raised.

Comparison is performed element-wise. If the version components being compared are of different types, the two versions are considered incompatible. Otherwise, if either of the components is not equal to the other, less or greater is returned based on the comparison’s result. In case the two versions are of different lengths, some elements in the longer version have not yet been compared. If these are all equal to zero, the two versions are equal. Otherwise, the longer version is greater.

If the two versions are incompatible, an exception is raised. Otherwise, the returned integer indicates the result of the comparison. If self == other, 0 is returned. If self > other, 1 is returned. If self < other -1 is returned.

Examples: Equality: - LooseVersion(‘1.0’).try_risky_comparison(LooseVersion(‘1.0’)) -> 0 - LooseVersion(‘2.0.0a’).try_risky_comparison(LooseVersion(‘2.0.0a’)) -> 0 Inequality: - LooseVersion(‘2.0.0’).try_risky_comparison(LooseVersion(‘1.0’)) -> 1 - LooseVersion(‘1.0.1’).try_risky_comparison(LooseVersion(‘2.0a’)) -> -1 Incomparability: - LooseVersion(‘1a’).try_risky_comparison(LooseVersion(‘1.0’)) -> ValueError

certbot.util.env_no_snap_for_external_calls() → dict[str, str][source]
When Certbot is run inside a Snap, certain environment variables are modified. But Certbot sometimes calls out to external programs, since it uses classic confinement. When we do that, we must modify the env to remove our modifications so it will use the system’s libraries, since they may be incompatible with the versions of libraries included in the Snap. For example, apachectl, Nginx, and anything run from inside a hook should call this function and pass the results into the env argument of subprocess.Popen.

Returns:
A modified copy of os.environ ready to pass to Popen

Return type:
dict

certbot.util.run_script(

params: list[str], log: ~typing.Callable[[str], None] =

method Logger.error of

certbot.util (WARNING)>>) → tuple[str, str][source]

Run the script with the given params.

Parameters:

• params (list) – List of parameters to pass to subprocess.run

• log (callable) – Logger method to use for errors

certbot.util.exe_exists(exe: str) → bool[source]
Determine whether path/name refers to an executable.

Parameters:
exe (str) – Executable path or name

Returns:
If exe is a valid executable

Return type:
bool

certbot.util.lock_dir_until_exit(dir_path: str) → None[source]
Lock the directory at dir_path until program exit.

Parameters:
dir_path (str) – path to directory

Raises:
errors.LockError – if the lock is held by another process

certbot.util.set_up_core_dir(directory: str, mode: int, strict: bool) → None[source]
Ensure directory exists with proper permissions and is locked.

Parameters:

• directory (str) – Path to a directory.

• mode (int) – Directory mode.

• strict (bool) – require directory to be owned by current user

Raises:

• .errors.LockError – if the directory cannot be locked

• .errors.Error – if the directory cannot be made or verified

certbot.util.make_or_verify_dir(directory: str, mode: int = 493, strict: bool = False) → None[source]
Make sure directory exists with proper permissions.

Parameters:

• directory (str) – Path to a directory.

• mode (int) – Directory mode.

• strict (bool) – require directory to be owned by current user

Raises:

• .errors.Error – if a directory already exists, but has wrong permissions or owner

• OSError – if invalid or inaccessible file names and paths, or other arguments that have the correct type, but are not accepted by the operating system.

certbot.util.safe_open(path: str, mode: str = 'w', chmod: int | None = None) → IO[source]
Safely open a file.

Parameters:

• path (str) – Path to a file.

• mode (str) – Same os mode for open.

• chmod (int) – Same as mode for filesystem.open, uses Python defaults if None.

certbot.util.unique_file(path: str, chmod: int = 511, mode: str = 'w') → tuple[IO, str][source]
Safely finds a unique file.

Parameters:

• path (str) – path/filename.ext

• chmod (int) – File mode

• mode (str) – Open mode

Returns:
tuple of file object and file name

certbot.util.unique_lineage_name(path: str, filename: str, chmod: int = 420, mode: str = 'w') → tuple[IO, str][source]
Safely finds a unique file using lineage convention.

Parameters:

• path (str) – directory path

• filename (str) – proposed filename

• chmod (int) – file mode

• mode (str) – open mode

Returns:
tuple of file object and file name (which may be modified from the requested one by appending digits to ensure uniqueness)

Raises:
OSError – if writing files fails for an unanticipated reason, such as a full disk or a lack of permission to write to specified location.

certbot.util.safely_remove(path: str) → None[source]
Remove a file that may not exist.

certbot.util.get_filtered_names(all_names: set[str]) → set[str][source]
Removes names that aren’t considered valid by Let’s Encrypt.

Parameters:
all_names (set) – all names found in the configuration

Returns:
all found names that are considered valid by LE

Return type:
set

certbot.util.get_os_info() → tuple[str, str][source]
Get OS name and version

Returns:
(os_name, os_version)

Return type:
tuple of str

certbot.util.get_os_info_ua() → str[source]
Get OS name and version string for User Agent

Returns:
os_ua

Return type:
str

certbot.util.get_systemd_os_like() → list[str][source]
Get a list of strings that indicate the distribution likeness to other distributions.

Returns:
List of distribution acronyms

Return type:
list of str

certbot.util.get_var_from_file(varname: str, filepath: str = '/etc/os-release') → str[source]
Get single value from a file formatted like systemd /etc/os-release

Parameters:

• varname (str) – Name of variable to fetch

• filepath (str) – File path of os-release file

Returns:
requested value

Return type:
str

certbot.util.get_python_os_info(pretty: bool = False) → tuple[str, str][source]
Get Operating System type/distribution and major version using python platform module

Parameters:
pretty (bool) – If the returned OS name should be in longer (pretty) form

Returns:
(os_name, os_version)

Return type:
tuple of str

certbot.util.safe_email(email: str) → bool[source]
Scrub email address before using it.

class certbot.util.DeprecatedArgumentAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Bases: Action

Action to log a warning when an argument is used.

certbot.util.add_deprecated_argument(add_argument: Callable[[...], None], argument_name: str, nargs: str | int) → None[source]
Adds a deprecated argument with the name argument_name.

Deprecated arguments are not shown in the help. If they are used on the command line, a warning is shown stating that the argument is deprecated and no other action is taken.

Parameters:

• add_argument (callable) – Function that adds arguments to an argument parser/group.

• argument_name (str) – Name of deprecated argument.

• nargs – Value for nargs when adding the argument to argparse.

certbot.util.enforce_le_validity(domain: str) → str[source]
Checks that Let’s Encrypt will consider domain to be valid.

Parameters:
domain (str) – FQDN to check

Returns:
The domain cast to str, with ASCII-only contents

Return type:
str

Raises:
ConfigurationError – for invalid domains and cases where Let’s Encrypt currently will not issue certificates

certbot.util.enforce_domain_sanity(domain: str | bytes) → str[source]
Method which validates domain value and errors out if the requirements are not met.

Parameters:
domain (str or bytes) – Domain to check

Raises:
ConfigurationError – for invalid domains and cases where Let’s Encrypt currently will not issue certificates

Returns:
The domain cast to str, with ASCII-only contents

Return type:
str

certbot.util.is_ipaddress(address: str) → bool[source]
Is given address string form of IP(v4 or v6) address?

Parameters:
address (str) – address to check

Returns:
True if address is valid IP address, otherwise return False.

Return type:
bool

certbot.util.is_wildcard_domain(domain: str | bytes) → bool[source]
“Is domain a wildcard domain?

Parameters:
domain (bytes or str) – domain to check

Returns:
True if domain is a wildcard, otherwise, False

Return type:
bool

certbot.util.is_staging(srv: str) → bool[source]
Determine whether a given ACME server is a known test / staging server.

Parameters:
srv (str) – the URI for the ACME server

Returns:
True iff srv is a known test / staging server

Rtype bool:

certbot.util.atexit_register(func: Callable, *args: Any, **kwargs: Any) → None[source]
Sets func to be called before the program exits.

Special care is taken to ensure func is only called when the process that first imports this module exits rather than any child processes.

Parameters:
func (function) – function to be called in case of an error

certbot.util.parse_loose_version(version_string: str) → list[int | str][source]
Parses a version string into its components. This code and the returned tuple is based on the now deprecated distutils.version.LooseVersion class from the Python standard library. Two LooseVersion classes and two lists as returned by this function should compare in the same way. See https://github.com/python/cpython/blob/v3.10.0/Lib/distutils/version.py#L205-L347. :param str version_string: version string :returns: list of parsed version string components :rtype: list