Confconsole - Let's Encrypt

Overview

Confconsole Let's Encrypt plugin provides a simple way to get a free legitimate CA signed TLS/SSL certificate via Let's Encrypt. It supports both the HTTP-01 and DNS-01 "challenge" methods to validate your control of the (sub)domain(s) that you are registering.

HTTP-01 challenges are hosted by our custom mini webserver via port 80. If port 80 is already in use, the default webserver is temporarily stopped. DNS-01 challenges are fulfilled by temporarily setting a TXT DNS record via a supported DNS provider's API.

By default Confconsole supports registering a domain with up to 4 subdomains, in a single certificate which the existing webserver will use on all https ports. So Adminer, etc will also use the same certificate, as will Webmin (via it's built in miniserver). Wildcard certificates are also supported, but they require DNS-01 validation (not compatible with HTTP-01).

Beyond initial setup via Confconsole, no additional configuration of your server is generally required. Common usage scenarios should "just work". More uncommon and/or complex ones are still possible, but may require additional configuration.

By default, Confconsole should "just work" with these servers/webservers:

• Apache
• LigHTTPd
• Nginx
• Tomcat
• Webmin

If you wish to see support for alternate servers, please post on the forums, and/or open a issue on our tracker if you're open to contributing code, that's warmly welcomed.

Cert auto renew

Selecting this option makes the default TLS/SSL certificate renewal cron job (/etc/cron.daily/confconsole-dehydrated) executable (or not). Only executable files within /etc/cron.daily are triggered automatically by cron.

Note: Until you get your initial certificate (which also configures dehydrated), the cron job doesn't exist in the cron.daily directory. This ensures that the cron job can't be enabled until the dehydrated-wrapper has been run (and hopefully a Let's Encrypt TLS/SSL cert has been generated).

Note: To generate wildcard certificates with the TurnKey Let's Encrypt integration, you will need to use DNS-01 validation. DNS-01 validation is not available prior to Confconsole v2.1 (first appears in TurnKey v18.0).

For more info about what the cron job actually does, please see Cron job details below.

Get certificate

Selecting this option will allow you to set a single fully qualified domain name (FQDN) for you server.

Another option is to set a root domain and up to 4 separate subdomains.

If you wish to set more than one root domain and/or more than 4 subdomains, manual configuration is required. Please see Advanced - usage with multiple domain names below. If you have another scenario not covered, please sign up and post on the forums.

Getting a certificate - HTTP-01

This option will validate your ownership of the domain(s) via looking up public DNS records of the domain(s) and checking that the appropriate challenge data is being served via port 80 of your server.

Requirements:

• Port 80: port 80 (default vanilla HTTP port) must be open on your server and publicly available
• DNS record(s): authoritative 'A'/'AAAA' or 'CNAME' record(s) which resolve to your server (for all domains/subdomains you are getting certs for)

Port 80: Beyond the port being externally accessible, no changes to existing web server config are required. E.g. web server config redirecting all traffic from HTTP to HTTP will be ignored, so does not need to be changed.

DNS record(s): If you have just made the required changes with your DNS registrar, please be aware that it can take time for DNS records to publicly propagate. To double check that your DNS records are publicly available, please check via 'dig'. E.g. Google's free online Dig tool.

Important Note: Please ensure that you have your Domain nameservers correctly configured and port 80 is publicly available prior to running this. Failure to do so will cause the Let's Encrypt challenges to fail (so you won't get a certificate). Repeated failures may cause your server to be blocked (for a week) from further attempts.

Getting a certificate - DNS-01

This option will validate your ownership of the domain(s) via looking up a special public DNS TXT record of the root domain and ensuring that it contains the appropriate challenge data. No external access is required to your server, so this option is ideal for internal/intranet servers. This option also supports wildcard certificates (e.g. '*.example.com').

Requirements:

• Supported DNS provider: your domain must be registered with a supported provider
• Credentials: User credentials and/or API key (as relevant) for accessing your DNS provider's API

Supported DNS provider: The required TXT DNS record needs to be created with your DNS registrar. Confconsole leverages Dehydrated which in turn leverages dns-lexicon to created the required TXT DNS record. As such, your domain needs to be registered with a supported provider.

Credentials: To create the required DNS record, access to your DNS provider (via API) is required. Each provider has different requirements, so please consult the dns-lexicon docs. On that doc page, find your provider and click the link. That should take you to the relevant section of that page. The relevant fields are formatted as dot points, with the key noted in monospace font, colored orange, with an explanation after.

Note that the config file may contain comments (lines starting with a '#' prefix) which will be ignored. See a few config examples below:

AWS Route53: (lexicon docs)

# AWS Route53 example
auth_access_key: YOUR_AWS_ACCESS_KEY
auth_access_secret: YOUR_AWS_ACCESS_SECRET
private_zone: False # generally you'll always want public zone
zone_id: YOUR_ZONE_ID

Cloudflare: (lexicon docs)

# Cloudflare example 1 - using global api key
auth_username: YOUR_CF_USERNAME
auth_token: YOUR_CF_API_TOKEN

Or

# Cloudflare example 2 - using unscoped API token
auth_token: YOUR_CF_UNSCOPED_API_TOKEN

Or

# Cloudflare example 3 - using scoped API token
auth_token: YOUR_CF_SCOPED_API_TOKEN
zone_id: YOUR_CF_ZONE_ID

For other DNS providers, please consult the relevant docs by clicking your provider in the list at the top of the DNS Lexicon provider doc page.

Special note re Wildcard certificates

Please note that generating a Wildcard certificate is only available when using the DNS-01 challenge method.

A wildcard certificate, is a special certificate that is generated for a domain that starts with an asterisk: '*', e.g. '*.example.com'. This special certificate that will match any subdomain (within limits). E.g. '*.example.com' will cover sites with domains such as 'www.example.com', 'blog.example.com' and 'docs.example.com'. However the same cert won't work with sub-sub-domains, e.g. a '*.example.com' certificate won't work with 'www.docs.example.com'. For 'www.docs.example.com' to work with a wildcard cert, you'd need to get a cert for '*.docs.example.com'.

It is possible to register specific sub domains at the same time as registering a wildcard domain, however, the wildcard domain must come first. Multiple wildcard domains are also allowed.

Also, when registering a wildcard domain, Dehydrated needs to give it an alias. You will see instructions online to separate the domain(s) with a '>' followed by the alias. You can do that if you wish, but Confconsole will ignore it and generate it's own alias.

The more advanced features supported when using Aliases with Dehydarated require using it standalone.

Important Note: Please ensure that you have your DNS registrar info correct. Incorrect authentication details will cause the Let's Encrypt challenges to fail (so you won't get a certificate). Repeated failures may cause your server to be blocked (for a week) from further attempts.

