REFERENCE.md

Reference

Table of Contents

Classes

Public Classes

• acme: Install and configure acme.sh to manage SSL certificates

Private Classes

• acme::request::handler: Gather all data and use acme.sh to create accounts and sign certificates.
• acme::setup::common: Setup all necessary directories, users and groups.
• acme::setup::puppetmaster: Setup acme.sh and all necessary directories and packages.

Defined types

Public Defined types

• acme::certificate: Request a certificate.

Private Defined types

• acme::csr: Create a Certificate Signing Request (CSR) and send it to PuppetDB
• acme::deploy: Collects signed certificates for this host from PuppetDB.
• acme::deploy::crt: Install a signed certificate on the target host.
• acme::request: A request to sign a CSR or renew a certificate.
• acme::request::crt: Fetch the certificate from facter and export it via PuppetDB.
• acme::request::ocsp: Retrieve ocsp stapling information

Functions

• file_or_empty_string: Return the contents of a file. Multiple files can be passed, and the first file that exists will be read in.

Classes

acme

Install and configure acme.sh to manage SSL certificates

Parameters

The following parameters are available in the acme class:

• accounts
• acct_dir
• acme_dir
• acme_git_url
• acme_git_force
• acme_host
• acme_install_dir
• acme_revision
• acmecmd
• acmelog
• base_dir
• ca_whitelist
• certificates
• cfg_dir
• crt_dir
• csr_dir
• date_expression
• default_account
• default_ca
• default_profile
• dh_param_size
• dnssleep
• exec_timeout
• group
• key_dir
• log_dir
• manage_packages
• ocsp_must_staple
• ocsp_request
• path
• posthook_cmd
• profiles
• proxy
• renew_days
• results_dir
• shell
• stat_expression
• user

accounts

Data type: Array

An array of e-mail addresses that acme.sh may use during the ACME account registration. Should only be defined on $acme_host.

acct_dir

Data type: Stdlib::Absolutepath

The directory for acme.sh accounts.

acme_dir

Data type: Stdlib::Absolutepath

The working directory for acme.sh.

acme_git_url

Data type: String

URL to the acme.sh GIT repository. Defaults to the official GitHub project. Feel free to use a local mirror or fork.

acme_git_force

Data type: Boolean

Force repository creation, destroying any files on the path in the process. Useful when the repo URL has changed.

acme_host

Data type: String

The host you want to run acme.sh on. For now it needs to be a puppetmaster, as it needs direct access to the certificates using functions in Puppet.

acme_install_dir

Data type: Stdlib::Absolutepath

The installation directory for acme.sh.

acme_revision

Data type: String

The GIT revision of the acme.sh repository. Defaults to master which should contain a stable version of acme.sh.

acmecmd

Data type: String

The binary path to acme.sh.

acmelog

Data type: Stdlib::Absolutepath

The log file.

base_dir

Data type: Stdlib::Absolutepath

The configuration base directory for acme.sh.

ca_whitelist

Data type: Array

Specifies the CAs that may be used on $acme_host. The module will register any account specified in $accounts with all specified CAs. This ensure that these accounts are ready for use.

certificates

Data type: Hash

Array of full qualified domain names you want to request a certificate for. For SAN certificates you need to pass space seperated strings, for example ['foo.example.com fuzz.example.com', 'blub.example.com']

cfg_dir

Data type: Stdlib::Absolutepath

The directory for acme.sh configs.

crt_dir

Data type: Stdlib::Absolutepath

The directory for acme.sh certificates.

csr_dir

Data type: Stdlib::Absolutepath

The directory for acme.sh CSRs.

date_expression

Data type: String

The command used to calculate renewal dates for existing certificates.

default_account

Data type: Optional[String]

The default account that should be used to new certificate requests. The account must already be defined in $accounts. May be overriden by specifying $use_account for the certificate.

Default value: undef

default_ca

Data type: Enum['buypass', 'buypass_test', 'letsencrypt', 'letsencrypt_test', 'sslcom', 'zerossl']

The default ACME CA that should be used to new certificate requests. May be overriden by specifying $ca for the certificate. Previous versions of acme.sh used to have Let's Encrypt as their default CA, hence this is the default value for this Puppet module.

