Enable YAML configuration

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,16 +11,13 @@ set -e
 # The created file should be stored somewhere under /etc/letsencrypt/dhparams/
 # to ensure persistence between restarts.
 create_dhparam() {
-    if [ -z "${DHPARAM_SIZE}" ]; then
-        debug "DHPARAM_SIZE unset, using default of 2048 bits"
-        DHPARAM_SIZE=2048
-    fi
-
+    local dhparam_size
+    dhparam_size=$(get_config nginx-certbot.dhparam-size DHPARAM_SIZE 2048 "Diffie-Hellman parameter size")
     info "
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     %                        ATTENTION!                       %
     %                                                         %
-    % This script will now create a ${DHPARAM_SIZE} bit Diffie-Hellman   %
+    % This script will now create a ${dhparam_size} bit Diffie-Hellman   %
     % parameter to use during the SSL handshake.              %
     %                                                         %
     % >>>>>      This MIGHT take a VERY long time!      <<<<< %
@@ -34,7 +31,7 @@ create_dhparam() {
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     "
     info "Will now output to the following file: '${1}'"
-    openssl dhparam -out "${1}" "${DHPARAM_SIZE}"
+    openssl dhparam -out "${1}" "${dhparam_size}"
     info "
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % >>>>>   Diffie-Hellman parameter creation done!   <<<<< %