Version information
This version is compatible with:
- Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x
- Puppet >= 5.0.0 < 8.0.0
- ,
Tasks:
- renew
Plans:
- renew
Start using this module
Add this module to your Puppetfile:
mod 'opuscodium-dehydrated', '2.4.1'
Learn more about managing modules with a PuppetfileDocumentation
dehydrated
Table of Contents
Module Description
The dehydrated module lets you use Puppet to manage Let's Encrypt certificates creation and renewal using dehydrated.
Setup
Beginning with dehydrated
Let's encrypt needs a contact address that must be passed to the dehydrated
class:
class { 'dehydrated':
contact_email => 'user@example.com',
}
This is enough to get started and creating certificates.
Usage
Generate a simple certificate
After including the required dehydrated
class, each dehydrated::certificate
will produce a single certificate file:
class { 'dehydrated':
contact_email => 'user@example.com',
}
dehydrated::certificate { 'example.com':
}
Generate a certificate with SAN
A dehydrated::certificate
can use the domains
parameter to indicate Subject Alternative Names (SAN).
class { 'dehydrated':
contact_email => 'user@example.com',
}
dehydrated::certificate { 'example.com':
domains => [
'www.example.com',
'example.net',
'www.example.net'
],
}
Use DNS-01 hook
Examples of dns-01 hook.sh
:
Hook must wait until DNS records are really synced across public DNS servers and only then finish. Otherwise Let's Encrypt won't find the records from their side and dehydrated run will fail.
class { 'dehydrated':
contact_email => 'user@example.com',
challengetype => 'dns-01',
hook => '/home/dehydrated/hook.sh',
timeout => 600,
}
dehydrated::certificate { 'example.com':
}
Renewing certificates with cron
The cron_integration
parameter of the dehydrated
class configures cron to renew certificates before they expire.
class { 'dehydrated':
contact_email => 'user@example.com',
cron_integration => true,
}
Please note that the web server is not automatically restarted when certificates are renewed.
Serving challenges with Apache
The apache_integration
parameter of the dehydrated
class configures apache to serve the challenges used for domain validation.
The following example redirect all HTTP requests to HTTPS except those related to letsencrypt's validation:
include ::apache
include ::apache::mod::rewrite
class { 'dehydrated':
contact_email => 'user@example.com',
apache_integration => true,
}
apache::vhost { 'main':
port => 80,
default_vhost => true,
docroot => '/var/empty',
manage_docroot => false,
directories => [
{
path => '/var/empty',
rewrites => [
{
rewrite_rule => '.* https://%{HTTP_HOST}%{REQUEST_URI} [R=301]',
},
],
},
],
}
Reference
Classes
Public Classes
Class: dehydrated
Main class used to setup the system.
Required parameters
contact_email
: The e-mail address Let's Encrypt can use to reach you regarding your certificates.
Optional parameters
-
apache_integration
: Specifies whether to setup apache to serve the generated challenges. Default: 'false'. -
cron_integration
: Specifies whether to setup cron to automatically renew certificates. Default: 'false'. -
user
: Specifies the user account used to manage certificates. Default: 'dehydrated'. -
ipversion
: Resolve names to addresses of IP version only. -
ca
: Path to certificate authority. -
ca_terms
: Path to certificate authority license terms redirect. -
license
: Path to license agreement. -
challengetype
: Which challenge should be used? -
keysize
: Default keysize for private keys. -
openssl_cnf
: Path to openssl config file. -
hook
: Program or function called in certain situations. -
hook_chain
: Chain clean_challenge|deploy_challenge arguments together into one hook call per certificate. -
renew_days
: Minimum days before expiration to automatically renew certificate. -
private_key_renew
: Regenerate private keys instead of just signing new certificates on renewal. -
private_key_rollover
: Create an extra private key for rollover. -
key_algo
: Which public key algorithm should be used? -
ocsp_must_staple
: Option to add CSR-flag indicating OCSP stapling to be mandatory. -
timeout
: Execution timeout for dehydrated tool. Default: '300'.
Defined Types
Defined Type: dehydrated::certificate
Class used to describe the certificates that should be maintained.
Parameters (all optional)
domains
: Specifies the list of domains to include as SAN (Subject Alternative Names).
Functions
Function: dehydrated::ssl_cert_file
Function used to provide the ssl_cert_file
path.
Required parameters
hostname
: Hostname
Function: dehydrated::ssl_privkey_file
Function used to provide the ssl_privkey_file
path.
Required parameters
hostname
: Hostname
Function: dehydrated::ssl_chain_file
Function used to provide the ssl_chain_file
path.
Required parameters
hostname
: Hostname
Function: dehydrated::ssl_fullchain_file
Function used to provide the ssl_fullchain_file
path.
Required parameters
hostname
: Hostname
Function: dehydrated::apache::vhost_attributes
Function used to provide the SSL attributes for apache::vhost
defined type.
It returns a hash with ssl_cert
, ssl_key
and ssl_chain
keys.
This function is designed to be used as hash attributes using splat operator, ie.:
apache::vhost { $hostname:
port => 443,
ssl => true,
[...]
* => dehydrated::apache::vhost_attributes($hostname)
}
Required parameters
hostname
: Hostname
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
renew
Renew certificates about to expire
What are plans?
Modules can contain plans that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
2.4.1 (2020-12-25)
Fixed bugs:
2.4.0 (2020-12-21)
Implemented enhancements:
- Default to dehydrated 0.7.0 when installing from repos #26 (smortex)
- Move common default values to init.pp #25 (smortex)
2.3.0 (2020-09-04)
Implemented enhancements:
- Implement helper functions to retrieve ssl paths #21 (neomilium)
- Make internal classes private #20 (smortex)
- Add task and plan to renew certificates #16 (smortex)
- Keep going on certificate creation/renewal failure #14 (smortex)
- Add documentation for classes and defined types #13 (smortex)
2.2.0 (2019-05-07)
2.1.0 (2018-12-05)
Implemented enhancements:
- Add support for exec timeout option #9 (sergiik)
- Default to dehydrated 0.5.0 when installing from repos #5 (smortex)
Fixed bugs:
2.0.0 (2017-12-22)
Implemented enhancements:
1.1.0 (2017-06-01)
Implemented enhancements:
1.0.1 (2017-01-08)
1.0.0 (2016-10-20)
* This Changelog was automatically generated by github_changelog_generator
Dependencies
- puppetlabs/concat (>= 2.1.0 < 5.0.0)
- puppetlabs/stdlib (>= 4.13.1 < 5.0.0)