Letsencrypt
===========
A module for configuring certificates from letsencrypt (or other ACME
providers), and deploying them.

Table of Contents
-----------------
1. [Why](#why)
2. [Usage](#usage)
    1. [Examples](#examples)
    2. [Authenticators](#authenticators)
    3. [Facts](#facts)
3. [Restrictions](#restrictions)
3. [Other Stuff](#other-stuff)

Why
---
Why this module instead of [puppet/letsencrypt][2]? Setting up certificates on
existing infrastructure with that module isn't a problem. However, bootstraping
new servers is a problem, since one usually wants to write a complete server
configuration (for nginx (or similar)) at the beginning, but letsencrypt
requires a working webserver to authenticate. This module solves that (see
[Server Integration](#Server Integration)).

This module also allows multiple domains to be added to a single certificate one
by one, instead of requiring them all to be pre-determined.

Usage
-----

### Examples

For basic usage, include `letsencrypt`, and define `letsencrypt::cert`
resources.

```puppet
include ::letsencrypt
letsencrypt::cert { 'example.com':
  include_self  => true,
  authenticator => 'nginx',
}
```

Each certificate can have its own authenticator and configuration, allowing
multiple different setups to co-exist.

#### Server Integration

A number of functions are available for easy integration with different
web servers (currently only nginx). These procedures expand to a correct ssl
configuration if the wanted certificate is available, or to `ssl => false` (or
similar) if it isn't. This allows efficient bootstrapping.

The following example would configure an ngnix server without SSL on its first
run, but configure a server with ssl on future runs (since the certificate will
be generated by then).

```puppet
nginx::resource::server { 'example.com':
  * => letsencrypt::conf::nginx('example.com'),
}
```

It's recommended to reload to add a post-hook to `letsencrypt::cert` which
reloads your server configuration. This won't allow SSL to get configured on the
first run, but is usually needed when a certificate gets renewed.

```
letsencrypt::cert { 'example.com':
  # [...]
  config => {
    'post-hook' => 'nginx -s reload',
  },
}
```

#### Extra Domains

Additional domain names can later be added to a given certificate.

```puppet
letsencrypt::domain { 'subdomain.example.com':
  cert_name => 'example.com',
}
```

This is for example useful if you have a profile which sets up a certificate
with the hosts fully qualified domain name as its name, and each other profile
registering domains to that certificate.

### Authenticators

Each certificate needs to be authenticated, this has no relation to where the
certificate is used, even though the usual configuration uses the certificates
on the same web server which was used for authentication. Currently only nginx
is supported.

### Facter Facts

#### `letsencrypt_bycertname`
A hash from each certificates locally chosen name, to its directory in the
letsencrypt live directory. The actual directory name [may have extra numbers on
its end]. This fact strips them to allow one to check if a given certificate is
loaded.

#### `letsencrypt_directory`
A hash from each domain name which has a certificate, to its directory in
letsencrypts live directory.
`"${letsencrypt_directory['example.com']}/fullchain.pem"` or similar is probably
what you want.

Restrictions
------------
Currently only nginx is supported. In the future, at least the following should
be supported:
- Apache2 authenticator
- Apache2 configuration function
- Route53 authenticator

The letsencrypt directories aren't cleaned up if certificates is no longer
managed.

The module doesn't notice if the authenticator service changes, meaning that old
certificates will need to be removed by hand.

Other Stuff
-----------
When debugging locally, configuration files will be placed in
`/etc/letsencrypt`. Letsencrypt stores its debug logs to
`/var/log/letsencrypt/letsencrypt.log`.

[1]: https://eff-certbot.readthedocs.io/en/stable/using.html#where-are-my-certificates
[2]: https://forge.puppet.com/modules/puppet/letsencrypt