default_profile

Data type: Optional[String]

The default profile that should be used to new certificate requests. The profile must already be defined in $profile. May be overriden by specifying $use_profile for the certificate.

Default value: undef

dh_param_size

Data type: Integer

Specifies the DH parameter size, defaults to 2048.

dnssleep

Data type: Integer

The time in seconds acme.sh should wait for all DNS changes to take effect. Settings this to 0 disables the sleep mechanism and lets acme.sh poll DNS status automatically by using DNS over HTTPS.

exec_timeout

Data type: Integer

Specifies the time in seconds that any acme.sh operation can take before it is aborted by Puppet. This should usually be set to a higher value than $dnssleep.

group

Data type: String

The group for acme.sh.

key_dir

Data type: Stdlib::Absolutepath

The directory for acme.sh keys.

log_dir

Data type: Stdlib::Absolutepath

The log directory for acme.sh.

manage_packages

Data type: Boolean

Whether the module should install necessary packages, mainly git. Set to false to disable package management.

ocsp_must_staple

Data type: Boolean

Whether to request certificates with OCSP Must-Staple extension, defaults to true.

ocsp_request

Data type: Stdlib::Absolutepath

The script used by acme.sh to get OCSP data.

path

Data type: String

The content of the PATH env variable when running Exec resources.

posthook_cmd

Data type: String

Specifies a optional command to run after a certificate has been changed.

profiles

Data type: Optional[Hash]

A hash of profiles that contain information how acme.sh should sign certificates. A profile defines not only the challenge type, but also all required parameters and credentials used by acme.sh to sign the certificate. Should only be defined on $acme_host.

Default value: undef

proxy

Data type: Optional[String]

Proxy server to use to connect to the ACME CA, for example proxy.example.com:3128

Default value: undef

renew_days

Data type: Integer

Specifies the interval at which certs should be renewed automatically. Defaults to 60.

results_dir

Data type: Stdlib::Absolutepath

The output directory for acme.sh.

shell

Data type: String

The shell for the acme.sh user account.

stat_expression

Data type: String

The command used to get the modification time of a file.

user

Data type: String

The user for acme.sh.

Defined types

acme::certificate

Request a certificate.

Parameters

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

• acme_host
• ca
• dh_param_size
• domain
• ocsp_must_staple
• posthook_cmd
• renew_days
• use_account
• use_profile

acme_host

Data type: String

The host you want to run acme.sh on. Usually your Puppet Server. Defaults to $acme::acme_host.

Default value: $acme::acme_host

ca

Data type: Optional[Enum['buypass', 'buypass_test', 'letsencrypt', 'letsencrypt_test', 'sslcom', 'zerossl']]

The ACME CA that should be used. Used to overwrite the default CA that is configured on $acme_host.

Default value: $acme::default_ca

dh_param_size

Data type: Integer

dh parameter size, defaults to $acme::dh_param_size

Default value: $acme::dh_param_size

domain

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

Full qualified domain names you want to request a certificate for. For SAN certificates you need to pass space seperated strings, for example 'foo.example.com fuzz.example.com', or an array of names.

If no domain is specified, the resource name will be parsed as a list of domains, and the first domain will be used as certificate name.

Default value: undef

ocsp_must_staple

Data type: Boolean

request certificate with OCSP Must-Staple exctension, defaults to $acme::ocsp_must_staple

Default value: $acme::ocsp_must_staple

posthook_cmd

Data type: String

Specifies a optional command to run after a certificate has been changed.

Default value: $acme::posthook_cmd

renew_days

Data type: Integer

Specifies the interval at which certs should be renewed automatically. Defaults to 60.

Default value: $acme::renew_days

use_account

Data type: String

The ACME account that should be used (or registered). This account must exist in $accounts on your $acme_host.

Default value: $acme::default_account

use_profile

Data type: String

Specify the profile that should be used to sign the certificate. This profile must exist in $profiles on your $acme_host.

Default value: $acme::default_profile

Functions

file_or_empty_string

Type: Ruby 3.x API

Return the contents of a file. Multiple files can be passed, and the first file that exists will be read in.

file_or_empty_string()

Return the contents of a file. Multiple files can be passed, and the first file that exists will be read in.

Returns: Any