diff --git a/REFERENCE.md b/REFERENCE.md index 002c398..3da1d46 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,757 +1,852 @@ # Reference + ## Table of Contents -**Classes** +### Classes -_Public Classes_ +#### Public Classes * [`letsencrypt`](#letsencrypt): Install and configure Certbot, the LetsEncrypt client * [`letsencrypt::install`](#letsencryptinstall): Installs the Let's Encrypt client. * [`letsencrypt::plugin::dns_rfc2136`](#letsencryptplugindns_rfc2136): Installs and configures the dns-rfc2136 plugin * [`letsencrypt::plugin::dns_route53`](#letsencryptplugindns_route53): Installs and configures the dns-route53 plugin * [`letsencrypt::renew`](#letsencryptrenew): Configures renewal of Let's Encrypt certificates using Certbot -_Private Classes_ +#### Private Classes * `letsencrypt::config`: Configures the Let's Encrypt client. -**Defined types** +### Defined types * [`letsencrypt::certonly`](#letsencryptcertonly): Request a certificate using the `certonly` installer * [`letsencrypt::hook`](#letsencrypthook): Creates hook scripts. -**Functions** +### Functions -* [`letsencrypt::letsencrypt_lookup`](#letsencryptletsencrypt_lookup): +* [`letsencrypt::letsencrypt_lookup`](#letsencryptletsencrypt_lookup) -**Data types** +### Data types * [`Letsencrypt::Cron::Hour`](#letsencryptcronhour): mimic hour setting in cron as defined in man 5 crontab * [`Letsencrypt::Cron::Minute`](#letsencryptcronminute): mimic minute setting in cron as defined in man 5 crontab * [`Letsencrypt::Cron::Monthday`](#letsencryptcronmonthday): mimic monthday setting in cron as defined in man 5 crontab * [`Letsencrypt::Plugin`](#letsencryptplugin): List of accepted plugins ## Classes -### letsencrypt +### `letsencrypt` Install and configure Certbot, the LetsEncrypt client #### Examples ##### ```puppet class { 'letsencrypt' : email => 'letsregister@example.com', config => { 'server' => 'https://acme-staging-v02.api.letsencrypt.org/directory', }, } ``` #### Parameters -The following parameters are available in the `letsencrypt` class. - -##### `email` +The following parameters are available in the `letsencrypt` class: + +* [`email`](#email) +* [`environment`](#environment) +* [`package_name`](#package_name) +* [`package_ensure`](#package_ensure) +* [`package_command`](#package_command) +* [`config_file`](#config_file) +* [`config`](#config) +* [`cron_scripts_path`](#cron_scripts_path) +* [`cron_owner_group`](#cron_owner_group) +* [`manage_config`](#manage_config) +* [`manage_install`](#manage_install) +* [`configure_epel`](#configure_epel) +* [`agree_tos`](#agree_tos) +* [`unsafe_registration`](#unsafe_registration) +* [`config_dir`](#config_dir) +* [`key_size`](#key_size) +* [`renew_pre_hook_commands`](#renew_pre_hook_commands) +* [`renew_post_hook_commands`](#renew_post_hook_commands) +* [`renew_deploy_hook_commands`](#renew_deploy_hook_commands) +* [`renew_additional_args`](#renew_additional_args) +* [`renew_cron_ensure`](#renew_cron_ensure) +* [`renew_cron_hour`](#renew_cron_hour) +* [`renew_cron_minute`](#renew_cron_minute) +* [`renew_cron_monthday`](#renew_cron_monthday) + +##### `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` +Default value: ``undef`` -##### `environment` +##### `environment` Data type: `Array` An optional array of environment variables -Default value: [] +Default value: `[]` -##### `package_name` +##### `package_name` Data type: `String` Name of package and command to use when installing the client package. -Default value: 'certbot' +Default value: `'certbot'` -##### `package_ensure` +##### `package_ensure` Data type: `Any` The value passed to `ensure` when installing the client package. -Default value: 'installed' +Default value: `'installed'` -##### `package_command` +##### `package_command` Data type: `String` Path or name for letsencrypt executable. -Default value: 'certbot' +Default value: `'certbot'` -##### `config_file` +##### `config_file` Data type: `String` The path to the configuration file for the letsencrypt cli. -Default value: "${config_dir}/cli.ini" +Default value: `"${config_dir}/cli.ini"` -##### `config` +##### `config` Data type: `Hash` A hash representation of the letsencrypt configuration file. -Default value: { 'server' => 'https://acme-v02.api.letsencrypt.org/directory' } +Default value: `{ 'server' => 'https://acme-v02.api.letsencrypt.org/directory' }` -##### `cron_scripts_path` +##### `cron_scripts_path` Data type: `String` The path for renewal scripts called by cron -Default value: "${facts['puppet_vardir']}/letsencrypt" +Default value: `"${facts['puppet_vardir']}/letsencrypt"` -##### `cron_owner_group` +##### `cron_owner_group` Data type: `String` Group owner of cron renew scripts. -Default value: 'root' +Default value: `'root'` -##### `manage_config` +##### `manage_config` Data type: `Boolean` A feature flag to toggle the management of the letsencrypt configuration file. -Default value: `true` +Default value: ``true`` -##### `manage_install` +##### `manage_install` Data type: `Boolean` A feature flag to toggle the management of the letsencrypt client installation. -Default value: `true` +Default value: ``true`` -##### `configure_epel` +##### `configure_epel` Data type: `Boolean` A feature flag to include the 'epel' class and depend on it for package installation. -##### `agree_tos` +##### `agree_tos` Data type: `Boolean` A flag to agree to the Let's Encrypt Terms of Service. -Default value: `true` +Default value: ``true`` -##### `unsafe_registration` +##### `unsafe_registration` Data type: `Boolean` A flag to allow using the 'register-unsafely-without-email' flag. -Default value: `false` +Default value: ``false`` -##### `config_dir` +##### `config_dir` Data type: `Stdlib::Unixpath` The path to the configuration directory. -Default value: '/etc/letsencrypt' +Default value: `'/etc/letsencrypt'` -##### `key_size` +##### `key_size` Data type: `Integer[2048]` Size for the RSA public key -Default value: 4096 +Default value: `4096` -##### `renew_pre_hook_commands` +##### `renew_pre_hook_commands` Data type: `Any` Array of commands to run in a shell before obtaining/renewing any certificates. -Default value: [] +Default value: `[]` -##### `renew_post_hook_commands` +##### `renew_post_hook_commands` Data type: `Any` Array of commands to run in a shell after attempting to obtain/renew certificates. -Default value: [] +Default value: `[]` -##### `renew_deploy_hook_commands` +##### `renew_deploy_hook_commands` Data type: `Any` 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: [] +Default value: `[]` -##### `renew_additional_args` +##### `renew_additional_args` Data type: `Any` Array of additional command line arguments to pass to 'certbot renew'. -Default value: [] +Default value: `[]` -##### `renew_cron_ensure` +##### `renew_cron_ensure` Data type: `Any` Intended state of the cron resource running certbot renew. -Default value: 'absent' +Default value: `'absent'` -##### `renew_cron_hour` +##### `renew_cron_hour` Data type: `Any` 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) +Default value: `fqdn_rand(24)` -##### `renew_cron_minute` +##### `renew_cron_minute` Data type: `Any` 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, fqdn_rand_string(10)) +Default value: `fqdn_rand(60, fqdn_rand_string(10))` -##### `renew_cron_monthday` +##### `renew_cron_monthday` Data type: `Any` 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: '*' +Default value: `'*'` -### letsencrypt::install +### `letsencrypt::install` Installs the Let's Encrypt client. #### Parameters -The following parameters are available in the `letsencrypt::install` class. +The following parameters are available in the `letsencrypt::install` class: + +* [`configure_epel`](#configure_epel) +* [`package_ensure`](#package_ensure) +* [`package_name`](#package_name) -##### `configure_epel` +##### `configure_epel` Data type: `Boolean` A feature flag to include the 'epel' class and depend on it for package installation. -Default value: $letsencrypt::configure_epel +Default value: `$letsencrypt::configure_epel` -##### `package_ensure` +##### `package_ensure` Data type: `String` The value passed to `ensure` when installing the client package. -Default value: $letsencrypt::package_ensure +Default value: `$letsencrypt::package_ensure` -##### `package_name` +##### `package_name` Data type: `String` Name of package to use when installing the client package. -Default value: $letsencrypt::package_name +Default value: `$letsencrypt::package_name` -### letsencrypt::plugin::dns_rfc2136 +### `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. +The following parameters are available in the `letsencrypt::plugin::dns_rfc2136` class: -##### `server` +* [`server`](#server) +* [`key_name`](#key_name) +* [`key_secret`](#key_secret) +* [`key_algorithm`](#key_algorithm) +* [`port`](#port) +* [`propagation_seconds`](#propagation_seconds) +* [`manage_package`](#manage_package) +* [`package_name`](#package_name) +* [`config_dir`](#config_dir) + +##### `server` Data type: `Stdlib::Host` Target DNS server. -##### `key_name` +##### `key_name` Data type: `String[1]` TSIG key name. -##### `key_secret` +##### `key_secret` Data type: `String[1]` TSIG key secret. -##### `key_algorithm` +##### `key_algorithm` Data type: `String[1]` TSIG key algorithm. -Default value: 'HMAC-SHA512' +Default value: `'HMAC-SHA512'` -##### `port` +##### `port` Data type: `Stdlib::Port` Target DNS port. -Default value: 53 +Default value: `53` -##### `propagation_seconds` +##### `propagation_seconds` Data type: `Integer` Number of seconds to wait for the DNS server to propagate the DNS-01 challenge. -Default value: 10 +Default value: `10` -##### `manage_package` +##### `manage_package` Data type: `Boolean` Manage the plugin package. -Default value: `true` +Default value: ``true`` -##### `package_name` +##### `package_name` Data type: `String[1]` The name of the package to install when $manage_package is true. -##### `config_dir` +##### `config_dir` Data type: `Stdlib::Absolutepath` The path to the configuration directory. -Default value: $letsencrypt::config_dir +Default value: `$letsencrypt::config_dir` -### letsencrypt::plugin::dns_route53 +### `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. +The following parameters are available in the `letsencrypt::plugin::dns_route53` class: + +* [`propagation_seconds`](#propagation_seconds) +* [`manage_package`](#manage_package) +* [`package_name`](#package_name) -##### `propagation_seconds` +##### `propagation_seconds` Data type: `Integer` Number of seconds to wait for the DNS server to propagate the DNS-01 challenge. -Default value: 10 +Default value: `10` -##### `manage_package` +##### `manage_package` Data type: `Boolean` Manage the plugin package. -Default value: `true` +Default value: ``true`` -##### `package_name` +##### `package_name` Data type: `String[1]` The name of the package to install when $manage_package is true. -### letsencrypt::renew +### `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. +The following parameters are available in the `letsencrypt::renew` class: -##### `pre_hook_commands` +* [`pre_hook_commands`](#pre_hook_commands) +* [`post_hook_commands`](#post_hook_commands) +* [`deploy_hook_commands`](#deploy_hook_commands) +* [`additional_args`](#additional_args) +* [`cron_ensure`](#cron_ensure) +* [`cron_hour`](#cron_hour) +* [`cron_minute`](#cron_minute) +* [`cron_monthday`](#cron_monthday) + +##### `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 +Default value: `$letsencrypt::renew_pre_hook_commands` -##### `post_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 +Default value: `$letsencrypt::renew_post_hook_commands` -##### `deploy_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 +Default value: `$letsencrypt::renew_deploy_hook_commands` -##### `additional_args` +##### `additional_args` Data type: `Array[String[1]]` Array of additional command line arguments to pass to 'certbot renew'. -Default value: $letsencrypt::renew_additional_args +Default value: `$letsencrypt::renew_additional_args` -##### `cron_ensure` +##### `cron_ensure` Data type: `Enum['present', 'absent']` Intended state of the cron resource running certbot renew -Default value: $letsencrypt::renew_cron_ensure +Default value: `$letsencrypt::renew_cron_ensure` -##### `cron_hour` +##### `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 +Default value: `$letsencrypt::renew_cron_hour` -##### `cron_minute` +##### `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 +Default value: `$letsencrypt::renew_cron_minute` -##### `cron_monthday` +##### `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 +Default value: `$letsencrypt::renew_cron_monthday` ## Defined types -### letsencrypt::certonly +### `letsencrypt::certonly` This type can be used to request a certificate using the `certonly` installer. #### Parameters -The following parameters are available in the `letsencrypt::certonly` defined type. - -##### `ensure` +The following parameters are available in the `letsencrypt::certonly` defined type: + +* [`ensure`](#ensure) +* [`domains`](#domains) +* [`custom_plugin`](#custom_plugin) +* [`plugin`](#plugin) +* [`webroot_paths`](#webroot_paths) +* [`letsencrypt_command`](#letsencrypt_command) +* [`additional_args`](#additional_args) +* [`environment`](#environment) +* [`key_size`](#key_size) +* [`manage_cron`](#manage_cron) +* [`suppress_cron_output`](#suppress_cron_output) +* [`cron_before_command`](#cron_before_command) +* [`cron_success_command`](#cron_success_command) +* [`cron_hour`](#cron_hour) +* [`cron_minute`](#cron_minute) +* [`cron_monthday`](#cron_monthday) +* [`config_dir`](#config_dir) +* [`pre_hook_commands`](#pre_hook_commands) +* [`post_hook_commands`](#post_hook_commands) +* [`deploy_hook_commands`](#deploy_hook_commands) +* [`cert_name`](#cert_name) + +##### `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' +Default value: `'present'` -##### `domains` +##### `domains` Data type: `Array[String[1]]` An array of domains to include in the CSR. -Default value: [$title] +Default value: `[$title]` -##### `custom_plugin` +##### `custom_plugin` Data type: `Boolean` Whether to use a custom plugin in additional_args and disable -a flag. -Default value: `false` +Default value: ``false`` -##### `plugin` +##### `plugin` Data type: `Letsencrypt::Plugin` The authenticator plugin to use when requesting the certificate. -Default value: 'standalone' +Default value: `'standalone'` -##### `webroot_paths` +##### `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: [] +Default value: `[]` -##### `letsencrypt_command` +##### `letsencrypt_command` Data type: `String[1]` Command to run letsencrypt -Default value: $letsencrypt::command +Default value: `$letsencrypt::command` -##### `additional_args` +##### `additional_args` Data type: `Array[String[1]]` An array of additional command line arguments to pass to the `letsencrypt` command. -Default value: [] +Default value: `[]` -##### `environment` +##### `environment` Data type: `Array[String[1]]` An optional array of environment variables -Default value: [] +Default value: `[]` -##### `key_size` +##### `key_size` Data type: `Integer[2048]` Size for the RSA public key -Default value: $letsencrypt::key_size +Default value: `$letsencrypt::key_size` -##### `manage_cron` +##### `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` +Default value: ``false`` -##### `suppress_cron_output` +##### `suppress_cron_output` Data type: `Boolean` Redirect cron output to devnull -Default value: `false` +Default value: ``false`` -##### `cron_before_command` +##### `cron_before_command` Data type: `Optional[String[1]]` Representation of a command that should be run before renewal command -Default value: `undef` +Default value: ``undef`` -##### `cron_success_command` +##### `cron_success_command` Data type: `Optional[String[1]]` Representation of a command that should be run if the renewal command succeeds. -Default value: `undef` +Default value: ``undef`` -##### `cron_hour` +##### `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. -Default value: fqdn_rand(24, $title) +Default value: `fqdn_rand(24, $title)` -##### `cron_minute` +##### `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, fqdn_rand_string(10, $title)) +Default value: `fqdn_rand(60, fqdn_rand_string(10, $title))` -##### `cron_monthday` +##### `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: ['*'] +Default value: `['*']` -##### `config_dir` +##### `config_dir` Data type: `Stdlib::Unixpath` The path to the configuration directory. -Default value: $letsencrypt::config_dir +Default value: `$letsencrypt::config_dir` -##### `pre_hook_commands` +##### `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: [] +Default value: `[]` -##### `post_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: [] +Default value: `[]` -##### `deploy_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: [] +Default value: `[]` -##### `cert_name` +##### `cert_name` Data type: `String[1]` -Default value: $title +Default value: `$title` -### letsencrypt::hook +### `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. +The following parameters are available in the `letsencrypt::hook` defined type: + +* [`type`](#type) +* [`hook_file`](#hook_file) +* [`commands`](#commands) -##### `type` +##### `type` Data type: `Enum['pre', 'post', 'deploy']` Hook type. -##### `hook_file` +##### `hook_file` Data type: `String[1]` Path to deploy hook script. -##### `commands` +##### `commands` Data type: `Variant[String[1],Array[String[1]]]` Bash commands to execute when the hook is run by certbot. ## Functions -### letsencrypt::letsencrypt_lookup +### `letsencrypt::letsencrypt_lookup` Type: Ruby 4.x API The letsencrypt::letsencrypt_lookup function. #### `letsencrypt::letsencrypt_lookup(Any $cn)` The letsencrypt::letsencrypt_lookup function. Returns: `Any` ##### `cn` Data type: `Any` ## Data types -### Letsencrypt::Cron::Hour +### `Letsencrypt::Cron::Hour` mimic hour setting in cron as defined in man 5 crontab -Alias of `Variant[Integer[0,23], String[1], Array[ +Alias of + +```puppet +Variant[Integer[0,23], String[1], Array[ Variant[ Integer[0,23], String[1], ] - ]]` + ]] +``` -### Letsencrypt::Cron::Minute +### `Letsencrypt::Cron::Minute` mimic minute setting in cron as defined in man 5 crontab -Alias of `Variant[Integer[0,59], String[1], Array[ +Alias of + +```puppet +Variant[Integer[0,59], String[1], Array[ Variant[ Integer[0,59], String[1], ] - ]]` + ]] +``` -### Letsencrypt::Cron::Monthday +### `Letsencrypt::Cron::Monthday` mimic monthday setting in cron as defined in man 5 crontab -Alias of `Variant[Integer[0,31], String[1], Array[ +Alias of + +```puppet +Variant[Integer[0,31], String[1], Array[ Variant[ Integer[0,31], String[1], ] - ]]` + ]] +``` -### Letsencrypt::Plugin +### `Letsencrypt::Plugin` List of accepted plugins -Alias of `Enum['apache', 'standalone', 'webroot', 'nginx', 'dns-route53', 'dns-google', 'dns-cloudflare', 'dns-rfc2136']` +Alias of + +```puppet +Enum['apache', 'standalone', 'webroot', 'nginx', 'dns-route53', 'dns-google', 'dns-cloudflare', 'dns-rfc2136'] +```