Skip to content

REFERENCE.md

Latest commit

 

History

History
1239 lines (737 loc) · 36.3 KB

REFERENCE.md

File metadata and controls

1239 lines (737 loc) · 36.3 KB

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • letsencrypt::config: Configures the Let's Encrypt client.
  • letsencrypt::install: Installs the Let's Encrypt client.
  • letsencrypt::scripts: Deploy helper scripts scripts

Defined types

Functions

Data types

Classes

letsencrypt

Install and configure Certbot, the LetsEncrypt client

Examples

class { 'letsencrypt' :
  email  => '[email protected]',
  config => {
    'server' => 'https://acme-staging-v02.api.letsencrypt.org/directory',
  },
}

Parameters

The following parameters are available in the letsencrypt class:

email

Data type: Optional[String]

The email address to use to register with Let's Encrypt. This takes precedence over an 'email' setting defined in $config.

Default value: undef

environment

Data type: Array

An optional array of environment variables

Default value: []

package_name

Data type: String

Name of package and command to use when installing the client package.

Default value: 'certbot'

package_ensure

Data type: String[1]

The value passed to ensure when installing the client package.

Default value: 'installed'

package_command

Data type: String

Path or name for letsencrypt executable.

Default value: 'certbot'

config_file

Data type: String

The path to the configuration file for the letsencrypt cli.

Default value: "${config_dir}/cli.ini"

config

Data type: Hash

A hash representation of the letsencrypt configuration file.

Default value: { 'server' => 'https://acme-v02.api.letsencrypt.org/directory' }

cron_scripts_path

Data type: String

The path for renewal scripts called by cron

Default value: "${facts['puppet_vardir']}/letsencrypt"

cron_owner_group

Data type: String

Group owner of cron renew scripts.

Default value: 'root'

manage_config

Data type: Boolean

A feature flag to toggle the management of the letsencrypt configuration file.

Default value: true

manage_install

Data type: Boolean

A feature flag to toggle the management of the letsencrypt client installation.

Default value: true

configure_epel

Data type: Boolean

A feature flag to include the 'epel' class and depend on it for package installation.

Default value: false

agree_tos

Data type: Boolean

A flag to agree to the Let's Encrypt Terms of Service.

Default value: true

unsafe_registration

Data type: Boolean

A flag to allow using the 'register-unsafely-without-email' flag.

Default value: false

config_dir

Data type: Stdlib::Unixpath

The path to the configuration directory.

Default value: '/etc/letsencrypt'

key_type

Data type: Enum['rsa', 'ecdsa']

Type of private key

Default value: 'rsa'

key_size

Data type: Integer[2048]

Size for the RSA public key

Default value: 4096

elliptic_curve

Data type: String[1]

The SECG elliptic curve name to use

Default value: 'secp256r1'

certificates

Data type: Hash[String[1],Hash]

A hash containing certificates. Each key is the title and each value is a hash, both passed to letsencrypt::certonly.

Default value: {}

renew_pre_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell before obtaining/renewing any certificates.

Default value: []

renew_post_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell after attempting to obtain/renew certificates.

Default value: []

renew_deploy_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell once for each successfully issued/renewed certificate. Two environmental variables are supplied by certbot:

  • $RENEWED_LINEAGE: Points to the live directory with the cert files and key. Example: /etc/letsencrypt/live/example.com
  • $RENEWED_DOMAINS: A space-delimited list of renewed certificate domains. Example: "example.com www.example.com"

Default value: []

renew_additional_args

Data type: Variant[String[1], Array[String[1]]]

Array of additional command line arguments to pass to 'certbot renew'.

Default value: []

renew_disable_distro_cron

Data type: Boolean

Boolean, set to true to disable the cron created by the distro package

Default value: false

renew_cron_ensure

Data type: String[1]

Intended state of the cron resource running certbot renew.

Default value: 'absent'

renew_cron_hour

Data type: Letsencrypt::Cron::Hour

Optional string, integer or array of hour(s) the renewal command should run. E.g. '[0,12]' to execute at midnight and midday. hour.

Default value: fqdn_rand(24)

