Using SSL

Introduction

SSL support was significantly improved in Aegir 0.4 alpha9 and subsequent releases have further refined the SSL functionality. Here are the current steps to configure SSL support in Aegir and apply it to your web sites.

Prepare Your Server

1. Make sure port 443 is open for SSL traffic.
2. From the command line, install SSL software for your web server (e.g. on Debian/Ubuntu you can use sudo apt-get install openssl).
3. Enable SSL support (e.g. sudo a2enmod ssl). You will need to restart Apache at this point.

Enable SSL Support in Aegir

1. You have to enable SSL support in Aegir as it is off by default. Assuming the URL of your Aegir front end is aegir.example.com, browse to aegir.example.com/admin/hosting/features
2. Click on Experimental to reveal experimental features
3. Check SSL support
4. Click Save configuration

Configure Your Aegir Server

1. Click on the Servers tab
2. Click on the server that you wish to enable SSL support
3. Click Edit to change the server configuration
4. Click apache_ssl (this will reveal an additional field: SSL port, which should be already populated with 443).
5. You may also have to add an IP address to the IP addresses field. The field is used as an "IP pool" for SSL certificates: IPs are assigned to SSL sites when they are created on a first come, first served basis. (Note that there are known issues with this process, see issue #1126640 for details.)
6. Click Save - this will start various tasks beginning with a verify task on the server followed by verify tasks on all platforms that are associated with that server
7. If all goes well you will see the following changes in your Aegir file system structure: a new /var/aegir/config/ssl.d directory and a new /var/aegir/config/server_master/ssl.d directory.

The /var/aegir/config/ssl.d directory is where you will be able to manipulate SSL keys and certificates, for example by importing commercial SSL certificates or generating a new key. Do not manually edit the /var/aegir/config/server_master/ssl.d directory as changes to that directory will be overwritten when the server or site are verified.

Configure Your Aegir Site

1. You must enable SSL on your sites that are on those platforms associated with the server. Browse to aegir.example.com/hosting/c/example.com
2. Click Edit to change the site configuration
3. Choose the type of Encryption required and the Encryption key (see the explanatory notes below each option). NOTE:, Alternatively, you may specify a directory under /var/aegir/config/server_master/ssl.d where your own certificate and key is to be stored (see Apache notes below).
4. Click Save. Aegir will then generate a certificate and private key for your web site and insert these into a new VirtualHost directive in your vhost file. (This file is typically at /config/server_master/apache/vhost.d/example.com).
5. If all goes well the VirtualHost directive will now have these important elements:

Now, when you navigate to https://example.com you should see that your site is SSL enabled. It will, however, generate warnings in your browsers because it is a self-signed certificates. See below for how to use commercial certificates to remove this warning.

Notes for Apache users with Commercial Certificate File(s)

If you wish to use your own commercial certificate and key you will need to do the following:

1. Follow the directions above, using the "Generate new encryption key" option and using your site's domain name for the "New encryption key". This will create a site directory under /var/aegir/config/ssl.d/example.com. With this step, you have created a self-signed certificate, and your site is now configured to use it.
2. This generated a 2048 bit RSA key for you along with a CSR (Certificate Signing Request). If you prefer to generate your own RSA key, replace the files (openssl.key and openssl.csr) in the /var/aegir/config/ssl.d/example.com directory with your RSA key and associated CSR.
3. Copy and paste the .csr file into the form for the issuing Certificate Authority (CA) to create your certificate.
4. When your certificate has been generated, download the files from the issuing authority and place in your temporary folder on your PC. You may have more than one .crt files, in this case you have a "bundle" or what we call a "certificate chain" that you need to add in aegir (see below).
5. Transfer all the files to /var/aegir/config/ssl.d/example.com. Rename the site .crt file to openssl.crt. If you have a certificate chain, install it in openssl_chain.crt. You should have at least three files in the directory (openssl.crt, openssl.key, openssl.csr, and optionnally openssl_chain.crt).

Verify your site from aegir's frontend.

You should now be able to access your site via https:// using your commercial certificate.

Notes for Nginx users:

It is recommended to allow Aegir to create a default self-signed certificate and key first, and then replace the contents of both files (not the files itself) with your real key and certificate. Any chained certificates (bundles) should be included in the same file, directly below your own certificate - there is no need for extra files/lines like it is for Apache configuration.

Preview	Attachment	Size
	site-ssl-configuration_0.png	26.91 KB