Skip to content

Latest commit

 

History

History
1001 lines (589 loc) · 30.1 KB

REFERENCE.md

File metadata and controls

1001 lines (589 loc) · 30.1 KB
Raw

Reference

Table of Contents

Classes

Public Classes

  • dehydrated: Base class to define necessary variables and include setup classes.
  • dehydrated::params: A short summary of the purpose of this class

Private Classes

  • dehydrated::setup: Setup required files and folders. Don't include/call this class.
  • dehydrated::setup::dehydrated_host: setup dehydrated and users/groups for it

Defined types

Public Defined types

Private Defined types

  • dehydrated::certificate::collect: A short summary of the purpose of this defined type.
  • dehydrated::certificate::csr: Creates a key file with CSR
  • dehydrated::certificate::deploy: Deploy collected certificate and CA files.
  • dehydrated::certificate::dh: Create the DH params file.
  • dehydrated::certificate::request: Prepare everything to request a certifificate for our CSRs.
  • dehydrated::certificate::transfer: Transfer crt/ca/ocsp files.

Resource types

Functions

Data types

Classes

dehydrated

Base class to setup the letsencrypt certificate handling with dehydrated.

Examples

# should be sufficient in most cases.
include dehydrated

# if you are "upgrading" from bzed-letsencrypt,
# you might want to use these options to stay
# compatible with the old group/directory:
class { 'dehydrated' :
  group    => 'letsencrypt',
  base_dir => '/etc/letsencrypt',
}

Parameters

The following parameters are available in the dehydrated class:

base_dir

Data type: Stdlib::Absolutepath

The base directory where keys/csr/certs are stored. Defaults to:

  • on $::os['family']=='Debian': /etc/dehydrated
  • on other Linux/Unix systems: /etc/pki/dehydrated
  • on windows: C:\LE_certs.

Default value: $dehydrated::params::base_dir

crt_dir

Data type: Stdlib::Absolutepath

The directory where certificates are stored. Defaults to ${base_dir}/certs

Default value: join([$base_dir, 'certs'], $dehydrated::params::path_seperator)

csr_dir

Data type: Stdlib::Absolutepath

The directory where CSRs are stored. Defaults to ${base_dir}/csr

Default value: join([$base_dir, 'csr'], $dehydrated::params::path_seperator)

key_dir

Data type: Stdlib::Absolutepath

The directory where pricate keys are stored. Defaults to ${base_dir}/private

Default value: join([$base_dir, 'private'], $dehydrated::params::path_seperator)

user

Data type: String

Linux: The user who owns the files in /etc/dehydrated. Windows: The user who owns the files in C:\LE_Certs. Needs to be specified!

Default value: $dehydrated::params::user

group

Data type: String

Linux: The group which owns the files in /etc/dehydrated. If you have a non-root process which needs to access private keys, add its user to this group. Windows: The group which owns the files in C:\LE_Certs. Needs to be specified!

Default value: $dehydrated::params::group

dehydrated_user

Data type: Optional[String]

User to run the dehydrated script as. Only used on the host that actually requests certificates.

Default value: $dehydrated::params::dehydrated_user

dehydrated_group

Data type: Optional[String]

Group to run the dehydrated script as. Only used on the host that actually requests certificates.

Default value: $dehydrated::params::dehydrated_group

letsencrypt_ca

Data type: String

Let’s Encrypt CA to use. Defaults to v2-production. See the letsencrypt_cas parameter for a way to specify your own Let’s Encrypt / ACME compatible CA. This configures the default CA to use, but You can actually define different CAs for each certificate, see the dehydrated::certificate define for details.

Default value: $dehydrated::params::letsencrypt_ca

letsencrypt_cas

Data type: Hash

Hash with the definitions of the official testing and production Let’s Encrypt CAs this puppet module was tested against.

Default value: $dehydrated::params::letsencrypt_cas

dh_param_size

Data type: Integer[768]

Default size of the DH params we should generate. Defaults to 2048.

Default value: $dehydrated::params::dh_param_size

challengetype

Data type: Dehydrated::Challengetype

Default challengetype to use. Defaults to 'dns-01'. You can specify a different challengetype for each certificate, see dehydrated::certificate.

Default value: $dehydrated::params::challengetype

algorithm

Data type: Dehydrated::Algorithm