renew_cron_minute

Data type: Letsencrypt::Cron::Minute

Optional string, integer or array of minute(s) the renewal command should run. E.g. 0 or '00' or [0,30].

Default value: fqdn_rand(60)

renew_cron_monthday

Data type: Letsencrypt::Cron::Monthday

Optional string, integer or array of monthday(s) the renewal command should run. E.g. '2-30/2' to run on even days.

Default value: '*'

renew_cron_environment

Data type: Optional[Variant[String[1], Array[String[1]]]]

Optional string or array of environments(s) the renewal command should have. E.g. PATH=/sbin:/usr/sbin:/bin:/usr/bin

Default value: undef

certonly_pre_hook_commands

Data type: Array[String[1]]

Array of commands to run in a shell before obtaining/renewing any certificates.

Default value: []

certonly_post_hook_commands

Data type: Array[String[1]]

Array of commands to run in a shell after attempting to obtain/renew certificates.

Default value: []

certonly_deploy_hook_commands

Data type: Array[String[1]]

Array of commands to run in a shell once for each successfully issued/renewed certificate. Two environmental variables are supplied by certbot:

  • $RENEWED_LINEAGE: Points to the live directory with the cert files and key. Example: /etc/letsencrypt/live/example.com
  • $RENEWED_DOMAINS: A space-delimited list of renewed certificate domains. Example: "example.com www.example.com"

Default value: []

letsencrypt::plugin::apache

install and configure the Let's Encrypt apache plugin

Parameters

The following parameters are available in the letsencrypt::plugin::apache class:

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

package_name

Data type: String[1]

The name of the package to install when $manage_package is true.

Default value: 'python3-certbot-apache'

letsencrypt::plugin::dns_cloudflare

This class installs and configures the Let's Encrypt dns-cloudflare plugin. https://certbot-dns-cloudflare.readthedocs.io

Parameters

The following parameters are available in the letsencrypt::plugin::dns_cloudflare class:

package_name

Data type: Optional[String[1]]

The name of the package to install when $manage_package is true.

Default value: undef

api_key

Data type: Optional[String[1]]

Optional string, cloudflare api key value for authentication.

Default value: undef

api_token

Data type: Optional[String[1]]

Optional string, cloudflare api token value for authentication.

Default value: undef

email

Data type: Optional[String[1]]

Optional string, cloudflare account email address, used in conjunction with api_key.

Default value: undef

config_path

Data type: Stdlib::Absolutepath

The path to the configuration directory.

Default value: "${letsencrypt::config_dir}/dns-cloudflare.ini"

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

propagation_seconds

Data type: Integer

Number of seconds to wait for the DNS server to propagate the DNS-01 challenge.

Default value: 10

letsencrypt::plugin::dns_linode

This class installs and configures the Let's Encrypt dns-linode plugin. https://certbot-dns-linode.readthedocs.io

Parameters

The following parameters are available in the letsencrypt::plugin::dns_linode class:

package_name

Data type: Optional[String[1]]

The name of the package to install when $manage_package is true.

Default value: undef

api_key

Data type: String[1]

Optional string, linode api key value for authentication.

version

Data type: String[1]

string, linode api version.

Default value: '4'

config_path

Data type: Stdlib::Absolutepath

The path to the configuration directory.

Default value: "${letsencrypt::config_dir}/dns-linode.ini"

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

propagation_seconds

Data type: Integer

Number of seconds to wait for the DNS server to propagate the DNS-01 challenge.

Default value: 120

letsencrypt::plugin::dns_rfc2136

This class installs and configures the Let's Encrypt dns-rfc2136 plugin. https://certbot-dns-rfc2136.readthedocs.io

Parameters

The following parameters are available in the letsencrypt::plugin::dns_rfc2136 class:

server

Data type: Stdlib::Host

Target DNS server.

key_name

Data type: String[1]

TSIG key name.

key_secret

Data type: String[1]

TSIG key secret.

key_algorithm

Data type: String[1]

TSIG key algorithm.

Default value: 'HMAC-SHA512'

port

Data type: Stdlib::Port

Target DNS port.

