# certbot.plugins.dns_common module

Common code for DNS Authenticator Plugins.

class certbot.plugins.dns_common.DNSAuthenticator(config: NamespaceConfig, name: str)

  Bases: `Plugin`, `Authenticator`

  Base class for DNS Authenticators

  classmethod add_parser_arguments(add: Callable[[...], None], default_propagation_seconds: int = 10) → 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.

  auth_hint(failed_achalls: list[AnnotatedChallenge]) → str

    See certbot.plugins.common.Plugin.auth_hint.

  get_chall_pref(unused_identifier: str) → Iterable[type[Challenge]]

    Return `collections.Iterable` of challenge preferences.

    Parameters:

      identifier (str) – Domain or IP address 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`

  prepare() → None

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

    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:

  perform(achalls: list[AnnotatedChallenge]) → list[ChallengeResponse]

    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:

      list of ACME `ChallengeResponse` instances corresponding to each provided `Challenge`.

    Return type:

      `collections.List` of `acme.challenges.ChallengeResponse`, where responses are required to be returned in the same order as corresponding input challenges

    Raises:

      .PluginError – If some or all challenges cannot be performed

  cleanup(achalls: list[AnnotatedChallenge]) → None

    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

class certbot.plugins.dns_common.CredentialsConfiguration(filename: str, mapper: ~typing.Callable[[str], str] = <function CredentialsConfiguration.<lambda>>)

  Bases: `object`

  Represents a user-supplied filed which stores API credentials.

  require(required_variables: Mapping[str, str]) → None

    Ensures that the supplied set of variables are all present in the file.

    Parameters:

      required_variables (dict) – Map of variable which must be present to error to display.

    Raises:

      errors.PluginError – If one or more are missing.

  conf(var: str) → str | None

    Find a configuration value for variable `var`, as transformed by `mapper`.

    Parameters:

      var (str) – The variable to get.

    Returns:

      The value of the variable, if it exists.

    Return type:

      str or None

certbot.plugins.dns_common.validate_file(filename: str) → None

  Ensure that the specified file exists.

certbot.plugins.dns_common.validate_file_permissions(filename: str) → None

  Ensure that the specified file exists and warn about unsafe permissions.

certbot.plugins.dns_common.base_domain_name_guesses(domain: str) → list[str]

  Return a list of progressively less-specific domain names.

  One of these will probably be the domain name known to the DNS provider.

  Example:

      >>> base_domain_name_guesses('foo.bar.baz.example.com')
      ['foo.bar.baz.example.com', 'bar.baz.example.com', 'baz.example.com', 'example.com', 'com']

  Parameters:

    domain (str) – The domain for which to return guesses.

  Returns:

    The a list of less specific domain names.

  Return type:

    list