Default algorithm / elliptic-curve you want to use. Supported: rsa, secp384r1, prime256v1. Defaults to rsa. You can specify a different algorithm for each certificate, see dehydrated::certificate.

Default value: $dehydrated::params::algorithm

dehydrated_base_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host. Path where the dehydrated script and configurations/csrs are being stored. Defaults to '/opt/dehydrated'.

Default value: $dehydrated::params::dehydrated_base_dir

dehydrated_git_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host. Path where the dehydrated script is being checkout out into using git. Defaults to ${dehydrated_base_dir}/dehydrated.

Default value: "${dehydrated_base_dir}/dehydrated"

dehydrated_git_tag

Data type: String

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host. Version of the dehydrated script we want to use. Change it on your own risk.

Default value: $dehydrated::params::dehydrated_git_tag

dehydrated_git_url

Data type: Dehydrated::GitUrl

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host. Git url to clone dehydrated from. If you have an internal mirror/version, you can override the default github url here.

Default value: $dehydrated::params::dehydrated_git_url

dehydrated_host

Data type: Stdlib::Fqdn

Default setting for the host you want to request the certificates on. Required on that host, on all others it is used as default for certificates requested via dehydrated::certificate. You can specify a different dehydrated_host on each certificate if you want to. If $facts['fqdn'] == $dehydrated::dehydrated_host, dehydrated will be installed and the certificate request cronjob will be setup.

Default value: $dehydrated::params::dehydrated_host

dehydrated_requests_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host. Path where requests that need to be handled are being stored.

Default value: "${dehydrated_base_dir}/requests"

dehydrated_hooks_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: "${dehydrated_base_dir}/hooks"

dehydrated_requests_config

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: "${dehydrated_base_dir}/requests.json"

dehydrated_wellknown_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: "${dehydrated_base_dir}/acme-challenges"

dehydrated_alpncert_dir

Data type: Stdlib::Absolutepath

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: "${dehydrated_base_dir}/alpn-certs"

dehydrated_host_packages

Data type: Array

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: $dehydrated::params::dehydrated_host_packages

dehydrated_environment

Data type: Hash

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: $dehydrated::params::dehydrated_environment

dehydrated_domain_validation_hook

Data type: Optional[Dehydrated::Hook]

Only used if $facts['fqdn'] == $dehydrated::dehydrated_host.

Default value: $dehydrated::params::dehydrated_domain_validation_hook

dehydrated_hook

Data type: Optional[Dehydrated::Hook]

Name of the hook script dehydrated will use to validate the authorization request. The hook script must live in the $dehydrated_hooks_dir on $dehydrated::dehydrated_host.

Default value: "${challengetype}.sh"

dehydrated_contact_email

Data type: Optional[Dehydrated::Email]

Contact email address for created accounts. We'll create one account for each puppet host.

Default value: $dehydrated::params::dehydrated_contact_email

accounts_per_agent

Data type: Boolean

Create one ACME account per puppet client (true; the default), or one account globally.

Default value: true

dehydrated_status_file

Data type: Stdlib::Absolutepath

File the dehydrated job runner will dump its status into. Pretty printed JSON.

Default value: "${dehydrated_base_dir}/status.json"

dehydrated_monitoring_status_file

Data type: Stdlib::Absolutepath

Status file for monitoring with check_statusfile, see README.md for details.

Default value: "${dehydrated_base_dir}/monitoring.status"

manage_user

Data type: Boolean

Create $dehydrated_user/$dehydrated_group and $user/$group if necessary.

Default value: $dehydrated::params::manage_user

manage_packages

Data type: Boolean

Install required packages using ensure_packages? Should be safe to leave enabled in most cases.

Default value: $dehydrated::params::manage_packages

pki_packages

Data type: Array

Required packages to create /etc/pki. Not really used yet.

Default value: $dehydrated::params::pki_packages

packages

Data type: Array

The list of packages we actually need to install to make this module work properly. You are free to modify this list if you need to.

Default value: $dehydrated::params::packages

certificates

Data type: Array[Variant[Dehydrated::DN, Tuple[Dehydrated::DN, Array[Dehydrated::DN]]]]

Allows to request certificates instead of using dehydrated::certificate. The puppet definition of this rather complex parameter is Array[Variant[Dehydrated::DN, Tuple[Dehydrated::DN, Array[Dehydrated::DN]]]] So basically, you need to specify an Array. Contents are either a

  • distinguished name
  • tuple with [distinguished name, array of distinguished names] The first case requests a default certificate. The tuple version will request a SAN certificate.