Default value: 53

propagation_seconds

Data type: Integer

Number of seconds to wait for the DNS server to propagate the DNS-01 challenge. (the plugin defaults to 60)

Default value: 10

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

package_name

Data type: String[1]

The name of the package to install when $manage_package is true.

config_dir

Data type: Stdlib::Absolutepath

The path to the configuration directory.

Default value: $letsencrypt::config_dir

letsencrypt::plugin::dns_route53

This class installs and configures the Let's Encrypt dns-route53 plugin. https://certbot-dns-route53.readthedocs.io

Parameters

The following parameters are available in the letsencrypt::plugin::dns_route53 class:

propagation_seconds

Data type: Integer

Number of seconds to wait for the DNS server to propagate the DNS-01 challenge.

Default value: 10

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

package_name

Data type: String[1]

The name of the package to install when $manage_package is true.

letsencrypt::plugin::nginx

install and configure the Let's Encrypt nginx plugin

Parameters

The following parameters are available in the letsencrypt::plugin::nginx class:

manage_package

Data type: Boolean

Manage the plugin package.

Default value: true

package_name

Data type: String[1]

The name of the package to install when $manage_package is true.

Default value: 'python3-certbot-nginx'

letsencrypt::renew

Configures renewal of Let's Encrypt certificates using the certbot renew command.

Note: Hooks set here will run before/after/for ALL certificates, including any not managed by Puppet. If you want to create hooks for specific certificates only, create them using letsencrypt::certonly.

Parameters

The following parameters are available in the letsencrypt::renew class:

pre_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell before obtaining/renewing any certificates.

Default value: $letsencrypt::renew_pre_hook_commands

post_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell after attempting to obtain/renew certificates.

Default value: $letsencrypt::renew_post_hook_commands

deploy_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell once for each successfully issued/renewed certificate. Two environmental variables are supplied by certbot:

  • $RENEWED_LINEAGE: Points to the live directory with the cert files and key. Example: /etc/letsencrypt/live/example.com
  • $RENEWED_DOMAINS: A space-delimited list of renewed certificate domains. Example: "example.com www.example.com"

Default value: $letsencrypt::renew_deploy_hook_commands

additional_args

Data type: Array[String[1]]

Array of additional command line arguments to pass to 'certbot renew'.

Default value: $letsencrypt::renew_additional_args

disable_distro_cron

Data type: Boolean

Boolean, set to true to disable the cron created by the distro package

Default value: $letsencrypt::renew_disable_distro_cron

distro_renew_cron_file

Data type: Optional[Stdlib::Unixpath]

Optional Unixpath, if set and if disable_distro_cron is true this file will be deleted (unless systemd is used)

Default value: undef

distro_renew_timer

Data type: Optional[String]

Optional String, name of the systemd timer to disable if disable_distro_cron is true

Default value: undef

cron_ensure

Data type: Enum['present', 'absent']

Intended state of the cron resource running certbot renew

Default value: $letsencrypt::renew_cron_ensure

cron_hour

Data type: Letsencrypt::Cron::Hour

Optional string, integer or array of hour(s) the renewal command should run. E.g. '[0,12]' to execute at midnight and midday. Default: fqdn-seeded random hour.

Default value: $letsencrypt::renew_cron_hour

cron_minute

Data type: Letsencrypt::Cron::Minute

Optional string, integer or array of minute(s) the renewal command should run. E.g. 0 or '00' or [0,30]. Default: fqdn-seeded random minute.

Default value: $letsencrypt::renew_cron_minute

cron_monthday

Data type: Letsencrypt::Cron::Monthday

Optional string, integer or array of monthday(s) the renewal command should run. E.g. '2-30/2' to run on even days. Default: Every day.

Default value: $letsencrypt::renew_cron_monthday

cron_environment

Data type: Optional[Variant[String[1], Array[String[1]]]]

Optional string or array of environment variables the renewal command should have. E.g. PATH=/sbin:/usr/sbin:/bin:/usr/bin

Default value: $letsencrypt::renew_cron_environment

Defined types

letsencrypt::certonly

