SSL Configuration Reference

From Sympl Wiki
Jump to navigation Jump to search

Secure Sockets Layer (SSL) is a system used to encrypt communication between two machines on a network, which uses public and private key encryption, with certificates signed by trusted parties, and is used by a huge range of services.

Sympl manages your SSL certificates for you, and by default will attempt to retrieve a free Let's Encrypt certificate for each of your configured websites and apply them the website and email for the domain.

While SSL and it's protocols has effectively been replaced by Transport Layer Security (TLS), it is still common to refer to the certificates and systems as 'SSL'.

SSL Providers

Until a few years ago, having a certificate signed by a trusted authority involved a number of manual identity checks and a fee to the certificate signer. These authorities include Comodo, Digicert and GlobalSign, among others.

At the end of 2015 a new free, automated, certificate signing service appeared in the form of Let's Encrypt, which is supported by a large number of tech companies including Mozilla, Google, Facebook and Cisco, and after only a few years is now used on a large range of sites.

Sympl will attempt to retrieve a Let's Encrypt certificate automatically, however it can also generate a 'self-signed' certificate for situations when it's not possible to retrieve one for the relevant domain from Let's Encrypt.

SSL Provider Configuration

Sympl has the concept of 'providers' when generating SSL certificates, keys and requests, and currently directly supports only two providers at present.

The file /srv/ controls if :

If .../config/ssl-provider Then
Contains letsencrypt A Let's Encrypt certificate will be retrieved.
Does not exist
Contains selfsigned A Self-Signed certificate will be generated.
Contains false Automatic certificate generation will be disabled for the domain.
Is Empty
Contains any other content

Managing Certificates with sympl-ssl

Sympl uses the tool sympl-ssl to manage domain certificates. It runs daily overnight, and will attempt to retrieve new Let's Encrypt and Self-Signed certificates where missing, and will automatically attempt to renew any which are expiring.

It can also be used to report on certificate status:

sympl@sympl:~$ sudo sympl-ssl --verbose
* Examining certificates for
	Current SSL set 0: self-signed for /, expires 2020-07-09 16:14:09 UTC
* Examining certificates for
	Current SSL set 1: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-06 16:43:35 UTC
* Examining certificates for
	Current SSL set 1: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-06 16:43:35 UTC
* Examining certificates for
	Current SSL set 4: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-09-09 16:49:41 UTC
* Examining certificates for
	Current SSL set 2: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-10 08:06:09 UTC

The example above shows the current certificate for each domain. These are 'sets', which are made up of a number of files stored in /srv/<set_number>/, and The currently active set is symlinked as /srv/

Filename Contents Description
ssl.crt The SSL certificate itself.
ssl.key The private key for the certificate.
ssl.bundle Intermediate Certification Authority (CA) certificate bundle.
ssl.combined Combined certificate, bundle (if available) and key, in that order.
ssl.csr A Certificate Signing Request.

Let's Encrypt Certificates

This article is a Stub. You can help the Sympl Project by expanding it.
  • Let's Encrypt certificates are retrieved automatically overnight, based on what domains are configured.
  • Authenticating ownership of the domain requires the server to be serving the website.
  • Certificate retrieval can be trigged manually with sudo sympl-ssl --verbose
  • Issued certificates last for 90 days, and are automatically renewed when there are fewer than 30 days until expiry.
  • Sympl uses the ACMEv02 endpoint with Let's Encrypt, but does not currently support retrieval of wildcard certificates.

Third Party Certificates

Sympl fully supports third party certificates, however due to the range of providers, certificate types, different processes and methods used, it's not possible to automatically generate the required files needed to support all providers.

Getting a New Third Party Certificate

If you want to swap to a purchased certificate, rather than using Let's Encrypt, you will likely need a Certificate Signing Request (.csr) file along with a new Private Key. The requirements for these can vary from provider to provider.

You can generate a CSR and save the keys to your home directory with:

