Pylons

Name	Space	Section	Version	Status	Reviewed	Author(s)
Setting up Apache and SSL for Pylons	Pylons Cookbook	Deployment	1.0	Draft	False	James Gardner

Introduction

If you are using Pylons with Apache using one of the many deployment methods you might also want to setup SSL to have the Pylons application secure. This is actually very easy if you use Apache to handle the SSL part.

There is a good description of how to setup Apache and HTTPS as part of the Ubuntu Server Documentation although the details of my vary slightly for other platforms.

Generating a Certificate Signing Request

To generate the Certificate Signing Request you should create your own key. You can run the following command from a terminal prompt to create the key:

openssl genrsa -des3 -out server.key 1024

You will need to install the packages for openssl if they are not already installed. Using the command above will create a key which uses a password. The minimum length when specifying -des3 is four characters. It should include numbers and/or punctuation and not be a word in a dictionary. Also remember that your passphrase is case-sensitive.

Re-type the passphrase to verify. Once you have re-typed it correctly, the server key is generated and stored in server.key file. Using a key with a passphrase like this can be inconvenient because every time you restart apache the passphrase has to be manually entered so if you server were to be rebooted, Apache would not start without manual intervention.

You can also run your secure web server without a passphrase but it is highly insecure and a compromise of the key means a compromise of the server as well. You can generate a key without a passphrease by leaving out the -des3 switch in the generation phase or by issuing the following command at a terminal prompt to convert your existing key.

openssl rsa -in server.key -out server.key.insecure

Once you have the key (with the passphrase or without) you need to generate the certificate signing request.

openssl req -new -key server.key -out server.csr

You will be prompted for Company Name, Site Name, Email Id, etc The details you enter here will form part of the certificate. It is important that the Common Name you enter (CN) matches the domain name the secure certificate is for otherwise the certificate won't work.

Now you have your certificate signing request you can either generate a self-signed certificate or purchase a signed certificate from a Certificate Authority. If you choose to sign the certificate yourself your users will be prompted by their web browser each time they visit the site because the browser will not recognise the certificate. As a rule production sites should not use self-signed certificates.

To sign the certificate yourself issue this command:

openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

We will use the key and certificate when setting up Apache.

Setting Up Apache

You also need to install mod_ssl, enable it and reload Apache: 

sudo apt-get install apache2-common
sudo a2enmod ssl
sudo /etc/init.d/apache2 force-reload

Then you need to get Apache to listen on port 443 by adding this to /etc/apache2/ports.conf

Listen 443

Now modify the virtual host entry to add the SSL options under the DocumentRoot line. You will need to adjust the paths to point to wherever you wish to keep the key and certificate and you should ensure Apache has access to read them.

The SSLOptions are described in the mod_ssl documentation so you should chose the options best suited to you.

You can also setup a 80 host too if you like by adding an identical entry but without the SSL options and with *:80 rather than *:443 specified. You shouldn't specify the domain name in the virtual host directive itself but by using the ServerName option. You'll add these entries too just before your virtual host entries:

ServerName your.domain.name
NameVirtualHost *:80
NameVirtualHost *:443

Note that whilst you can have multiple virtual hosts on http, only one virtual host per IP address can use SSL. This is because the SSL protocol does not support virtual hosts.

Finally restart Apache and you should find you can access your Pylons application from https:// as well as http://.

sudo /etc/init.d/apache2 restart

Setting Up Pylons

Once Apache is setup you should find that the HTTPS requests are correctly sent to Pylons and that routes correctly generates URLs starting https://. You shouldn't need to make any other modifications. 

Debugging

If you are using Firefox and simply get an Error message alert when you try to use the HTTPS version of your site it is likely you have made an error in creating your certificate. Check
that the Common Name you specified when creating the certificate signing request matches the domain name you are using.

If you need to perform further debugging these commands might be useful: 

netstat -ta
openssl s_client -connect localhost:443 -state -debug

You should also check the main Apache error logs for clues as well as your virtual host's error log:

tail /var/log/apache2/error.log