Getting a certificate - Behind the scenes

The process goes like this:

• Confconsole Let's Encrypt plugin writes the domain (and subdomains) to /etc/dehydrated/confconsole.domains.txt
• Confconsole calls dehydrated-wrapper
• dehydrated-wrapper stops webserver listening on port 80
• dehydrated-wrapper checks for /etc/dehydrated/confconsole.config (config file); if it doesn't exist, it copies it the default file from: /usr/share/confconsole/letsencrypt/dehydrated-confconsole.config
• dehydrated-wrapper checks for /etc/dehydrated/confconsole.hook.sh (hook script); if it doesn't exist, it copies it the default file from: /usr/share/confconsole/letsencrypt/dehydrated-confconsole.hook.sh
• dehydrated-wrapper checks for /etc/cron.daily/confconsole-dehydrated (cron script); if it doesn't exist, it copies it the default file from: /usr/share/confconsole/letsencrypt/dehydrated-confconsole.cron
• dehydrated-wrapper calls dehydrated, passing confconsole.config, confconsole.hook.sh & confconsole.domains.txt (all stored within /etc/dehydrated/)
• dehydrated contacts Let's Encrypt and gets the challenge (to prove you control the domain)
• Whilst hosting the challenge, add-water temporarily redirects all web traffic except for the challenge (i.e. 304 - temporarily moved) to the web root. A simple "Under Maintence" message is displayed. To provide a custom html page, please see Advanced - custom maintence message below.
• via the hook script, dehydrated serves Let's Encrypt challenges using add-water server (minimalist python webserver)
• when done, add-water is killed (via hook script)
• dehydrated writes certificate to /etc/ssl/private/cert.pem (via hook script); original certs generated by dehydrated remain in /var/lib/dehydrated/certs/DOMAIN
• dehydrated hands back to dehydrated-wrapper
• dehydrated-wrapper restarts webserver
• dehydrated-wrapper restarts stunnel (so Webmin & Webshell also use new cert)
• dehydrated-wrapper hands back to confconsole

Cron job details

The cron job checks the expiry date of the default certificate (/etc/ssl/private/cert.pem) and if it will expire within 30 days or less, it runs dehydrated-wrapper (using the --force switch).

Advanced - custom maintence message

As noted, whilst it is serving the challenges, add-water will redirect all other urls to the web root. By default it will display a simple "Maintenance" message via a basic index.html file.

If you wish to display a custom message, then you can add a custom index.html file to /var/lib/confconsole/letsencrypt/. E.g. to copy across the default and then tweak it:

mkdir -p /var/lib/confconsole/letsencrypt/
cp /usr/share/confconsole/letsencrypt/index.html \
  /var/lib/confconsole/letsencrypt/index.html

add-water will serve /var/lib/confconsole/letsencrypt/index.html if it exists, or otherwise will fall back to the default.

Note: The custom file must be named index.html and contain only valid HTML (and CSS). PHP or other server side languages are not supported. Embedded (i.e. "inline") JavaScript is also supported as that is processed client side.

Advanced - usage with multiple domain names

The interactive Confconsole plugin only supports a single domain with up to 4 subdomains. However, the dehydrated-wrapper can handle multiple root domains, plus multiple subdomains. To support that you will need to manually make configuration adjustments in a number of places:

• add additional domains to /etc/dehydrated/confconsole.domains.txt
  • ensure that each line starts with the base domain, followed by a space separated list of any subdomains.
  • WARNING: If you re-run confconsole's Let's Encrypt plugin, your custom additional domains will be removed!
• adjust your webserver virtual hosts to use the relevant certificates in /var/lib/dehydrated/certs/DOMAIN. Each domain will have it's own subdirectory under /var/lib/dehydrated/certs/.
• By default, the last domain (and any subdomains) configured, will be the one which will work for Webmin & Webshell (and Adminer, if it's included). To change this behaviour, you can adjust the hook script, or simply rearange the order of your domains and put the one you want Webmin & Webshell available from, last.
• Note: the cron job only checks the expiry of /etc/ssl/private/cert.pem. So if you adjust the hook script to no longer update /etc/ssl/private/cert.pem, you will also need to adjust the cron job to check the expiry of a certificate you are updating. Failure to do so will result in daily certificate updates, which may get your server temporarily blocked from accessing the Let's Encrypt servers.