From 6744dc64b397ba898342e99664e8a8b9a55f261f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Sun, 15 Jan 2023 15:12:22 +0100
Subject: Add README.

---
 README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8943db9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+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',
+  email         => 'domainmaster@example.com',
+}
+```
+
+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.
+
+### 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
-- 
cgit v1.2.3