This type can be used to request a certificate using the certonly installer.

Examples

standalone authenticator
# Request a certificate for `foo.example.com` using the `certonly`
# installer and the `standalone` authenticator.
letsencrypt::certonly { 'foo.example.com': }
Multiple domains
# Request a certificate for `foo.example.com` and `bar.example.com` using
# the `certonly` installer and the `standalone` authenticator.
letsencrypt::certonly { 'foo':
  domains => ['foo.example.com', 'bar.example.com'],
}
Apache authenticator
# Request a certificate for `foo.example.com` with the `certonly` installer
# and the `apache` authenticator.
letsencrypt::certonly { 'foo.example.com':
  plugin  => 'apache',
}
Nginx authenticator
# Request a certificate for `foo.example.com` with the `certonly` installer
# and the `nginx` authenticator.
letsencrypt::certonly { 'foo.example.com':
  plugin  => 'nginx',
}
webroot authenticator
# Request a certificate using the `webroot` authenticator. The paths to the
# webroots for all domains must be given through `webroot_paths`. If
# `domains` and `webroot_paths` are not the same length, the last
# `webroot_paths` element will be used for all subsequent domains.
letsencrypt::certonly { 'foo':
  domains       => ['foo.example.com', 'bar.example.com'],
  plugin        => 'webroot',
  webroot_paths => ['/var/www/foo', '/var/www/bar'],
}
dns-rfc2136 authenticator
# Request a certificate using the `dns-rfc2136` authenticator. Ideally the
# key `secret` should be encrypted, eg. with eyaml if using Hiera. It's
# also recommended to only enable access to the specific DNS records needed
# by the Let's Encrypt client.
#
# [Plugin documentation](https://certbot-dns-rfc2136.readthedocs.io)
class { 'letsencrypt::plugin::dns_rfc2136':
  server     => '192.0.2.1',
  key_name   => 'certbot',
  key_secret => '[...]==',
}

letsencrypt::certonly { 'foo.example.com':
  plugin        => 'dns-rfc2136',
}
dns-route53 authenticator
# Request a certificate for `foo.example.com` with the `certonly` installer
# and the `dns-route53` authenticator.
letsencrypt::certonly { 'foo.example.com':
  plugin  => 'dns-route53',
}
Additional arguments
# If you need to pass a command line flag to the `certbot` command that
# is not supported natively by this module, you can use the
# `additional_args` parameter to pass those arguments.
letsencrypt::certonly { 'foo.example.com':
  additional_args => ['--foo bar', '--baz quuz'],
}

Parameters

The following parameters are available in the letsencrypt::certonly defined type:

ensure

Data type: Enum['present','absent']

Intended state of the resource Will remove certificates for specified domains if set to 'absent'. Will also remove cronjobs and renewal scripts if manage_cron is set to 'true'.

Default value: 'present'

domains

Data type: Array[String[1]]

An array of domains to include in the CSR.

Default value: [$title]

custom_plugin

Data type: Boolean

Whether to use a custom plugin in additional_args and disable -a flag.

Default value: false

plugin

Data type: Letsencrypt::Plugin

The authenticator plugin to use when requesting the certificate.

Default value: 'standalone'

webroot_paths

Data type: Array[Stdlib::Unixpath]

An array of webroot paths for the domains in domains. Required if using plugin => 'webroot'. If domains and webroot_paths are not the same length, the last webroot_paths element will be used for all subsequent domains.

Default value: []

letsencrypt_command

Data type: String[1]

Command to run letsencrypt

Default value: $letsencrypt::command

additional_args

Data type: Array[String[1]]

An array of additional command line arguments to pass to the letsencrypt command.

Default value: []

environment

Data type: Array[String[1]]

An optional array of environment variables

Default value: []

key_type

Data type: Enum['rsa', 'ecdsa']

Type of private key

Default value: $letsencrypt::key_type

key_size

Data type: Integer[2048]

Size for the RSA public key

Default value: $letsencrypt::key_size

elliptic_curve

Data type: String[1]

The SECG elliptic curve name to use

Default value: $letsencrypt::elliptic_curve

manage_cron

Data type: Boolean

