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

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 renewal_provider parameter of the dehydrated class selects how certificate renewal is triggered; set it to 'cron' to install a cron job that runs at the cadence configured by renewal_interval ('daily' by default, 'weekly', or 'never').

class { 'dehydrated':
  contact_email    => 'user@example.com',
  renewal_provider => 'cron',
}

Use renewal_provider => 'systemd' instead to ship a dehydrated.timer systemd unit with the same renewal cadence.

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]',
        },
      ],
    },
  ],
}