dehydrated

Table of Contents

• Module Description
• Setup
  • Beginning with dehydrated
• Usage
  • Generate a simple certificate
  • Generate a certificate with SAN
  • Use DNS-01 hook
  • Renewing certificates with cron
  • Serving challenges with Apache
• Reference
  • Classes
    • Public Classes
    • Class: dehydrated
      • Required parameters
      • Optional parameters
  • Defined Types
    • Defined Type: dehydrated::certificate
      • Parameters (all optional)
  • Functions
    • Function: dehydrated::ssl_cert_file
      • Required parameters
    • Function: dehydrated::ssl_privkey_file
      • Required parameters
    • Function: dehydrated::ssl_chain_file
      • Required parameters
    • Function: dehydrated::ssl_fullchain_file
      • Required parameters
    • Function: dehydrated::apache::vhost_attributes
      • Required parameters

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:

• nsupdate
• more

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

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.3.0]

Added

• Add documention for classes and defined types
• Add task and plan to renew certificates
• Make internal classes private
• Implement helper functions to retrieve ssl paths (ie. dehydrated::ssl_*_file)
• Add a dehydrated::apache::vhost_attributes function to ease apache::vhost usage with dehydrated

Changed

• Keep going on certificate failure.

2.2.0

Added

• Support for RedHat based operating systems.

2.1.0

Added

• Added missing dependency on apache::mod::alias,
• Allow end-user to customize dehydrated source when using a repo ($dehydrated::repo_source),
• Allow end-user to customize dehydrated version when using a repo ($dehydrated::repo_revision),
• Allow end-user to customize execution timeout ($dehydrated::timeout).

Changed

• Default to the latests dehydrated release (v0.5.0) when using a repo.

2.0.0

Added

• $dehydrated::ipversion parameter,
• $dehydrated::ca parameter,
• $dehydrated::ca_terms parameter,
• $dehydrated::license parameter,
• $dehydrated::challengetype parameter,
• $dehydrated::keysize parameter,
• $dehydrated::openssl_cnf parameter,
• $dehydrated::hook parameter,
• $dehydrated::hook_chain parameter,
• $dehydrated::renew_days parameter,
• $dehydrated::private_key_renew parameter,
• $dehydrated::private_key_rollover parameter,
• $dehydrated::key_algo parameter,
• $dehydrated::ocsp_must_staple parameter.

Changed

• Modernize code base,
• Install curl on Debian hosts.

Removed

• letsencrypt.sh to dehydrated migration support.

1.1.0 - 2017-07-21

Changed

• Install dehydrated 0.4.0 on Debian.

1.0.1 - 2017-01-08

Fixed

• Fix warning when strict_variable checking is set.

[1.0.0] - 2017-01-08

Initial release