Indicating whether or not to schedule cron job for renewal. Runs daily but only renews if near expiration, e.g. within 10 days.

Default value: false

cron_output

Data type: Optional[Enum['suppress', 'log']]

How to treat cron output suppress - Suppress all output log - Forward cron output to syslog undef - Do nothing with cron output (default)

Default value: undef

cron_before_command

Data type: Optional[String[1]]

Representation of a command that should be run before renewal command

Default value: undef

cron_success_command

Data type: Optional[String[1]]

Representation of a command that should be run if the renewal command succeeds.

Default value: undef

cron_hour

Data type: Variant[Integer[0,23], String, Array]

Optional hour(s) that the renewal command should execute. e.g. '[0,12]' execute at midnight and midday. Default - seeded random hour, twice a day.

Default value: [fqdn_rand(12, $title), fqdn_rand(12, $title) + 12]

cron_minute

Data type: Variant[Integer[0,59], String, Array]

Optional minute(s) that the renewal command should execute. e.g. 0 or '00' or [0,30]. Default - seeded random minute.

Default value: fqdn_rand(60, $title)

cron_monthday

Data type: Array[Variant[Integer[0, 59], String[1]]]

Optional string, integer or array of monthday(s) the renewal command should run. E.g. '2-30/2' to run on even days. Default: Every day.

Default value: ['*']

config_dir

Data type: Stdlib::Unixpath

The path to the configuration directory.

Default value: $letsencrypt::config_dir

pre_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of commands to run in a shell before attempting to obtain/renew the certificate.

Default value: $letsencrypt::certonly_pre_hook_commands

post_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of command(s) to run in a shell after attempting to obtain/renew the certificate.

Default value: $letsencrypt::certonly_post_hook_commands

deploy_hook_commands

Data type: Variant[String[1], Array[String[1]]]

Array of command(s) to run in a shell once if the certificate is successfully issued. Two environmental variables are supplied by certbot:

  • $RENEWED_LINEAGE: Points to the live directory with the cert files and key. Example: /etc/letsencrypt/live/example.com
  • $RENEWED_DOMAINS: A space-delimited list of renewed certificate domains. Example: "example.com www.example.com"

Default value: $letsencrypt::certonly_deploy_hook_commands

cert_name

Data type: String[1]

the common name used for the certificate

Default value: $domains[0]

letsencrypt::hook

This type is used by letsencrypt::renew and letsencrypt::certonly to create hook scripts.

Parameters

The following parameters are available in the letsencrypt::hook defined type:

type

Data type: Enum['pre', 'post', 'deploy']

Hook type.

hook_file

Data type: String[1]

Path to deploy hook script.

commands

Data type: Variant[String[1],Array[String[1]]]

Bash commands to execute when the hook is run by certbot.

Functions

letsencrypt::letsencrypt_lookup

Type: Ruby 4.x API

The letsencrypt::letsencrypt_lookup function.

letsencrypt::letsencrypt_lookup(Any $common_name)

The letsencrypt::letsencrypt_lookup function.

Returns: Any

common_name

Data type: Any

Data types

Letsencrypt::Cron::Hour

mimic hour setting in cron as defined in man 5 crontab

Alias of

Variant[Integer[0,23], String[1], Array[
    Variant[
      Integer[0,23],
      String[1],
    ]
  ]]

Letsencrypt::Cron::Minute

mimic minute setting in cron as defined in man 5 crontab

Alias of

Variant[Integer[0,59], String[1], Array[
    Variant[
      Integer[0,59],
      String[1],
    ]
  ]]

Letsencrypt::Cron::Monthday

mimic monthday setting in cron as defined in man 5 crontab

Alias of

Variant[Integer[0,31], String[1], Array[
    Variant[
      Integer[0,31],
      String[1],
    ]
  ]]

Letsencrypt::Plugin

List of accepted plugins

Alias of Enum['apache', 'standalone', 'webroot', 'nginx', 'dns-azure', 'dns-route53', 'dns-google', 'dns-cloudflare', 'dns-linode', 'dns-rfc2136', 'manual', 'dns-ovh']