openssl req -new -newkey rsa:2048 -nodes -keyout ~/ -out ~/

You will then be prompted for a number of pieces of information:

Prompt Information to Enter
Country Name The two-letter ISO format country code for where your organization is registered. Note that for the UK it is 'GB'.
State or Province Name The full name of the county/state/province where your organization is registered.
Localitiy Name The full name of the city where your organization is registered.
Organization Name The full registered name of your business, or or the name of the requestor if an individual.
Organization Unit Name The 'Doing Business As' name, if applicable.
Common Name The fully qualified domain name, such as If you're requesting a wildcard certificate, use *
Email Address An administrative email address on the domain which can accept mail. Check with the Certificate Authority as to what they will accept before generating the certificate.
Challenge Password Do not specify a password (leave blank). Note that you should still keep the generated .key file in a safe place.

If you want to request a certificate with multiple domains or subdomains (other than www., which is usually added automatically), please check with the Certificate Authority for instructions on generating the CSR.

You can check the .csr file with the command openssl req -in ~/ -text -noout.

Once you have the .csr file, you can provide that to the Certificate Authority, and they will provide you with a signed certificate and usually file containing the intermediate certificates.

Installing a Third Party Certificate

Once you have the certificate, key and intermediate certificate, you should disable automatic certificate provisioning and create a new sets directory in /srv/ Note that you can use any name for the set, but in this case we are using manual.

echo 'false' > /srv/
mkdir -p /srv/

Copy the files into /srv/ . You will probably need to rename the files as shown above, and likely combine the cert, bundle and key into the ssl.combined file. You can do that with:

cd /srv/
cat ssl.crt ssl.bundle ssl.key > ss.combined

Once that has been done, you can swap to the new certificate set with:

sudo sympl-ssl --verbose --select manual

SSL Hooks

There are a number of automatic hook scripts which are run once sympl-ssl completes, designed to update the relevant services or configs when SSL certificates have changed.

These are run from /etc/sympl/ssl-hooks.d/, must be executable, and will be passed live-update as the first parameter, with following parameters being the domains which have been changed.

Configuration Reference

File or Directory Used For
.../config/ssl-provider Selects the automatic SSL provider to use, or disables automatic SSL generation. More...
.../config/ssl/ Directory for the SSL certificates and configuration. Permissions are secured with sympl-filesystem-security. More...
.../config/ssl/current/ A symbolic link which points toward the currently active certificate set directory. More...
.../config/ssl/set_id/ A directory containing the SSL files for the set set_id. More...
.../config/ssl/set_id/ssl.crt The SSL certificate in X.509 format. More...
.../config/ssl/set_id/ssl.key The SSL key in X.509 format. More...
.../config/ssl/set_id/ssl.bundle The SSL intermediate certificate in X.509 format. More...
.../config/ssl/set_id/ssl.combined A combination of ssl.crt, ssl.bundle and ssl.key, in that order. More...
.../config/ssl/set_id/ssl.csr The Certificate Signing Request. file in X.509 format. More...
.../config/ssl/letsencrypt/email Email address for Let's Encrypt registration and notices. This defaults to root@your-server-hostname so may need to be changed from the default if your server does not have a publicly visible name. More...
.../config/ssl/letsencrypt/rsa_key_size The size in bits of the public RSA key generated for the SSL certificate. Defaults to 2048. More...
.../config/ssl/letsencrypt/endpoint The Let's Encrypt API endpoint to use. Defaults to More...
.../config/ssl/letsencrypt/docroot The document root for the domain, used to confirm ownership. Defaults to /srv/ More...
.../config/ssl/letsencrypt/account_key The private RSA key for this Let's Encrypt account. Generated automatically if not present. More...
.../config/ssl/selfsigned/rsa_key_size The size in bits of the public RSA key generated for the SSL certificate. Defaults to 2048. More...
.../config/ssl/selfsigned/lifetime The length in days the certificate should be valid for. Defaults to 365. More...

See also Configuration Reference for other configuration files.