Default value: []

build_pfx_files

Data type: Boolean

Create PKCS12 container with key, certificate and ca certificates. Defaults to true on windows, to false on all other OS.

Default value: $dehydrated::params::build_pfx_files

preferred_chain

Data type: Optional[String]

Default value: $dehydrated::params::preferred_chain

dehydrated::params

A description of what this class does

Examples

include dehydrated::params

Defined types

dehydrated::certificate

Triggers key and csr generation and requests the certificate via the host configured in $dehydrated_host. This is the main defined type to use if you want to have a certificate. Together with the defaults in the dehydrated class you should have everything to make requesting certificates possible. Especially the dehydrated::certificate::* types do not have a public API and can change without warning. Don't rely on them. Dehydrated::Certificate[$dn] is also what you want to use to subscribe to if you want to restart services after certificates have been installed/updated.

Examples

dehydrated::certificate { 'test.example.com': }

Parameters

The following parameters are available in the dehydrated::certificate defined type:

dn

Data type: Dehydrated::DN

The main distinguished name to use for the certificate. Defaults to $name.

Default value: $name

base_filename

Data type: String

The base part of the filename of all related files. For wildcard certificates the * is replaced by wildcard. Feel free to use whatever a valid filename is.

Default value: regsubst($dn, '^\*', '_wildcard_')

subject_alternative_names

Data type: Array[Dehydrated::DN]

To request a SAN certificate, pass an array with the alternative names here. The main $dn will be added automatically.

Default value: []

challengetype

Data type: Dehydrated::Challengetype

Default challengetype to use. Defaults to $dehydrated::challengetype, which defaults to 'dns-01'. You can specify a different challengetype for each certificate here.

Default value: $dehydrated::challengetype

algorithm

Data type: Dehydrated::Algorithm

Algorithm / elliptic-curve you want to use. Supported: rsa, secp384r1, prime256v1. Defaults to $dehydrated::algorithm, which defaults to 'rsa'. You can specify a different algorithm for each certificate here.

Default value: $dehydrated::algorithm

dh_param_size

Data type: Integer[768]

Size of the DH params we should generate. Defaults to $dehydrated::dh_param_size, which defaults to 2048. You can specify a different DH param size for each certificate here.

Default value: $dehydrated::dh_param_size

dehydrated_host

Data type: Stdlib::Fqdn

$::fqdn of the host which is responsible to request the certificates from the Let's Encrypt CA. Defaults to $dehydrated::dehydrated_host where you can configure your default.

Default value: $dehydrated::dehydrated_host

dehydrated_environment

Data type: Hash

Hash with the environment variables to set for the $dehydrated_domain_validation_hook and also for running the hook in dehydrated. Defaults to $dehydrated::dehydrated_environment, empty by default.

Default value: $dehydrated::dehydrated_environment

dehydrated_hook

Data type: Optional[Dehydrated::Hook]

Name of the hook script you want to use. Can be left on undef if http-01 is being used as challengetype to use the built-in http-01 implementation of dehydrated. Defaults to $dehydrated::dehydrated_hook, which will use "${challengetype}.sh" if the challengetype is not http-01.

Default value: $dehydrated::dehydrated_hook

letsencrypt_ca

Data type: String

Defines the CA you want to use to request certificates. If you want to use a non-supported CA, you need to configure it in $dehydrated::letsencrypt_cas on your $dehydrated_host. Normally, the following CAs are pre-configured: staging, production, v2-staging, v2-production Defaults to $dehydrated::letsencrypt_ca, which points to v2-production.

Default value: $dehydrated::letsencrypt_ca

dehydrated_domain_validation_hook

Data type: Optional[Dehydrated::Hook]

Name of the hook script to run before dehydrated is actually executed. Used to check if a domain is still valid or if you are allowed to modify it. Or whatever else you want to do as preparation. Good thing to use before running into limits by trying to request certificates for domains you don't own. Defaults to $dehydrated::dehydrated_domain_validation_hook where you can configure the default for your setup.

Default value: $dehydrated::dehydrated_domain_validation_hook

key_password

Data type: Optional[String]

If your key should be protected by a password, specify it here.

Default value: undef

