dehydrated

Forked from https://github.com/opus-codium/puppet-dehydrated

Table of Contents

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with dehydrated
   • Beginning with dehydrated
3. Usage - Configuration options and additional functionality
   • Generate a simple certificate
   • Generate a certificate with SAN
   • Renewing certificates with cron
   • Serving challenges with Apache
   • Handling the letsencrypt_sh to dehydrated transition
4. Reference - An under-the-hood peek at what the module is doing and how
   • Classes
   • Defined Types

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':
  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':
  email => 'user@example.com',
}

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

Generate a certificate with SAN

A dehydrated::certificate can use the domain parameter to indicate Subject Alternative Names (SAN).

class { 'dehydrated':
  email => 'user@example.com',
}

dehydrated::certificate { 'example.com':
  domains => [
    'www.example.com',
    'example.net',
    'www.example.net'
  ],
}

Renewing certificates with cron

The cron_enabled parameter of the dehydrated class configures cron to renew certificates before they expire.

class { 'dehydrated':
  email    => 'user@example.com',
  cron_enabled => true,
}

Serving challenges with Apache

The module can be integrated with the puppetlabs apache module to serve the challenges used for domain validation.

The following example redirects all HTTP requests to HTTPS except those related to letsencrypt's validation:

class { 'dehydrated':
  email      => 'user@example.com',
}

include ::apache
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]',
        },
      ],
    },
  ],
}
apache::custom_config { 'dehydrated':
  source => "puppet:///modules/profiles/dehydrated/apache_alias.conf",
}

Alias /.well-known/acme-challenge/ /var/lib/dehydrated/.acme-challenges/

<Directory /var/lib/dehydrated/.acme-challenges>
    Require all granted
</Directory>

Handling the letsencrypt.sh to dehydrated transition

This module assumes you're starting from scratch and not migrating from letsencrypt.sh. It makes no attempt to migrate your configuration.

Classes

Public Classes

• dehydrated

Defined Types

• dehydrated::certificate

Class: dehydrated

Main class used to setup the system.

Required parameters

• email: The e-mail address Let's Encrypt can use to reach you regarding your certificates.

Optional parameters

• user: Specifies the user account used to manage certificates. Default: 'dehydrated'.
• group: Specifies the group account used to manage certificates. Default: 'dehydrated'.
• staging_enabled: Specifies whether to use the lets encrypt staging server. Default: 'false'.
• cron_enabled: Specifies whether to setup cron to automatically renew certificates. Default: 'true'.

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).