# certbot.util module

Utilities for all Certbot.

class certbot.util.Key(file, pem)

  Bases: `tuple`

  file

    Alias for field number 0

  pem

    Alias for field number 1

class certbot.util.CSR(file, data, form)

  Bases: `tuple`

  data

    Alias for field number 1

  file

    Alias for field number 0

  form

    Alias for field number 2

certbot.util.env_no_snap_for_external_calls()

  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, log=<bound method Logger.error of <Logger certbot.util (WARNING)>>)

  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)

  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)

  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, mode, strict)

  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, mode=493, strict=False)

  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=None) → IO

  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, chmod=511, mode='w')

  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, filename, chmod=420, mode='w')

  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)

  Remove a file that may not exist.

certbot.util.get_filtered_names(all_names)

  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()

  Get OS name and version

  Returns

    (os_name, os_version)

  Return type

    `tuple` of `str`

certbot.util.get_os_info_ua()

  Get OS name and version string for User Agent

  Returns

    os_ua

  Return type

    `str`

certbot.util.get_systemd_os_like()

  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, filepath='/etc/os-release')

  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=False)

  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)

  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)

  Bases: `argparse.Action`

  Action to log a warning when an argument is used.

certbot.util.add_deprecated_argument(add_argument, argument_name, nargs)

  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)

  Checks that Let’s Encrypt will consider domain to be valid.

  Parameters

    domain (`str` or `unicode`) – 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)

  Method which validates domain value and errors out if the requirements are not met.

  Parameters

    domain (`str` or `unicode`) – 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)

  Is given address string form of IP(v4 or v6) address?

  Parameters

    address (`str` or `unicode`) – address to check

  Returns

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

  Return type

    bool

certbot.util.is_wildcard_domain(domain)

  “Is domain a wildcard domain?

  Parameters

    domain (`bytes` or `str` or `unicode`) – domain to check

  Returns

    True if domain is a wildcard, otherwise, False

  Return type

    bool

certbot.util.get_strict_version(normalized)

  Converts a normalized version to a strict version.

  Parameters

    normalized (str) – normalized version string

  Returns

    An equivalent strict version

  Return type

    distutils.version.StrictVersion

certbot.util.is_staging(srv)

  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, *args, **kwargs)

  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