Wildcard Certificates

Wildcard certificates are supported by the FleetSSL cPanel plugin since v.0.13.0.

What is a Wildcard Certificate and do I need one?

A wildcard certificate is an SSL certificate that is valid for all subdomains of one or more domains. It can be identified by an *. prefix on any of the names it is issued for, e.g. *.example.org, *.staging.example.org

We suggest that the majority of users do not need wildcards. They are useful when:

  • You have many (10-100+) subdomains or combinations of subdomains
  • You don’t know what subdomains will exist, e.g. when you dynamically give each customer/user their own subdomain, e.g. when you have a subdomain-based multi-site
  • You regularly create new subdomains (at least on a monthly basis)
  • You are using a wildcard DNS record and need to protect all possible domains using SSL

Unless your requirements resemble one or more of those listed above, we recommend you stick to non-wildcard certificates. They are simpler, faster to issue and safer to manage.

Prerequisites

DNS Validation is required: Your DNS must be hosted with cPanel

Due to Let’s Encrypt policy, wildcard certificates must use DNS-based validation.

This means that your domain must have its DNS hosted with cPanel’s nameservers, because cPanel needs to be able to create TXT records to demonstrate control of your domain. If your domain has its DNS externally hosted, you will not be able to issue wildcard certificates.

The choice of validation method will be presented to you when you go to issue your certificate.

(For WHM administrators) DNS Cluster Delays

When DNS records are updated in cPanel, the changes may not be immediately visible in the attached DNS cluster. This is because cPanel’s DNS updates are done asynchronously.

By default, the plugin will wait for 5 seconds after completing all of the DNS modifications. This is a fairly conservative delay, but may be tuned for your specific hosting environment by altering the dns_challenge_delay_secs configuration parameter.

(For WHM administrators) ‘Zone Editor (AAAA, CAA, SRV, TXT)’ must be enabled in WHM Feature Manager

This isn’t specifically related to wildcards, but if you would like users to be able to use the DNS validation method, ensure that Zone Editor (AAAA, CAA, SRV, TXT) is enabled for your users’ packager in WHM’s Feature Manager.

How to issue a Wildcard Certificate

1. Open the Lets Encrypt SSL interface

Visit the Lets Encrypt SSL interface in cPanel, and select which domain you would like to issue a certificate for, as per the user guide.

2. Select the DNS validation method

Selecting DNS-01 validation

3. Select which domains you would like wildcards for:

Check the “Include Wildcard?” column to add the wildcard variant of any domain to your certificate request. You may include as many combinations of wildcards and other domains as you like on a single certificate.

Please take note, if you would like a certificate to be valid for mail.l33t.website as well as *.mail.l33t.website, you must tick both ‘Include?’ and ‘Include Wildcard?’, as the wildcard will not match the domain on its own.

Selecting wildcard domains

4. Issue

Press the Issue button and wait.

If you experience a failure, please double check that your domain is using t`he nameservers of your cPanel hosting service, rather than being externally hosted (such as on Cloudflare or Route53 or at your domain registrar).

If in doubt, get in contact with your cPanel hosting provider.

Sharing wildcards between virtual hosts

Sometimes you will want to share a single wildcard certificate between many virtual hosts.

Before 0.14.0, this was not possible, as each certificate was specific to an individual virtual host. Beginning 0.14.0, it is possible to reuse certificates across virtual hosts. These certificates will remain mapped even through renewal.

You can do this the following way:

1. Issue a wildcard certificate to your primary virtual host

Do this as you usually would. For example, issue a certificate for example.org and *.example.org.

2. Reuse the certificate

For each virtual host (i.e. subdomain) that should use this certificate as well, visit the Issue interface, and then find at the bottom of the page:

Click the link, and you will be faced with an interface to select the certificate to re-use:

Press Install and you’re all done!

CLI Usage

You may also use the CLI to perform the task, which should allow some automation.

The available commands are:

 reuse         Re-uses a certificate from one virtual host on another virtual host
 remove-reuse  Removes a re-use from a virtual host
 list-reuses   Lists all certificate re-uses configured on the account

Following the web-based example (where a wildcard for *.example.org is installed to the example.org virtual host), you would want to run:

le-cp ssl --user=USER reuse --source example.org --target client1.example.org

Resulting in:

le-cp ssl --user=USER list-reuses
INFO[0000] 1 re-uses found.
INFO[0000] Virtual host 'client1.example.org' re-uses the certificate from 'example.org'

and to unmap that certificate re-use:

le-cp ssl --user=USER remove-reuse --target client1.example.org