Enable YAML configuration

This patch allows configuring nginx-certbot with a config.yml file. In
particular this allows to directly declare the certificates that should
be requested by certbot with finer granularity compared to the automatic
discovery based on the nginx config files.

Main motivations:

 - Currently, since automatic discovery is implemented on a per file
   basis, all domain names in a file are attached ot all certificates in
   that file. This means that for e.g.
   ```nginx
   server {
       server_name      example.com *.example.com;
       ssl_certificate  /etc/letsencrypt/live/example-com/fullchain.pem;
       # [...]
   }
   server {
       server_name      a.example.com;
       ssl_certificate  /etc/letsencrypt/live/a-example-com/fullchain.pem;
       # [...]
   }
   ```
   both `example-com` and `a-example-com` will contain the domain names
   `example.com`, `*.example.com`, and `a.example.com`.
   With this patch it is possible to instead do
   ```yaml
   certificates:
     - name: example-com
       domains: [example.com, *.example.com]
     - name: a-example-com
       domains: [a.example.com]
   ```

 - Currently the authenticator credentials can't be specified on a per
   certificate basis (see e.g. #315). With this patch that is possible:
   ```yaml
   certbot:
     authenticator: dns-cloudflare
   certificates:
     - name: example-com
       domains: [example.com]
       credentials: /etc/letsencrypt/example-com-cloudflare.ini
     - name: example-se
       domains: [example.se]
       credentials: /etc/letsencrypt/example-se-cloudflare.ini
   ```

 - Authenticator and key type can currently be specified on a
   per-certificate basis by naming them appropriately. This works okay,
   but it becomes a bit clunky to support more such per-certificate
   configurations (such as e.g. the elliptic curve or the authenticator
   credentials). This patch allows to directly specify everything for
   each certificate:
   ```yaml
   certbot:
     authenticator: dns-cloudflare
     key-type: ecdsa
   certificates:
     - name: example-com-rsa
       domains: [example.com]
       key-type: rsa
     - name: example-com
       domains: [example.com]
   ```

The file examples/config.yml is documented with all the various options
that are enabled.

Author: fredrikekre

README.md

@@ -62,25 +62,41 @@ instructions, from `@staticfloat`'s image, can be found
    function.
 
 
-## Available Environment Variables
+## Configuration
+
+The container can be configured using a YAML config file or with environment
+variables. The config file takes precendence whenever a setting is specified
+twice. The default location of the config file is
+`/etc/nginx-certbot/config.yml` but can be customized with the environment
+variable `NGINX_CERTBOT_CONFIG_FILE`. A documented example config file can be
+found in the [`examples/`](./examples) folder.
 
 ### Required
-- `CERTBOT_EMAIL`: Your e-mail address. Used by Let's Encrypt to contact you in case of security issues.
+
+| YAML key        | Environment variable | Description |
+| --------------- | -------------------- | ----------- |
+| `certbot.email` | `CERTBOT_EMAIL`      | Your e-mail address. Used by Let's Encrypt to contact you in case of security issues. |
 
 ### Optional
-- `DHPARAM_SIZE`: The size of the [Diffie-Hellman parameters](./docs/good_to_know.md#diffie-hellman-parameters) (default: `2048`)
-- `ELLIPTIC_CURVE`: The size/[curve][15] of the ECDSA keys (default: `secp256r1`)
-- `RENEWAL_INTERVAL`: Time interval between certbot's [renewal checks](./docs/good_to_know.md#renewal-check-interval) (default: `8d`)
-- `RSA_KEY_SIZE`: The size of the RSA encryption keys (default: `2048`)
-- `STAGING`: Set to `1` to use Let's Encrypt's [staging servers](./docs/good_to_know.md#initial-testing) (default: `0`)
-- `USE_ECDSA`: Set to `0` to have certbot use [RSA instead of ECDSA](./docs/good_to_know.md#ecdsa-and-rsa-certificates) (default: `1`)
+
+| YAML key                         | Environment variable | Description |
+| -------------------------------- | -------------------- | ----------- |
+| `nginx-certbot.renewal-interval` | `RENEWAL_INTERVAL`   | Time interval between certbot's [renewal checks](./docs/good_to_know.md#renewal-check-interval) (default: `8d`) |
+| `nginx-certbot.dhparam-size`     | `DHPARAM_SIZE`       | The size of the [Diffie-Hellman parameters](./docs/good_to_know.md#diffie-hellman-parameters) (default: `2048`) |
+| `certbot.elliptic-curve`         | `ELLIPTIC_CURVE`     | The size/[curve][15] of the ECDSA keys (default: `secp256r1`) |
+| `certbot.rsa-key-size`           | `RSA_KEY_SIZE`       | The size of the RSA encryption keys (default: `2048`) |
+| `certbot.staging`                | `STAGING`            | Set to `1` to use Let's Encrypt's [staging servers](./docs/good_to_know.md#initial-testing) (default: `0`) |
+| -                                | `USE_ECDSA`          | Set to `0` to have certbot use [RSA instead of ECDSA](./docs/good_to_know.md#ecdsa-and-rsa-certificates) (default: `1`) |
+| `certbot.key-type`               | -                    | Certificate key type (default: `ecdsa` (or, if `USE_ECDSA=0`, `rsa`) |
 
 ### Advanced
-- `CERTBOT_AUTHENTICATOR`: The [authenticator plugin](./docs/certbot_authenticators.md) to use when responding to challenges (default: `webroot`)
-- `CERTBOT_DNS_PROPAGATION_SECONDS`: The number of seconds to wait for the DNS challenge to [propagate](.docs/certbot_authenticators.md#troubleshooting-tips) (default: certbot's default)
-- `DEBUG`: Set to `1` to enable debug messages and use the [`nginx-debug`][10] binary (default: `0`)
-- `USE_LOCAL_CA`: Set to `1` to enable the use of a [local certificate authority](./docs/advanced_usage.md#local-ca) (default: `0`)
 
+| YAML key                          | Environment variable              | Description |
+| --------------------------------- | --------------------------------- | ----------- |
+| `certbot.authenticator`           | `CERTBOT_AUTHENTICATOR`           | The [authenticator plugin](./docs/certbot_authenticators.md) to use when responding to challenges (default: `webroot`) |
+| `certbot.dns-propagation-seconds` | `CERTBOT_DNS_PROPAGATION_SECONDS` | The number of seconds to wait for the DNS challenge to [propagate](.docs/certbot_authenticators.md#troubleshooting-tips) (default: certbot's default) |
+| `nginx-certbot.debug`             | `DEBUG`                           | Set to `1` to enable debug messages and use the [`nginx-debug`][10] binary (default: `0`) |
+| -                                 | `USE_LOCAL_CA`                    | Set to `1` to enable the use of a [local certificate authority](./docs/advanced_usage.md#local-ca) (default: `0`) |
 
 ## Volumes
 - `/etc/letsencrypt`: Stores the obtained certificates and the Diffie-Hellman parameters

docs/good_to_know.md

@@ -65,6 +65,13 @@ in the old way like how [`@staticfloat`'s image][5] worked.
 
 
 ## How the Script add Domain Names to Certificate Requests
+There are two ways to configure the certificates the container should request
+and maintain:
+ - [Automatic discovery](#automatic-certificate-discovery) based on the mounted
+   Nginx config files
+ - Explicit specification using the [YAML config file](#yaml-certificate-specification)
+
+### Automatic certificate discovery
 The included script will go through all configuration files (`*.conf*`) it
 finds inside Nginx's `/etc/nginx/conf.d/` folder, and create requests from the
 file's content. In every unique file it will find any line that says:
@@ -119,6 +126,28 @@ Furthermore, we support wildcard domain names, but that requires you to use an
 authenticator capable of DNS-01 challenges, and more info about that may be
 found in the [certbot_authenticators.md](./certbot_authenticators.md) document.
 
+### YAML certificate specification
+To explicitly define certificate requests you can define a list `certificates:`
+list in a YAML config file (`/etc/nginx-certbot/config.yml` by default). Note
+that when the `certificates` key exist the automatic discovery from nginx
+config files is disabled and *only* certificates from the config file are
+requested.
+
+The example from the previous section would correspond to the following
+specification:
+```yaml
+certificates:
+  - name: test-name
+    domains:
+      - yourdomain.com
+      - www.yourdomain.com
+      - sub.yourdomain.com
+```
+
+Refer to the commented example [`config.yml`](../examples/config.yml) file for
+more details. It is, for example, possible to specify the
+[certbot authenticator](./certbot_authenticators.md), and the certificate
+[key type](#ecdsa-and-rsa-certificates).
 
 ## ECDSA and RSA Certificates
 [ECDSA (or ECC)][16] certificates use a newer encryption algorithm than the well

examples/config.yml

@@ -0,0 +1,62 @@
+# Configuration for this docker image
+nginx-certbot:
+  # Diffie-Hellman parameter size. Falls back to the DHPARAM_SIZE environment variable or,
+  # if that is unset, to '2048'.
+  dhparam-size: 2048
+  # Certificate renewal interval. Falls back to the RENEWAL_INTERVAL environment variable
+  # or, if that is unset, to '8d'.
+  renewal-interval: 8d
+  # Boolean to enable verbose debug messages and the nginx-debug binary. Falls back to the
+  # DEBUG environment variable, or, if that is unset, to 'false'.
+  debug: false
+
+# Configuration for certbot.
+# Note that some of these can be overriden on the certificate level.
+certbot:
+  # Default certbot authenticator (see certbots --authenticator flag). Falls back to the
+  # CERTBOT_AUTHENTICATOR environment variable or, if that is unset, to 'webroot'. The
+  # authenticator can be overriden on the certificate level.
+  authenticator: webroot
+  # Default certbot authenticator credentials (see certbots --<authenticator>-credentials
+  # flag). This is required for the various DNS authenticators. Falls back to
+  # '/etc/letsencrypt/<authenticator>.ini'.
+  credentials: ''
+  # Number of seconds to wait for the DNS challenge (when using dns authenticators). Falls
+  # back to the CERTBOT_DNS_PROPAGATION_SECONDS environment variable and if that is unset to
+  # certbots default.
+  dns-propagation-seconds: ''
+  # Default elliptic curve (see certbots --elliptic-curve flag). Falls back to the
+  # ELLIPTIC_CURVE environment variable or, if that is unset, to 'secp256r1'.
+  elliptic-curve: secp256r1
+  # Default key type (see certbots --key-type flag). Falls back to 'ecdsa' (or if
+  # USE_ECDSA=0 to 'rsa'). The key type can be overriden on the certificate level.
+  key-type: ecdsa
+  # Default RSA key size (see certbots --rsa-key-size flag). Falls back to the RSA_KEY_SIZE
+  # environment variable or, if that is unset, to 2048. The key size can be overriden on the
+  # certificate level.
+  rsa-key-size: 2048
+  # Boolean to enable the Let's Encrypt staging servers. Falls back to the STAGING
+  # environment variable or, if that is unset, to 'false'.
+  staging: false
+
+# Array of certificate specifications.
+# If the 'certificates' key exist (even if the array is empty) the automatic discovery of
+# certificate names and domains is disabled and instead nginx-certbot will request
+# certificates based on the specifications in the array.
+# A minimum requirement for each certificate is to specifiy 'name' and 'domains'.
+certificates:
+    # Certificate name (see certbots --cert-name flag). Generated certificates will be
+    # placed in the /etc/letsencrypt/live/<name>/ folder. This is a required parameter.
+  - name: example-com
+    # Required list of domains for which the certificate should be valid for (see certbots
+    # --domain flag). This is a required parameter.
+    domains: ["a.example.com", "b.example.com", "*.c.example.com"]
+    # Authenticator to use for this certificate. Falls back to certbot.authenticator.
+    authenticator: ''
+    # Credential file for this certificates authenticator. Falls back to
+    # certbot.credentials.
+    credentials: ''
+    # Key type for the certificate. Falls back to certbot.key-type.
+    key-type: ''
+    # RSA key size for the certificate. Falls back to certbot.rsa-key-size.
+    rsa-key-size: ''

src/Dockerfile

@@ -71,6 +71,8 @@ RUN set -ex && \
     pip3 install -r /requirements.txt && \
 # And the supported extra authenticators.
     pip3 install $(echo $CERTBOT_DNS_AUTHENTICATORS | sed 's/\(^\| \)/\1certbot-dns-/g') && \
+# Install shyaml
+    pip3 install shyaml && \
 # Remove everything that is no longer necessary.
     apt-get remove --purge -y \
             build-essential \

src/scripts/create_dhparams.sh

@@ -11,6 +11,16 @@ set -e
 # The created file should be stored somewhere under /etc/letsencrypt/dhparams/
 # to ensure persistence between restarts.
 create_dhparam() {
+    # Read dhparam-size from config file, falling back to DHPARAM_SIZE environment variable.
+    local CONFIG_FILE="${NGINX_CERTBOT_CONFIG_FILE:-/etc/nginx-certbot/config.yml}"
+    if [ -f "${CONFIG_FILE}" ]; then
+        local YAML_DHPARAM_SIZE
+        YAML_DHPARAM_SIZE=$(shyaml get-value nginx-certbot.dhparam-size '' < "${CONFIG_FILE}")
+        if [ -n "${YAML_DHPARAM_SIZE}" ]; then
+            DHPARAM_SIZE=${YAML_DHPARAM_SIZE}
+            debug "Using nginx-certbot.dhparam-size=${DHPARAM_SIZE} from config file."
+        fi
+    fi
     if [ -z "${DHPARAM_SIZE}" ]; then
         debug "DHPARAM_SIZE unset, using default of 2048 bits"
         DHPARAM_SIZE=2048