Wildcard Certificates with Let’s Encrypt and NGINX

Let’s Encrypt released the ability to generate wildcard certificates since we wrote the introduction to Let’s Encrypt with NGINX. This feature is brand new, released on March 13, 2018, so can we use it?

Note: this tutorial assumes that NGINX and certbot are already installed on a CentOS 7 server. Follow this post if you haven’t already.

Ensuring Certbot Is Updated

Before we can utilize wildcard certificates, we need to make sure that we have a new enough version of certbot. We need at least 0.22.0.

$ certbot --version
certbot 0.22.0

To upgrade an older version of the package that we installed, we can run yum update.

$ sudo yum update certbot-nginx

How Let’s Encrypt Wildcard Certs Work

There’s a difference in the approach necessary for working with Let’s Encrypt wildcard certificates because they require doing a DNS challenge using a TXT record. We can accomplish this in two ways:

  1. Using a certbot DNS plugin.
  2. Using the --manual option for certbot

The various DNS plugins work in roughly the same way, but if the provider you’re using doesn’t have one available, then you’ll need to use the --manual option. Unfortunately, the --manual option doesn’t provide a great way for auto-renewing certificates if the DNS provider doesn’t have an API for creating records. If possible, using a DNS plugin is best. For this example, I’m going to be working with a domain that is managed by DNSimple and there is a DNSimple plugin.

We’ll need to have our DNS set up to point to our server already. Here are the DNS records that I’ve created myself:

@       A       MY_IP_ADDRESS
www     CNAME   chord.tools
blog    CNAME   chord.tools

I realize that chord.tools is a weird domain.

Configuring the DNS Plugin

DNS plugins for certbot are Python packages so they can be installed using pip, but they can sometimes also be installed using the system package manager (yum in our case). To see what we have available, let’s do a yum search:

$ sudo yum search certbot | grep dns
python2-certbot-dns-cloudflare.noarch : Cloudflare DNS Authenticator plugin for
python2-certbot-dns-cloudxns.noarch : CloudXNS DNS Authenticator plugin for
python2-certbot-dns-digitalocean.noarch : DigitalOcean DNS Authenticator plugin
python2-certbot-dns-dnsimple.noarch : DNSimple DNS Authenticator plugin for
python2-certbot-dns-dnsmadeeasy.noarch : DNS Made Easy DNS Authenticator plugin
python2-certbot-dns-google.noarch : Google Cloud DNS Authenticator plugin for
python2-certbot-dns-luadns.noarch : LuaDNS Authenticator plugin for Certbot
python2-certbot-dns-nsone.noarch : NS1 DNS Authenticator plugin for Certbot
python2-certbot-dns-rfc2136.noarch : RFC 2136 DNS Authenticator plugin for
python2-certbot-dns-route53.noarch : Route53 DNS Authenticator plugin for

For my situation, I’m going to install the python2-certbot-dns-dnsimple package.

$ sudo yum install -y python2-certbot-dns-dnsimple

The last thing that we need before moving forward is a credentials file. How this file is generated depends on the DNS plugin being used. For DNSimple, we need to generate an API token and place it in an INI file that looks something like this (the location of this file doesn’t matter):


dns_dnsimple_token = MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw

Creating Virtual Host Configuration

We’re going to point all of these subdomains at a single NGINX server. Let’s create the configuration now (substitute chord.tools with your domain):


server {
    listen 80;
    server_name .chord.tools;
    root /usr/share/nginx/html;

The special syntax of .chord.tools matches chord.tools and *.chord.tools. Now we’re ready to generate our first Let’s Encrypt wildcard SSL certificate. Our root points to the default NGINX HTML files just so that there is something to display.

Generating the Certificate

The general shape for our command to generate our certificates will match this:

$ sudo certbot 
  -a dns-[DNS_PROVIDER] 
  --dns-[DNS_PROVIDER]-credentials /path/to/credentials 
  --dns-[DNS_PROVIDER]-propagation-seconds 60 
  -i nginx 
  -d "*.example.com" 
  --server https://acme-v02.api.letsencrypt.org/

We’re being specific about the server that we use for this because it must be the ACME V2 server to handle wildcard certificates. With the credential file path that we’re working with and “dnsimple” substituted in, this is my final command:

$ sudo certbot 
  -a dns-dnsimple 
  --dns-dnsimple-credentials /var/.secrets/dnsimple-credentials.ini 
  --dns-dnsimple-propagation-seconds 60 
  -i nginx 
  -d "*.chord.tools" 
  --server https://acme-v02.api.letsencrypt.org/directory

This process might send you through some prompts if it’s your first time using certbot on that server. If so, you’ll want to answer them accordingly. Eventually, if the DNS challenge succeeds, we will be prompted about what NGINX configuration file to change and whether to redirect traffic to HTTPS. We should select the proper configuration file and select that we do want to redirect all traffic to HTTPS.

After this process is finished, we should be able to visit our domain and our subdomains to see that they are using a valid wildcard SSL certificate.


Let’s Encrypt supporting wildcard certificates is awesome and makes it even easier for us to secure multiple domains and subdomains. If you have the option to use a DNS Plugin, I encourage you to do so because it makes managing certificates with Let’s Encrypt incredibly simple.


Hands-On Linux Training hbspt.cta.load(3900131, ‘e30a6bf3-2ac0-490c-80c3-d59598799683’, {});

The post Wildcard Certificates with Let’s Encrypt and NGINX appeared first on Linux Academy Blog.

You might also like
Leave A Reply

Your email address will not be published.