Revision of Using SSL from Mon, 08/01/2011 - 01:22

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). Note: you may also have to add an IP address to the IP addresses field.
5. 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
6. If all goes well you will see the following changes in your Aegir file system structure: a) under /var/aegir/config you will see a new directory ssl.d b) under /var/aegir/config/server_master you will see a similar new directory ssl.d

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/site-1.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/site-1.com).
5. If all goes well the VirtualHost directive will now have these important elements:

Now, when you navigate to https://site-1.com you should see that your site is SSL enabled.

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 both /var/aegir/config/ssl.d and /var/aegir/config/server_master/ssl.d. With this step, you have created a self-signed certificate, and your site is now configured to use it. To use a commercial certificate, however, you need to delete all files created (including any _receipt files) while leaving the directory structure intact.
2. Create Certificate Signing Request (.csr file). Using a tool like https://www.digicert.com/easy-csr/openssl.htm, create the following code:
   openssl req -new -newkey rsa:2048 -nodes -out site-1_com.csr -keyout site-1_com.key -subj "/C=us/ST=Your State/L=Your City/O=Your Organization Inc./CN=site-1.com"
   Paste this code (modify it if not using tool) into your /var/aegir/config/server_master/ssl.d/site-1.com directory. It will generate a .csr and a .key file. Transfer the two files created to a temporary directory on your PC and delete the files from the server (will be transferred back from your PC later).
3. Copy and paste the .csr file into the form for the issuing authority (GoDaddy to create Starfield Technologies certificates, for example) 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. In total, you will have four files: one .csr file, one .key file, and the two .crt files. One of the .crt files will be an sf_bundle file which will need special consideration (see below).
5. Transfer all the files to /var/aegir/config/ssl.d/site-1.com and /var/aegir/config/server_master/ssl.d/site-1.com (the directories should be empty). Rename the site .crt and .key files to openssl.crt and openssl.key in both directories; you need not rename the sf_bundle.crt file. You should have four files in each directory (openssl.crt, openssl.key, site-1_com.csr, and sr_bundle.crt).

IMPORTANT: Do not verify your site until you complete the next step! Whenever you reverify your site, your vhost file is automatically regenerated by Aegir and any non-Aegir generated certificate information will be replaced in the vhost file. Your commercial certificate will not work without referencing the sf_bindled.crt file in your vhost file!

Create file to insert additional configuration in your vhost file for this site.

1. Create a file in /var/aegir/.drush and include the following:
   <?php
  function sitename_provision_apache_vhost_config($uri, $data) {
    return "SSLCertificateChainFile /var/aegir/config/server_master/ssl.d/" . $uri . "/sf_bundle.crt";
  }
?>
2. Save the file as sitename.drush.inc

Now, when aegir verifies your site, you changes to the vhost file will remain intact, and the correct SSLCertificateChainFile will be inserted.

For more information on this technique, see http://community.aegirproject.org/node/70

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.