Adding an SSL Certificate

This guide explains how to add an SSL certificate on a Symbiosis server. Cloud servers running other OSs have SSL Certificates included as standard through Let’s Encrypt.

By default, Symbiosis uses the default certificate for the hostname of the server for email and FTP connections. This is usually a self-signed certificate which is generated when the server is initially set up, so it will likely be for the hostname, which can look a little untidy (and be fairly long to type).

Using a Let’s Encrypt certificate for email & FTP

As an alternative, you can use a Let’s Encrypt certificate from one of the sites hosted on the server, allowing you to connect to the mail server on that hostname without receiving certificate warnings.

Things you’ll need

• A basic understanding of the command line and SSH This should be reasonably simple, and is mostly copy and paste over SSH.
• A server running Symbiosis Jessie or newer — Symbiosis Wheezy doesn’t have built in support for Let’s Encrypt, but can do something similar with Let’s Encrypt or other certificates you have set up.
• A domain you control You’ll need to be able to add DNS records, and point them to the server.

Initial setup

First of all, you’ll need to ensure the site with the address (or addresses) you want to use is running on the server with HTTPS. In this example the main website is www.example.com, with the configuration in /srv/example.com on the server. Whatever you plan to use, before continuing you should be able to browse to the domain using HTTPS without any problems.

A note on advanced setup

Before running through this process it is worth mentioning that if you decide to remove the domain or subdomain that holds the certificate that you are linking to, you will need to go through the ‘Undoing the changes‘ section at the bottom of the page before removing the domain. If you remove the domain without going through this process you may render the mail and FTP services unusable.

If you want to, you can set up a subdomain at this point such as mail.example.com, by creating a symlink to the directory in /srv, via something like:

ln -s /srv/example.com /srv/mail.example.com

Symbiosis will then make the website visible on that domain, attempt to handle DNS, and alias everything across, and the next time it retrieves a certificate, it will attempt to get one with all the linked domains as alternate names. You may also want to set up redirects to the main site, but I won’t cover that here.

Also, you could potentially have a separate domain configured in symbiosis this, with sub domains aliased to it for each customer – there are many complex configurations possible, but I’ll just cover the basic one here.

Adjusting the configuration

First of all, log in to the server as the admin user via SSH, then set a quick variable to save typing / copying / editing the domain multiple times. Ensure you edit this to be the domain you want to use!

domain="example.com"

Next we should make a copy of the old certificate links, in case we need to revert the changes (you should be fine to copy and paste from this point.

sudo mkdir /etc/ssl/oldcerts

sudo mv /etc/ssl/ssl.combined /etc/ssl/ssl.crt /etc/ssl/ssl.key /etc/ssl/oldcerts

Then, we create new symlinks to point to the new certificate we want to use.

sudo ln -s /srv/$domain/config/ssl/current/ssl.crt /etc/ssl/ssl.crt
sudo ln -s /srv/$domain/config/ssl/current/ssl.key /etc/ssl/ssl.key
sudo ln -s /srv/$domain/config/ssl/current/ssl.combined /etc/ssl/ssl.combined

We’ll also need to allow TLS sessions if they’re not already allowed.

sudo echo "1" | sudo tee /etc/pure-ftpd/conf/TLS

Finally, we reload Dovecot (POP3 / IMAP mail server) and restart Pure-FTPd (FTP) to swap to the new certificates. (Exim reads the certificates as it needs them, so it doesn’t need to be reloaded.)

sudo service dovecot reload
sudo service pure-ftpd restart

Checking it works

At this point the default certificate being used for FTP and Email purposes should be live. You can check this with the commands:

openssl s_client -connect localhost:465 < /dev/null 2> /dev/null | grep "subject="
openssl s_client -connect localhost:143 -starttls imap < /dev/null 2> /dev/null | grep "subject="
openssl s_client -connect localhost:21 -starttls ftp < /dev/null 2> /dev/null | grep "subject="

Each should respond with the text “subject=/CN=“, followed by one of the domains on the certificate, in this case “subject=/CN=example.com”

At that point, you should be able to connect to any of the services with an FTP or mail client, using one of the domains in the certificate, without any security warning prompts.

Finishing up

Once you have it working, and you’re happy, you’ll need to add a quick scheduled cron job to restart Dovecot and Pure-FTPd periodically, as the Let’s Encrypt certificate will change every few months.

echo -e '#!/bin/bash\nservice dovecot reload > /dev/null\nservice pure-ftpd restart > /dev/null' | sudo tee /etc/cron.daily/reload-dovecot-pureftpd-ssl

And finally, make the new script executable:

sudo chmod 755 /etc/cron.daily/reload-dovecot-pureftpd-ssl

Undoing the changes

In the event you need to undo the changes, it should be fairly simple.

Log in as admin via SSH, and run:

sudo rm /etc/ssl/ssl.combined /etc/ssl/ssl.crt /etc/ssl/ssl.key /etc/cron.daily/reload-dovecot-ssl

sudo mv /etc/ssl/oldcerts/* /etc/ssl

sudo service dovecot reload
sudo service pure-ftpd restart

At which point you should be back to where you were before.