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 ELEARNING_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.

ELEARNING_FQDN: This is the fully qualified domain name (FQDN) of the primary domain for which wildcard SSL certificates will be issued. staging-elearning.nl for this guide example.