Setting up SSL: Ubuntu and Apache 2
This document requires that you've got a signed server.crt and a server.key file available. You may have justgone through my page Creating Certificate Authorities and self-signed SSL certificates.If not, go there first and follow the instructions.
The remaining steps involve Apache and other tweaks detailed step-by-step below. This file was originallywritten for Ubuntu 6.06, but has been kept current and verified with 10.04 Lucid Lynx. It should work withmost/all releases in between -- and probably Debian-based distros in general, with little or no modification.
(1) Preliminaries and Packages.
If you have a registered DNS name, be sure that you properly set it up. On the Gnome console:System->Administration->Networking:General. Your host/domain name here should match the one you'llbe using in later steps. You can also edit /etc/hosts directly if you're comfortable with that route.
If you haven't done so already, use apt-get, Synaptic or some other tool toget and install Apache 2. I prefer apache2-mpm-prefork. You should also have openssl by this point.
(2) Copy the server.crt and server.key files into position.
This step suggests putting certificate-related files in this location: /etc/apache2/ssl. If the"ssl" directory doesn't already exist there, go ahead and mkdir it now.
Then copy the server.key and server.crt files into position:
cp server.key /etc/apache2/ssl
cp server.crt /etc/apache2/ssl
(3) Enable ssl.
You'll want to run the /usr/sbin/a2enmod script. If you look at this script, it's simply ageneral purpose utility to establish a symlink between a module in/etc/apache2/mods-available to /etc/apache2/mods-enabled (or give a message to theeffect that a given module doesn't exist or that it's already symlinked for loading).
a2enmod ssl
(4) Create a stub SSL conf. file (if needed) and establish a necessary symlink.
NOTE. Ubuntu 10.04 already ships with a stub SSL conf file(/etc/apache2/sites-available/default-ssl), so you won't need to copy the 'default'conf as a stub for the 'default-ssl' conf -- but you will STILL need a symlink between it and thesites-enabled directory.
So if using an Ubuntu prior to ~10.04:
cp /etc/apache2/sites-available/default /etc/apache2/sites-available/default-ssl
For all versions of Ubuntu:
Next, establish a symlink from the 'available' default-ssl file to the 'enabled' file. The symlinking methodology between those two directories is similar in philosophy to mods-available and mods-enabled (previous step). The general idea is that enabled files exist as symlinks created to their available counterparts. Ubuntu prefixes '000-' in frontof the default file, so we may as well keep the same convention with default-ssl:
ln -s /etc/apache2/sites-available/default-ssl /etc/apache2/sites-enabled/000-default-ssl
(5) Set up the document roots.
The default location for HTML pages with an initial install of Ubuntu is/var/www and there exists no separate place for ssl files. I prefer toserve up basic HTML pages in /var/www/html and SSL pages in /var/www-ssl/html.Whatever works for you. But at this point I create the directories.
cd /var/www
mkdir html
cd /var
mkdir www-ssl
cd www-ssl
mkdir html
(6) Configure virtual hosts.
su to the superuser and make a backup of the original Apache configuration file.Call it whatever you want. My practice is to add "_original" to any default configurationfile before I make changes -- in case I need to revert. You should not make a backup of the followingfile in the sites-enabled directory, since both the original and backup will be loaded when you restartApache. Also note that a symlink exists from /etc/apache2/sites-enabled/000-default to/etc/apache2/sites-available/default. Back it up in the sites-available directory or some other location outsideof Apache altogether.
sudo su
cd /etc/apache2/sites-available
cp /etc/apache2/sites-available/default default_original
(Note: If using Ubuntu 10.04+ you may want to backup the original SSL conf also):
cp /etc/apache2/sites-available/default-ssl default-ssl_original
Now you need to declare the IP of your box (or FQDN/DNS name) and document roots you created in a previous step.
To configure HTTP over port 80 (edit /etc/apache2/sites-available/default):
NameVirtualHost *:80
(Note: Look down just a bit and make a change to the virtual host settings.)
<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html/
(Note: Use your assigned IP or DNS name followed with ":80" if you have one for ServerName).
Similar procedure for HTTPS over port 443 (edit /etc/apache2/sites-available/default-ssl):
NameVirtualHost *:443
(Note: Look down just a bit and make a change to the virtual host settings.)
<VirtualHost *:443>
ServerName localhost
DocumentRoot /var/www-ssl/html/
(Note: Again, use your assigned IP or a DNS name followed with ":443" if you have one for ServerName.)
(7) Instruct Apache to listen to 443.
Go to this file /etc/apache2/ports.conf and add the following to it:
Listen 443
I noted that starting with Ubuntu 7.10 (or thereabouts), the ports.conf may already have an IfModule clause in it for the SSL portion. If you see this, you can just leave it as-is:
<IfModule mod_ssl.c> Listen 443</IfModule>
(8) Turn on the SSL engine.
Make sure the following are in your default-ssl file. The SSLengine should be on, and thecert and key should be properly pathed:
SSLEngine On
SSLCertificateFile /etc/apache2/ssl/server.crt
SSLCertificateKeyFile /etc/apache2/ssl/server.key
(9) Make an /etc/hosts tweak (if need be) -- and restart apache.
When starting and stopping Apache there may be a complaint such as "Could not determine the server's fully qualifieddomain name, using 127.0.1.1 for ServerName". You may encounter this if you don't have a DNS name for your server, andare just using an IP. If this applies to you, go into your /etc/hosts file and make the following changes.Basically, we'll be adding "localhost.localdomain" to the 127.0.0.1 IP and whatever system name you chose when youinstalled Ubuntu (assuming you've not changed it). The final line below should be there if you have a static IP, andcorresponding DNS name registered to it. If this is the case, earlier steps that wanted ServerName should have a valuewhich corresponds to the DNS name also indicated here.
127.0.0.1 localhost localhost.localdomain {your system name}
127.0.1.1 {your system name}
{static IP if you you have one} {fully qualified DNS host name if you have one}
It may be that I first noticed additional behavior with Ubuntu 8.04 Hardy Heron. Ifyou don't have a fully qualified domain name (FQDN) for your box, you may need to makean additional tweak. In your /etc/apache2/apache2.conf file, you may want to add the followingline at the very end of the file if Apache is still complaining about lacking a fullyqualified domain name at startup:
ServerName localhost
Restart Apache.
cd /etc/init.d
./apache2 restart
Done -- test it out!
This document requires that you've got a signed server.crt and a server.key file available. You may have justgone through my page Creating Certificate Authorities and self-signed SSL certificates.If not, go there first and follow the instructions.
The remaining steps involve Apache and other tweaks detailed step-by-step below. This file was originallywritten for Ubuntu 6.06, but has been kept current and verified with 10.04 Lucid Lynx. It should work withmost/all releases in between -- and probably Debian-based distros in general, with little or no modification.
(1) Preliminaries and Packages.
If you have a registered DNS name, be sure that you properly set it up. On the Gnome console:System->Administration->Networking:General. Your host/domain name here should match the one you'llbe using in later steps. You can also edit /etc/hosts directly if you're comfortable with that route.
If you haven't done so already, use apt-get, Synaptic or some other tool toget and install Apache 2. I prefer apache2-mpm-prefork. You should also have openssl by this point.
(2) Copy the server.crt and server.key files into position.
This step suggests putting certificate-related files in this location: /etc/apache2/ssl. If the"ssl" directory doesn't already exist there, go ahead and mkdir it now.
Then copy the server.key and server.crt files into position:
cp server.key /etc/apache2/ssl
cp server.crt /etc/apache2/ssl
(3) Enable ssl.
You'll want to run the /usr/sbin/a2enmod script. If you look at this script, it's simply ageneral purpose utility to establish a symlink between a module in/etc/apache2/mods-available to /etc/apache2/mods-enabled (or give a message to theeffect that a given module doesn't exist or that it's already symlinked for loading).
a2enmod ssl
(4) Create a stub SSL conf. file (if needed) and establish a necessary symlink.
NOTE. Ubuntu 10.04 already ships with a stub SSL conf file(/etc/apache2/sites-available/default-ssl), so you won't need to copy the 'default'conf as a stub for the 'default-ssl' conf -- but you will STILL need a symlink between it and thesites-enabled directory.
So if using an Ubuntu prior to ~10.04:
cp /etc/apache2/sites-available/default /etc/apache2/sites-available/default-ssl
For all versions of Ubuntu:
Next, establish a symlink from the 'available' default-ssl file to the 'enabled' file. The symlinking methodology between those two directories is similar in philosophy to mods-available and mods-enabled (previous step). The general idea is that enabled files exist as symlinks created to their available counterparts. Ubuntu prefixes '000-' in frontof the default file, so we may as well keep the same convention with default-ssl:
ln -s /etc/apache2/sites-available/default-ssl /etc/apache2/sites-enabled/000-default-ssl
(5) Set up the document roots.
The default location for HTML pages with an initial install of Ubuntu is/var/www and there exists no separate place for ssl files. I prefer toserve up basic HTML pages in /var/www/html and SSL pages in /var/www-ssl/html.Whatever works for you. But at this point I create the directories.
cd /var/www
mkdir html
cd /var
mkdir www-ssl
cd www-ssl
mkdir html
(6) Configure virtual hosts.
su to the superuser and make a backup of the original Apache configuration file.Call it whatever you want. My practice is to add "_original" to any default configurationfile before I make changes -- in case I need to revert. You should not make a backup of the followingfile in the sites-enabled directory, since both the original and backup will be loaded when you restartApache. Also note that a symlink exists from /etc/apache2/sites-enabled/000-default to/etc/apache2/sites-available/default. Back it up in the sites-available directory or some other location outsideof Apache altogether.
sudo su
cd /etc/apache2/sites-available
cp /etc/apache2/sites-available/default default_original
(Note: If using Ubuntu 10.04+ you may want to backup the original SSL conf also):
cp /etc/apache2/sites-available/default-ssl default-ssl_original
Now you need to declare the IP of your box (or FQDN/DNS name) and document roots you created in a previous step.
To configure HTTP over port 80 (edit /etc/apache2/sites-available/default):
NameVirtualHost *:80
(Note: Look down just a bit and make a change to the virtual host settings.)
<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html/
(Note: Use your assigned IP or DNS name followed with ":80" if you have one for ServerName).
Similar procedure for HTTPS over port 443 (edit /etc/apache2/sites-available/default-ssl):
NameVirtualHost *:443
(Note: Look down just a bit and make a change to the virtual host settings.)
<VirtualHost *:443>
ServerName localhost
DocumentRoot /var/www-ssl/html/
(Note: Again, use your assigned IP or a DNS name followed with ":443" if you have one for ServerName.)
(7) Instruct Apache to listen to 443.
Go to this file /etc/apache2/ports.conf and add the following to it:
Listen 443
I noted that starting with Ubuntu 7.10 (or thereabouts), the ports.conf may already have an IfModule clause in it for the SSL portion. If you see this, you can just leave it as-is:
<IfModule mod_ssl.c> Listen 443</IfModule>
(8) Turn on the SSL engine.
Make sure the following are in your default-ssl file. The SSLengine should be on, and thecert and key should be properly pathed:
SSLEngine On
SSLCertificateFile /etc/apache2/ssl/server.crt
SSLCertificateKeyFile /etc/apache2/ssl/server.key
(9) Make an /etc/hosts tweak (if need be) -- and restart apache.
When starting and stopping Apache there may be a complaint such as "Could not determine the server's fully qualifieddomain name, using 127.0.1.1 for ServerName". You may encounter this if you don't have a DNS name for your server, andare just using an IP. If this applies to you, go into your /etc/hosts file and make the following changes.Basically, we'll be adding "localhost.localdomain" to the 127.0.0.1 IP and whatever system name you chose when youinstalled Ubuntu (assuming you've not changed it). The final line below should be there if you have a static IP, andcorresponding DNS name registered to it. If this is the case, earlier steps that wanted ServerName should have a valuewhich corresponds to the DNS name also indicated here.
127.0.0.1 localhost localhost.localdomain {your system name}
127.0.1.1 {your system name}
{static IP if you you have one} {fully qualified DNS host name if you have one}
It may be that I first noticed additional behavior with Ubuntu 8.04 Hardy Heron. Ifyou don't have a fully qualified domain name (FQDN) for your box, you may need to makean additional tweak. In your /etc/apache2/apache2.conf file, you may want to add the followingline at the very end of the file if Apache is still complaining about lacking a fullyqualified domain name at startup:
ServerName localhost
Restart Apache.
cd /etc/init.d
./apache2 restart
Done -- test it out!
No comments:
Post a Comment