Upgrading to Apache 2

92

Author: Tom Haddon

Apache 2 offers a number of new features and improvements over the Apache 1.3 series, but the upgrade can seem daunting to those who haven’t had much (or any) experience with Apache 2. I recently had to go through an upgrade from Apache 1.3 to Apache 2.0 on Debian Sarge, and it’s not as difficult as you might think.

Despite some differences in the configurations of the two versions of Apache, the upgrade can be a surprisingly smooth process if you plan well. This assumes that you already have Apache 1.3 installed on Debian Sarge, have root access to the server, and have one or more sites configured as virtual hosts in your /etc/apache/httpd.conf file.

The first step is to install the Debian packages for Apache 2. Be sure that you’ve run apt-get update to update the list of packages. Next, you’ll want to install the actual Apache 2 packages using apt-get install apache2 apache2-common, which will install the Apache server and support packages. If you receive a “Couldn’t find package apache2” error, or similar, check your package resource list (/etc/apt/sources.list) to make sure that your list of package archives is correct.

You may also want to install some additional packages, such as libapache2-mod-php4 for PHP 4 support, or libapache2-mod-python for Mod_python. You can either append those to your original apt-get install command (don’t forget to use spaces as separators), or run separate apt-get install commands after the first.

Now Apache 2 is installed, but you can’t start it in the default configuration because it’s using the same port as Apache 1.3. If you try, you should receive a message that says a service is already running on port 80. Since Apache is already running on port 80, apt, Debian’s package
installer, will disable Apache 2 by default by setting NO_START=1 in the configuration file /etc/default/apache2. To change this, edit /etc/apache2/ports.conf to change the port that Apache 2 will monitor for requests. Change Listen 80 to Listen 8080, or whatever port you want to use for testing purposes, as long as it doesn’t conflict with another service. Then you can change the NO_START entry in /etc/default/apache2 to 0, and run /etc/init.d/apache2 start to start your shiny new Apache 2 Web server.

The next step is to configure your virtual hosts. The configuration file layout is different between Apache 1.3 and Apache 2.0 on Debian. While Apache 1.3 typically has all of its virtual hosts information in the /etc/apache/httpd.conf file, Apache 2.0 is set up to look for virtual host configurations in the /etc/apache2/sites-enabled directory.

Say, for instance, that your /etc/apache/httpd.conf virtual hosts section looks like this:


# Named VirtualHosts
NameVirtualHost *
<VirtualHost *>

ServerName incorrect.com
DocumentRoot /var/www/html/default
</VirtualHost>

<VirtualHost *>
ServerName www.example.com
ServerAlias example.com
DocumentRoot /var/www/html/example.com/html
CustomLog logs/www.example.com-access_log common

</VirtualHost>

This could translate in Apache 2 into one or more separate configuration files under /etc/apache2/sites-enabled. While you can keep all of your virtual host entries in one configuration file, it’s usually best to split them into separate configuration files for each host.

With Apache 1.3, the first entry of your VirtualHosts section serves as your “default” site — in other words, if someone comes to a site that’s not configured in your VirtualHosts section correctly, but is specified in public DNS as your server’s IP address, he will be sent to the default Web site.

With Apache 2.0, the default site is instead the first file (in alphabetical order) in the /etc/apache2/sites-enabled directory. After initial installation, there will be a symlink from 000-default in this directory to /etc/apache2/sites-available/default. As you can see from this, Apache 2.0 offers another level of abstraction in virtual hosts by recommending putting the actual files in /etc/apache2/sites-available and then symlinking from there to /etc/apache2/sites-enabled.

I recommend following this convention. It makes it much easier to manage when there are a large number of virtual hosts on a server. In the example above, you would create two files, /etc/apache2/sites-available/default and etc/apache2/sites-available/example.com. The /etc/apache2/sites-available/default file would look like this:


NameVirtualHost *
<VirtualHost *>
ServerName incorrect.com
DocumentRoot /var/www/html/default
</VirtualHost>

And the /etc/apache2/sites-available/example.com would look like this:


<VirtualHost *>
ServerName www.example.com
ServerAlias example.com
DocumentRoot /var/www/html/example.com/html
CustomLog logs/www.example.com-access_log common
</VirtualHost>

Then, create symlinks to the files in the /etc/apache2/sites-enabled directory with the ln -s command: ln -s /etc/apache2/sites-available/example.com /etc/apache2/sites-enabled/example.com.

Now that you have the virtual hosts configured, it’s time to test. To start Apache 2, type /etc/init.d/apache2 start. Fire up a browser and head to www.example.com:8080. Obviously, this will only work assuming you have a correct virtual host entry for a hostname which has DNS pointing to your server rather than www.example.com. Alternatively, you can add an entry in the /etc/hosts file on the machine that you’re browsing from to fool it into thinking it should be going to the IP address of your server.

If Apache 2 didn’t start correctly, you may see errors when running /etc/init.d/apache2 start, and you will need to resolve some issues before you can proceed. Check the /var/log/apache2/error.log for details on any problems.

In my case, I have a number of sites running PHP with PostgreSQL or MySQL database backends, as well as a Zope/Plone instance that’s being served from Apache using mod_rewrite. As a result, I had to install the libapache2-mod-php4 and libapache2-mod-proxy-html packages. In addition, I had to copy my existing php.ini file (/etc/php4/apache/php.ini) to /etc/php4/apache2/php.ini to make sure all my PHP settings were preserved. I also had to create symlinks from /etc/apache2/mods-available/proxy.load and rewrite.load to the /etc/apache2/mods-enabled directory. Once again, Apache 2 is modularizing its configuration layout.

My final step to resolve Apache 2 startup issues was to symlink /etc/apache/logs to /etc/apache2/logs, as that was my log file directory.

Assuming your testing has gone well, you’re now ready to migrate to Apache 2.0! Stop Apache 2 if it’s running by using the command /etc/init.d/apache2 stop, and change the /etc/apache2/ports.conf to use port 80. Stop Apache 1.3 with /etc/init.d/apache stop, and then fire up Apache 2 with /etc/init.d/apache2 start. You’re done — almost.

The final cleanup steps include making sure Apache 2 will start when the server is rebooted, and making sure Apache 1.3 won’t. There are a few ways to remove Apache 1.3 from the services that start on boot. One is to remove the symlinks for Apache in the /etc/rc*.d directories. Another is to use the sysv-rc-conf run-level configuration editor. This is not installed on Debian systems by default, but can be installed using apt-get install sysv-rc-conf.

You may also want to verify that a start link (like “S91apache2”) is in the /etc/rc2.d directory and symlinked to /etc/init.d/apache2. This will ensure Apache 2 is started on reboot, and should have been configured when the package was installed. On my system, I also needed to restart Zope for the mod_rewrite module to work correctly.

That’s all there is to it. Congratulations, and welcome to the world of Apache 2.0!