Setting Up Wildcard Subdomains with SSL on a Debian Application
This guide provides a step-by-step approach to setting up wildcard subdomains with SSL on a Debian-based application. Wildcard subdomains allow applications to dynamically support multiple subdomains (abc.example.com, xyz.example.com) under a single SSL certificate.
In this guide, the focus is on configuring a Debian package to handle wildcard subdomains primarily through updates to the debian/postinst file. The guide uses the kaboom-api app as an example, with staging-elearning.nl as the domain name on which we’re setting up wildcard subdomains.
If you do not need or prefer not to modify the application code itself, you can still follow the key steps and commands described in this guide directly from the terminal. This will allow you to set up SSL for wildcard subdomains without diving into the application’s Debian packaging configuration.
By the end of this guide, you will have a fully automated process for configuring and renewing SSL certificates for wildcard subdomains, leveraging tools like Certbot and DNS authentication.
Prerequisites
1. DNS Configuration for Wildcard Subdomains
Access your DNS repository and add the necessary A and AAAA records for the wildcard subdomain you plan to use. This typically involves adding entries like *.example.com pointing to your server’s IP address.
The following is an example of what has been done for the domain name staging-elearning.nl
staging-elearning.nl.zone
$ORIGIN staging-elearning.nl.
$TTL 3600
@ IN 3600 SOA delftsolutions.ns1.signaldomain.nl. info.signaldomain.nl. (
<serial> ; don't modify, auto incremented
86400 ; secondary refresh
7200 ; secondary retry
3600000 ; secondary expiry
600 ; negative response ttl
)
@ 3600 IN NS ns2.signaldomain.net.
@ 3600 IN NS delftsolutions.ns1.signaldomain.nl.
* IN 3600 A 193.5.147.172
* IN 3600 AAAA 2a0c:8187:0:201::196
2. Required Packages
- python3-certbot-dns-rfc2136
- openssl
- nginx
- dnsutils
- certbot
Configuring SSL and Wildcard Subdomains
1. Handling Environment Variables
We’ll first add three environment variables to capture essential information: DNS_AUTHENTICATION, CERTBOT_EMAIL, and FQDN. These variables will be defined using Debconf, which allows us to prompt for values during installation and configuration.
DNS_AUTHENTICATION: This string is required for Certbot’s DNS-based challenge verification. The format includes a keyname, algorithm, and secret for authentication, followed by the authoritative DNS hostname.
This string is currently obtained using the signal domain api package running the command :
signaldomain-api key certbot create <domain_name>
The expected format is: dns://<key_name>:<key_algorithm>~<key_secret_base64>@<authoritive_nameserver_domainname>
example: dns://staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.:hmac-sha256~<key_secret>@ns1.signaldomain.nl/staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.
CERTBOT_EMAIL: This email address is used when registering an account with Let’s Encrypt. Important notifications about certificate issues will be sent to this address.
FQDN: This is the fully qualified domain name of the primary domain for which wildcard SSL certificates will be issued. staging-elearning.nl for this guide example.
Here’s how to set these variables in debian/templates, define prompts in debian/config, and retrieve them in debian/postinst.
in debian/templates, add the following entries to create prompt templates for each variable:
…
Template: <PKG_NAME>/DNS_AUTHENTICATION
Type: string
Default:
Description: DNS authentication string in the following format: dns://<key_name>:<key_algorithm>~<key_secret_base64>@<authoritative_nameserver_domainname>
Template: <PKG_NAME>/CERTBOT_EMAIL
Type: string
Default:
Description: Enter the email that certificate issues should be reported to. Entering this will result in accepting the Let's Encrypt terms and conditions.
Template: <PKG_NAME>/FQDN
Type: string
Default:
Description: Enter the fully qualified domain name for ...
…
<PKG_NAME> is the name of your Debian package, kaboom-api in our case.
Add the following lines to your debian/config file to prompt for these variables during configuration:
in debian/templates, add the following entries to create prompt templates for each variable:
…
db_input medium <PKG_NAME>/CERTBOT_EMAIL || true
db_input medium <PKG_NAME>/DNS_AUTHENTICATION || true
db_input medium <PKG_NAME>/FQDN || true
…
In debian/postinst, retrieve the stored values with the following lines:
…
db_get <PKG_NAME>/DNS_AUTHENTICATION
DNS_AUTHENTICATION="$RET"
db_get <PKG_NAME>/CERTBOT_EMAIL
CERTBOT_EMAIL="$RET"
db_get <PKG_NAME>/FQDN
FQDN="$RET"
…
These values shall be set or updated once the whole config is over, by running the following command:
sudo dpkg-reconfigure <PKG_NAME>
2. Automating SSL and Wildcard Domain Setup in postinst
Here we will break down concern by concern how to configure the debian/postinst file.
a. Creating the dns-auth.conf File
The dns-auth.conf file will be generated from the DNS_AUTHENTICATION variable, which contains the details for Certbot’s DNS challenge configuration. Add the following to the debian/postinst file to create this file:
dns_hostname_path="$(cut -d'@' -f2- <<<"$DNS_AUTHENTICATION")"
dns_schema_auth="$(cut -d'@' -f1 <<<"$DNS_AUTHENTICATION")"
dns_hostname="$(cut -d'/' -f1 <<<"$dns_hostname_path")"
dns_auth="$(cut -d'/' -f3- <<<"$dns_schema_auth")"
dns_auth_keyname="$(cut -d':' -f1 <<<"$dns_auth")"
dns_auth_algorithm="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f1 | tr '[:lower:]' '[:upper:]')"
dns_auth_secret="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f2-)"
dns_host_aaaa="$(dig +short AAAA "$dns_hostname" | head -n1)"
[ -d etc/<DNS_CONF_DIR> ] || mkdir -p etc/<DNS_CONF_DIR>
umask 266
cat > etc/<DNS_CONF_DIR>/dns-auth.conf <<CONF
# Managed by apt, please use dpkg-reconfigure <PKG_NAME> to modify
dns_rfc2136_server = $dns_host_aaaa
dns_rfc2136_port = 53
dns_rfc2136_name = $dns_auth_keyname
dns_rfc2136_secret = $dns_auth_secret
dns_rfc2136_algorithm = $dns_auth_algorithm
CONF
umask 022
This configuration file will be used by Certbot to authenticate and verify domain ownership via DNS challenges.
In the case of our guide with the kaboom-api example, <DNS_CONF_DIR> is kaboom, it's up to you to select the right naming for your case.
Once the script has been executed The dns-auth.conf file should look something like this:
dns_rfc2136_server = 2a0c:8187::120
dns_rfc2136_port = 53
dns_rfc2136_name = staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.
dns_rfc2136_secret = <secret-key>
dns_rfc2136_algorithm = HMAC-SHA256
Make sure that proper letter case is observed as this would cause the script to fail with unclear error messages.
b. Setting Up Certbot and Requesting Certificates
To handle SSL certificates, Certbot needs to register an account (if not already registered) and request a certificate for the primary domain and wildcard subdomain. Add the following to postinst to check and register Certbot, then request the certificate:
certbot_account_count="$(find /etc/letsencrypt/accounts/acme-v02.api.letsencrypt.org/directory/ -maxdepth 1 -mindepth 1 | wc -l)"
if [ "z$certbot_account_count" = "z0" ]; then
certbot register --non-interactive --email "$CERTBOT_EMAIL" --no-eff-email --agree-tos
fi
[ ! -f "/etc/letsencrypt/live/<CERT_NAME>/fullchain.pem" ] || certbot certonly --non-interactive --cert-name <CERT_NAME> --dns-rfc2136 --dns-rfc2136-credentials etc/<DNS_CONF_DIR>/dns-auth.conf --domain "$FQDN" --domain "*.$FQDN" --deploy-hook /usr/share/<PKG_NAME>/bin/cert-deploy
This block registers Certbot, checks for an existing certificate, and if none exists, requests a new certificate using DNS authentication with the specified dns-auth.conf file. The --deploy-hook option calls the cert-deploy file after each certificate issuance or renewal. We will create the cert-deploy in step f..
In the case of our guide with the kaboom-api example, <CERT_NAME> is kaboom-elearning, again it's up to you to select the right naming for your case.
c. Generating Diffie-Hellman Parameters for SSL
Diffie-Hellman parameters enhance SSL security. To ensure this file exists, add the following to debian/postinst:
[ -f "etc/<DNS_CONF_DIR>/ssl-dhparams.pem" ] || openssl dhparam -out etc/<DNS_CONF_DIR>/ssl-dhparams.pem 2048
This code checks for an existing ssl-dhparams.pem file, generating one if it doesn’t exist, using 2048-bit encryption for security.
d. Configuring Nginx for Wildcard SSL
Finally, configure Nginx to handle requests for the wildcard domain and apply SSL settings. Here’s the code to create a new Nginx server block for the wildcard domain:
cat >/etc/nginx/sites-available/<CERT_NAME> <<CONF
server {
root /usr/share/<PKG_NAME>/public;
server_name *.$FQDN;
location / {
proxy_pass http://<PKG_NAME>/;
proxy_set_header Host \$host;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_buffers 8 32k;
proxy_buffer_size 64k;
client_max_body_size 0;
proxy_redirect off;
proxy_buffering off;
}
listen [::]:443 ssl http2;
listen 443 ssl http2;
ssl_certificate /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<CERT_NAME>/privkey.pem;
ssl_dhparam etc/<DNS_CONF_DIR>/ssl-dhparams.pem;
ssl_session_cache shared:le_nginx_SSL:10m;
ssl_session_timeout 1440m;
ssl_session_tickets off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
}
CONF
[ -L /etc/nginx/sites-enabled/<CERT_NAME> ] || ln -s /etc/nginx/sites-available/<CERT_NAME> /etc/nginx/sites-enabled
nginx -q -t && service nginx reload
e. Wrapping everything in an if statement
You do not want to run that part of the postinst script if you do not have the DNS_AUTHENTICATION, CERTBOT_EMAIL, and FQDN variables set.
This is why we’ll wrap everything we just covered inside an if statement
if [ -n "$DNS_AUTHENTICATION" ] && [ -n "$CERTBOT_EMAIL" ] && [ -n "$FQDN" ] ; then
#Everything we just wrote
else
echo "one or more of DNS_AUTHENTICATION, CERTBOT_EMAIL, FQDN are missing, skipping wildcard subdomains SSL certificate setup."
fi
Here is what the finished code looks like in the kaboom-api example
if [ -n "$DNS_AUTHENTICATION" ] && [ -n "$CERTBOT_EMAIL" ] && [ -n "$FQDN" ] ; then
dns_hostname_path="$(cut -d'@' -f2- <<<"$DNS_AUTHENTICATION")"
dns_schema_auth="$(cut -d'@' -f1 <<<"$DNS_AUTHENTICATION")"
dns_hostname="$(cut -d'/' -f1 <<<"$dns_hostname_path")"
dns_auth="$(cut -d'/' -f3- <<<"$dns_schema_auth")"
dns_auth_keyname="$(cut -d':' -f1 <<<"$dns_auth")"
dns_auth_algorithm="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f1 | tr '[:lower:]' '[:upper:]')"
dns_auth_secret="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f2-)"
dns_host_aaaa="$(dig +short AAAA "$dns_hostname" | head -n1)"
[ -d /etc/kaboom ] || mkdir -p /etc/kaboom
umask 266
cat >/etc/kaboom/dns-auth.conf <<CONF
# Managed by apt, please use dpkg-reconfigure kaboom-api to modify
dns_rfc2136_server = $dns_host_aaaa
dns_rfc2136_port = 53
dns_rfc2136_name = $dns_auth_keyname
dns_rfc2136_secret = $dns_auth_secret
dns_rfc2136_algorithm = $dns_auth_algorithm
CONF
umask 022
certbot_account_count="$(find /etc/letsencrypt/accounts/acme-v02.api.letsencrypt.org/directory/ -maxdepth 1 -mindepth 1 | wc -l)"
if [ "z$certbot_account_count" = "z0" ]; then
certbot register --non-interactive --email "$CERTBOT_EMAIL" --no-eff-email --agree-tos
fi
echo "Checking if SSL certificate already exists"
if [ ! -f "/etc/letsencrypt/live/kaboom-elearning/fullchain.pem" ]; then
echo "Requesting new certificate for $FQDN and *.$FQDN"
certbot certonly --non-interactive --cert-name kaboom-elearning --dns-rfc2136 --dns-rfc2136-credentials /etc/kaboom/dns-auth.conf --domain "$FQDN" --domain "*.$FQDN" --deploy-hook /usr/share/kaboom-api/bin/cert-deploy
if [ $? -eq 0 ]; then
echo "Certificate obtained successfully"
else
echo "Error obtaining certificate"
fi
else
echo "Certificate already exists"
fi
echo "Checking if SSL DHParams file already exists"
if [ ! -f "/etc/kaboom/ssl-dhparams.pem" ]; then
openssl dhparam -out /etc/kaboom/ssl-dhparams.pem 2048
if [ $? -eq 0 ]; then
echo "DHParams generated successfully"
else
echo "Error generating DHParams"
fi
else
echo "DHParams file already exists"
fi
cat >/etc/nginx/sites-available/kaboom-elearning <<CONF
server {
root /usr/share/kaboom-api/public;
server_name *.$FQDN;
location / {
proxy_pass http://kaboom_api/;
proxy_set_header Host \$host;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_buffers 8 32k;
proxy_buffer_size 64k;
client_max_body_size 0;
proxy_redirect off;
proxy_buffering off;
}
listen [::]:443 ssl http2;
listen 443 ssl http2;
ssl_certificate /etc/letsencrypt/live/kaboom-elearning/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/kaboom-elearning/privkey.pem;
ssl_dhparam /etc/kaboom/ssl-dhparams.pem;
ssl_session_cache shared:le_nginx_SSL:10m;
ssl_session_timeout 1440m;
ssl_session_tickets off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
}
CONF
[ -L /etc/nginx/sites-enabled/kaboom-elearning ] || ln -s /etc/nginx/sites-available/kaboom-elearning /etc/nginx/sites-enabled
nginx -q -t && service nginx reload
else
echo "one or more of DNS_AUTHENTICATION, CERTBOT_EMAIL, FQDN are missing, skipping wildcard subdomains SSL certificate setup."
fi
f. Creating the cert-deploy Deploy Hook
The certbot command calls in a cert-deploy file via the --deploy-hook flag. This cert-deploy script, should be created in /usr/share/<PKG_NAME>/bin, and runs after each certificate issuance or renewal.
#!/bin/bash
set -euo pipefail
if [ "z$RENEWED_LINEAGE" != "z/etc/letsencrypt/live/<CERT_NAME>" ]; then
echo "Unknown certificate renewed, ignoring" 1>&2
exit 1
fi
nginx -q -t && service nginx reload