preferred_chain

Data type: Optional[String]

Default value: $dehydrated::preferred_chain

Resource types

dehydrated_csr

CSRs for dehydrated

Properties

The following properties are available in the dehydrated_csr type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the dehydrated_csr type.

algorithm

Valid values: prime256v1, secp384r1, rsa

The algorithm to use, supported: rsa, secp384r1, prime256v1

Default value: rsa

common_name

The common name for the csr

country

country part of the certificate name

digest

Digest used while signing the CSR, defaults to SHA512

Default value: SHA512

email_address

emailAddress part of the certificate name

force

Valid values: true, false

Whether to replace the certificate if the private key or CommonName/SANs mismatches

Default value: false

locality

locality part of the certificate name

organization

locality part of the certificate name

organizational_unit

organizational_unit part of the certificate name

password

The optional password for the private key

path
private_key
provider

The specific backend to use for this dehydrated_csr resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

state

state part of the certificate name

subject_alternative_names

SANs to request

Default value: []

dehydrated_dhparam

DH params for dehydrated

Properties

The following properties are available in the dehydrated_dhparam type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the dehydrated_dhparam type.

path
provider

The specific backend to use for this dehydrated_dhparam resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

size

The key size

Default value: 2048

dehydrated_key

Create a private key for dehydrated.

Properties

The following properties are available in the dehydrated_key type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the dehydrated_key type.

algorithm

Valid values: prime256v1, secp384r1, rsa

Algorithm to use for Key generation, supported: prime256v1, secp384r1, rsa

Default value: rsa

password

The optional password for the key

path

Key location, must be absolute.

provider

The specific backend to use for this dehydrated_key resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

size

The key size, used for RSA only.

Default value: 2048

dehydrated_pfx

pkcs12 / pfx files for dehydrated

Properties

The following properties are available in the dehydrated_pfx type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the dehydrated_pfx type.

ca

The path of the ca certificates to put into the pkcs12 container

certificate

The path of the certificate to put into the pkcs12 container

key_password

The optional password for the private key

password

The optional password for the pkcs12 container

path
pkcs12_name

A string describing the key / pkcs12 container

private_key
provider

The specific backend to use for this dehydrated_pfx resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

Functions

dehydrated::file

Type: Ruby 4.x API

The dehydrated::file function.

dehydrated::file(String $files, Optional[String] *$more_files)

The dehydrated::file function.

Returns: Any

files

Data type: String

*more_files

Data type: Optional[String]

Data types

Dehydrated::Algorithm

The Dehydrated::Algorithm data type.

Alias of Pattern[/^(rsa|prime256v1|secp384r1)$/]

Dehydrated::CRT

The Dehydrated::CRT data type.

Alias of Pattern[/(?m:.*-+BEGIN CERTIFICATE-+.*-+END CERTIFICATE-+.*)/]

Dehydrated::CSR

The Dehydrated::CSR data type.

Alias of Pattern[/(?m:.*-+BEGIN CERTIFICATE REQUEST-+.*-+END CERTIFICATE REQUEST-+.*)/]

Dehydrated::Challengetype

The Dehydrated::Challengetype data type.

Alias of Pattern[/^(http-01|dns-01|tls-alpn-01)$/]

Dehydrated::DN

what we can request certificates for.

Alias of Variant[Stdlib::Fqdn, Dehydrated::WildcardDN]

Dehydrated::Email

The Dehydrated::Email data type.

Alias of Pattern[/^(?i:[A-Z0-9_%+"-]+[A-Z0-9._%+"-]+@[A-Z0-9.-]+\.[A-Z]{2,})$/]

Dehydrated::GitSSHUrl

The Dehydrated::GitSSHUrl data type.

Alias of Pattern[/(?i:^(ssh:\/\/([^\/@]+@)?[^\/]+\/.*|([^@:]+@)?[^:]+:.*))/]

Dehydrated::GitUrl

a type that hopefully matches all possible git urls.

Alias of Variant[Dehydrated::GitSSHUrl, Stdlib::HTTPUrl, Stdlib::Absolutepath]

Dehydrated::Hook

The Dehydrated::Hook data type.

Alias of Pattern[/^[^\\\/]+$/]

Dehydrated::WildcardDN

based on Stdlib::Fqdn lint:ignore:140chars

Alias of Pattern[/^\*\.(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$/]