# Apache Migration HOWTO

Abstract

This HOWTO covers the migration of Scientific Linux web servers from Apache 1.3 packages to Apache 2.0 packages. It explains the relevant differences between the 1.3 and 2.0 packages, and describes the process required to migrate your server's configuration from 1.3 to 2.0.

## 1. Naming and filesystem changes

### 1.1. Packaging changes

When using RPM to administer your system you should be aware that some packages have been renamed, some have been incorporated into others, and some have been deprecated. The major changes are that the `apache`, `apache-devel` and `apache-manual` packages have been renamed as `httpd`, `httpd-devel` and `httpd-manual`, and that the `mod_dav` package has been incorporated into the `httpd` package.

A complete breakdown of the packaging changes can be found in Appendix A, Packaging Changes.

### 1.2. Filesystem changes

The single major change to the filesystem layout is that there is now a directory, `/etc/httpd/conf.d`, into which the configuration files for individually packaged modules (`mod_ssl`, `php`, `mod_perl` and so on) are placed. The server is instructed to load configuration files from this location by the directive `Include conf.d/*.conf` within `/etc/httpd/conf/httpd.conf`, so it is vital that this line be inserted when migrating an existing configuration.

Of the many minor changes, the most important to be aware of are that the utility programs ab and logresolve have been moved from `/usr/sbin` to `/usr/bin`, which will cause scripts with absolute paths to these binaries to fail; the dbmmanage command has been replaced by htdbm (see Section 2.4.4, “mod_auth_dbm and mod_auth_db”); the logrotate configuration file has been renamed from `/etc/logrotate.d/apache` to `/etc/logrotate.d/httpd`.

## 2. Migrating your configuration

If you have upgraded your server from a previous version of Scientific Linux upon which Apache was installed then the stock configuration file from the Apache 2.0 package will have been created as `/etc/httpd/conf/httpd.conf.rpmnew`, leaving your original `httpd.conf` untouched. It is, of course, entirely up to you whether you use the new configuration file and migrate your old settings to it, or use your existing file as a base and modify it to suit, however some parts of the file have changed more than others and a mixed approach is generally the best. The stock configuration files for both 1.3 and 2.0 are divided into three sections, and for each of these this document will suggest what is hopefully the easiest route.

If your `httpd.conf` has been modified from the default configuration and you have saved a copy of the original then you may find the diff command comes in handy. Invoked as:

    diff -u httpd.conf.orig httpd.conf | less

for example, it will highlight the modifications you have made. If you do not have a copy of the original file all is not lost, since it is possible to extract it from an RPM package using the rpm2cpio and cpio commands, for example:

    rpm2cpio apache-1.3.23-11.i386.rpm | cpio -i --make

Finally, it is useful to know that Apache has a testing mode to check your configuration for errors. This may be invoked as:

    apachectl configtest

### 2.1. Global Environment

The global environment section of the configuration file contains directives which affect the overall operation of Apache, such as the number of concurrent requests it can handle and the locations of the various files it uses. This section requires a large number of changes compared with the others and it is therefore recommended that you base this section on the Apache 2.0 configuration file and migrate your old settings into it.

#### 2.1.1. Selecting which interfaces and ports to bind to

The `BindAddress` and `Port` directives no longer exist: their functionality is now provided by a more flexible `Listen` directive.

If you had set `Port 80` you should change it to `Listen 80` instead. If you had set `Port` to some other value then you should also append the port number to the contents of your `ServerName` directive:

Example 1. Apache 1.3 port configuration

    Port 123
    ServerName www.example.com

Example 2. Equivalent Apache 2.0 port configuration

    Listen 123
    ServerName www.example.com:123

See also:

- `Listen`
- `ServerName`

#### 2.1.2. Server-pool size regulation

In Apache 2.0, the responsibility for accepting requests and dispatching children to handle them has been abstracted into a group of modules called Multi-Processing Modules (MPMs); the original Apache 1.3 behaviour has now been moved into the prefork MPM.

The MPM used by default on Scientific Linux is prefork which accepts the same directives (`StartServers`, `MinSpareServers`, `MaxSpareServers`, `MaxClients` and `MaxRequestsPerChild`) as Apache 1.3 and as such the values of these directives may be migrated across directly.

An alternative, thread-based MPM called worker is also available; to use this MPM, add the line:

    HTTPD=/usr/sbin/httpd.worker

to the file `/etc/sysconfig/httpd`.

See also:

- Apache Multi-Processing Modules

#### 2.1.3. Dynamic Shared Object (DSO) Support

There are many changes required here and it is highly recommended that anyone trying to modify an Apache 1.3 configuration to suit Apache 2.0 (as opposed to migrating your changes into the Apache 2.0 configuration) simply copy this section from the stock Scientific Linux Apache 2.0 configuration. If you do decide to try and modify your original file, please note that it is of paramount importance that your `httpd.conf` contains the following directive:

    #
    # Load config files from the config directory "/etc/httpd/conf.d".
    #
    Include conf.d/*.conf

Omission of this directive will result in the failure of all modules packaged in their own RPMs (`mod_ssl`, `php`, `mod_perl` and the like).

Those who still don't want to simply copy the section from the stock Apache 2.0 configuration should note the following:

- The `AddModule` and `ClearModuleList` directives no longer exist. These directives where used to ensure that modules could be enabled in the correct order. The new Apache 2.0 API allows modules to explicitly specify their ordering, eliminating the need for these directives.

- The order of the `LoadModule` lines is thus no longer relevant.

- Many modules have been added, removed, renamed, split up, or incorporated with each other.

- `LoadModule` lines for modules packaged in their own RPMs (`mod_ssl`, `php`, `mod_perl` and the like) are no longer necessary as they can be found in the relevant file in the directory `/etc/httpd/conf.d`.

- The various `HAVE_XXX` definitions are no longer defined.

#### 2.1.4. Other changes

The `ServerType` directive has been removed in Apache 2.0 which can only be run as `ServerType standalone`.

The `AccessConfig` and `ResourceConfig` directives have been removed since they mirror the functionality of the `Include` directive. If you have `AccessConfig` and `ResourceConfig` directives set then you need to replace these with `Include` directives. To ensure that the files are read in the order implied by the older directives the `Include` directives should be placed at the end of `httpd.conf`, with the one corresponding to `ResourceConfig` preceding the one corresponding to `AccessConfig`. If you were making use of the default values you will need to include them explicitly as `conf/srm.conf` and `conf/access.conf`.

### 2.2. Main server configuration

The main server configuration section of the configuration file sets up the main server, which responds to any requests that aren't handled by a `<VirtualHost>` definition. Values here also provide defaults for any `<VirtualHost>` containers you may define.

The directives used in this section have changed little between Apache 1.3 and Apache 2.0, so if your main server configuration is heavily customised you may find it easier to modify your existing configuration to suit Apache 2.0. Users with only lightly customised main server sections are recommended to migrate their changes into the stock Apache 2.0 configuration.

#### 2.2.1. UserDir mapping

The `UserDir` directive is used to enable URLs such as `http://example.com/~jim/` to map to a directory in the home directory of the user `jim`, such as `/home/jim/public_html`. A side-effect of this feature allows a potential attacker to determine whether a given username is present on the system, so the default configuration for Apache 2.0 does not enable `UserDir`.

To enable `UserDir` mapping, change the directive:

    UserDir disable

to

    UserDir public_html

in `/etc/httpd/conf/httpd.conf`.

See also:

- `UserDir`

#### 2.2.2. Logging

The `AgentLog`, `RefererLog` and `RefererIgnore` directives have been removed. Agent and referrer logs are still available using the `CustomLog` and `LogFormat` directives.

See also:

- `CustomLog`
- `LogFormat`

#### 2.2.3. Directory Indexing

The deprecated `FancyIndexing` directive has now been removed. The same functionality is available through the `FancyIndexing` option to the `IndexOptions` directive.

The new `VersionSort` option to the `IndexOptions` directive causes files containing version numbers to be sorted in the natural way, so that `apache-1.3.9.tar` would appear before `apache-1.3.12.tar` in a directory index page.

The defaults for the `ReadmeName` and `HeaderName` directives have changed from `README` and `HEADER` to `README.html` and `HEADER.html`.

See also:

- `IndexOptions`
- `ReadmeName`
- `HeaderName`

#### 2.2.4. Content Negotiation

The `CacheNegotiatedDocs` directive now takes the argument: on or off. Existing instances of `CacheNegotiatedDocs` should be replaced with `CacheNegotiatedDocs on`.

See also:

- `CacheNegotiatedDocs`

#### 2.2.5. Error Documents

To use a hard-coded message with the `ErrorDocument` directive, the message should be enclosed in a pair of double quotes, rather than just preceded by a double quote as required in Apache 1.3. For instance, change:

    ErrorDocument 404 "The document was not found

to

    ErrorDocument 404 "The document was not found"

See also:

- `ErrorDocument`

#### 2.2.6. Default Character Set

The default character set which will be sent in a `Content-Type` header has changed from previous versions. By default, the configuration in Scientific Linux uses a UTF-8 locale, the default character set used in `httpd.conf` is now `utf-8`, rather than the previous default of `ISO-8859-1`.

To configure the server to use a default character set of ISO-8859-1 if migrating non-UTF-8 content, change:

    AddDefaultCharset utf-8

to

    AddDefaultCharset ISO-8859-1

### 2.3. Virtual Hosts

The contents of all `<VirtualHost>` containers should be migrated in the same way as the main server section as described in Section 2.2, “Main server configuration”. Note that the SSL virtual host context has been moved into the file `/etc/httpd/conf.d/ssl.conf`.

See also:

- Apache Virtual Host Documentation

### 2.4. Modules

In Apache 2.0 the module system has been changed to allow modules to be chained together to combine them in new and interesting ways. CGI scripts, for example, can generate server-parsed HTML documents which can then be processed by `mod_include`. The possibilities are only limited by the bounds of your imagination.

The way this actually works is that each request is served by exactly one handler module followed by zero or more filter modules. Under Apache 1.3, for example, a PHP script would be handled entirely by the PHP module; under Apache 2.0 the request is initially handled by the core module (which serves static files) and subsequently filtered by the PHP module.

Exactly how to use this (and all the other new features of Apache 2.0 for that matter) is beyond the scope of this document, however the change has ramifications if you have used PATH_INFO (trailing path information after the true filename) in a document which is handled by a module that is now implemented as a filter. The core module, which initially handles the request, does not by default understand PATH_INFO and will serve 404 Not Found errors for requests that have it. The `AcceptPathInfo` directive can be used to coerce the core module into accepting requests with PATH_INFO:

    AcceptPathInfo on

See also:

- `AcceptPathInfo`
- Apache's Handler Use
- Filters

#### 2.4.1. mod_ssl

The configuration for `mod_ssl` has been moved from `httpd.conf` into the file `/etc/httpd/conf.d/ssl.conf`. For this file to be loaded, and hence for `mod_ssl` to work, you must have the statement `Include conf.d/*.conf` in your `httpd.conf` as described in Section 2.1.3, “Dynamic Shared Object (DSO) Support”.

`ServerName` directives in SSL virtual hosts must explicitly specify the port number:

Example 3. Apache 1.3 SSL virtual host configuration

    ##
    ## SSL Virtual Host Context
    ##

    <VirtualHost _default_:443>
        # General setup for the virtual host
        ServerName ssl.host.name
        ...
    </VirtualHost>

Example 4. Equivalent Apache 2.0 SSL virtual host configuration

    ##
    ## SSL Virtual Host Context
    ##

    <VirtualHost _default_:443>
        # General setup for the virtual host
        ServerName ssl.host.name:443
        ...
    </VirtualHost>

See also:

- Apache Module mod_ssl
- Apache Virtual Host Documentation

#### 2.4.2. mod_proxy

Proxy access control statements are now placed inside a `<Proxy>` block rather than a `<Directory proxy:>`.

The caching functionality of the old `mod_proxy` has been split out into three other modules (`mod_cache`, `mod_disk_cache`, `mod_file_cache`), although these generally use the same or similar directives as the old `mod_proxy`.

See also:

- Apache Module mod_proxy

#### 2.4.3. mod_include

`mod_include` is now implemented as a filter and must therefore be enabled differently:

Example 5. Apache 1.3 `mod_include` configuration

    AddType text/html .shtml
    AddHandler server-parsed .shtml

Example 6. Equivalent Apache 2.0 `mod_include` configuration

    AddOutputFilter INCLUDES .shtml

Note that `Options +Includes` is still required.

See also:

- Apache Module mod_include

#### 2.4.4. mod_auth_dbm and mod_auth_db

Apache 1.3 supported two authentication modules, `mod_auth_db` and `mod_auth_dbm`, which used Berkeley Databases and DBM databases respectively. These modules have been combined into a single module named `mod_auth_dbm` in Apache 2.0, which can access several different database formats. To migrate from `mod_auth_db` in Apache 1.3, configuration files should be adjusted by replacing `AuthDBUserFile` and `AuthDBGroupFile` with the `mod_auth_dbm` equivalents `AuthDBMUserFile` and `AuthDBMGroupFile`, and the directive `AuthDBMType DB` should be added to indicate the type of database file in use.

Example 7, “Apache 1.3 mod_auth_db configuration” shows a sample `mod_auth_db` configuration for Apache 1.3, and Example 8, “Equivalent Apache 2.0 mod_auth_dbm configuration” shows how it would be migrated to Apache 2.0. Note that the `AuthDBUserFile` directive can also be used in `.htaccess` files.

Example 7. Apache 1.3 `mod_auth_db` configuration

    <Location /private/>
      AuthType Basic
      AuthName "My Private Files"
      AuthDBUserFile /var/www/authdb
      require valid-user
    </Location>

Example 8. Equivalent Apache 2.0 `mod_auth_dbm` configuration

    <Location /private/>
      AuthType Basic
      AuthName "My Private Files"
      AuthDBMUserFile /var/www/authdb
      AuthDBMType DB
      require valid-user
    </Location>

The dbmmanage Perl script, used to manipulate username/password databases, has been replaced by the htdbm program in Apache 2.0. htdbm offers equivalent functionality, and like `mod_auth_dbm` can operate a variety of database formats; a `-T` argument can be used to specify the format to use for a particular command. Table 1, “Migrating from dbmmanage to htdbm” shows how to migrate from using dbmmanage on a DBM-format database with Apache 1.3, to htdbm in 2.0.

Table 1. Migrating from dbmmanage to htdbm

Action | dbmmanage command (Apache 1.3) | Equivalent htdbm command (Apache 2.0)
--- | --- | ---
Add user to database (using given password) | `dbmmanage authdb add username password` | `htdbm -b -TDB authdb username password`
Add user to database (prompts for password) | `dbmmanage authdb adduser username` | `htdbm -TDB authdb username`
Remove user from database | `dbmmanage authdb delete username` | `htdbm -x -TDB authdb username`
List users in database | `dbmmanage authdb view` | `htdbm -l -TDB authdb`
Verify a password | `dbmmanage authdb check username` | `htdbm -v -TDB authdb username`

The `-m` and `-s` options work with both dbmmanage and htdbm (enabling the use of the MD5 or SHA1 algorithms for hashing passwords, respectively). When creating a new database with htdbm, the `-c` option must be used.

See also:

- Apache Module mod_auth_dbm

#### 2.4.5. PHP

The configuration for PHP has been moved from `httpd.conf` into the file `/etc/httpd/conf.d/php.conf`. For this file to be loaded, and hence for PHP to work, you must have the statement `Include conf.d/*.conf` in your `httpd.conf` as described in Section 2.1.3, “Dynamic Shared Object (DSO) Support”.

In PHP 4.2.0 and later the default set of predefined variables which are available in the global scope has changed. Individual input and server variables are by default no longer placed directly into the global scope; rather, they are placed into a number superglobal arrays. This change may cause scripts to break, and you may revert to the old behaviour globally by setting `register_globals` to `On` in the file `/etc/php.ini` or more selectivly by using `php_value register_globals 1` in your `httpd.conf` or in `.htaccess` files.

As of the `php-4.3.6-5` package, the default `/etc/php.ini` has also changed: it is now based on the `php.ini-recommended` defaults included in PHP releases, rather than the `php.ini-dist` defaults as used previously. Notable differences are that:

- display_errors is now Off
- log_errors now On
- magic_quotes_gpc is now Off

See also:

- PHP 4.1.0 Release Announcement for details of the global scope changes

#### 2.4.6. mod_perl

The configuration for `mod_perl` has been moved from `httpd.conf` into the file `/etc/httpd/conf.d/perl.conf`. For this file to be loaded, and hence for `mod_perl` to work, you must have the statement `Include conf.d/*.conf` in your `httpd.conf` as described in Section 2.1.3, “Dynamic Shared Object (DSO) Support”.

Occurances of `Apache::` in your `httpd.conf` must be replaced with `ModPerl::`. Additionally, the manner in which handlers are registered has been changed, for example:

Example 9. Apache 1.3 `mod_perl` configuration

    <Directory /var/www/perl>
        SetHandler perl-script
        PerlHandler Apache::Registry
        Options +ExecCGI
    </Directory>

Example 10. Equivalent Apache 2.0 `mod_perl` configuration

    <Directory /var/www/perl>
        SetHandler perl-script
        PerlResponseHandler ModPerl::Registry
        Options +ExecCGI
    </Directory>

Most modules for `mod_perl` 1.x should work without modification with `mod_perl` 2.x. XS modules will require recompilation and may possibly require minor Makefile modifications.

#### 2.4.7. mod_python

The configuration for `mod_python` has been moved from `httpd.conf` into the file `/etc/httpd/conf.d/python.conf`. For this file to be loaded, and hence for `mod_python` to work, you must have the statement `Include conf.d/*.conf` in your `httpd.conf` as described in Section 2.1.3, “Dynamic Shared Object (DSO) Support”.

#### 2.4.8. suexec

In Apache 2.0, suexec is configured using the new `SuexecUserGroup` directive rather than `User` and `Group`.

Example 11. Apache 1.3 suexec configuration

    <VirtualHost vhost.example.com:80>
        User someone
        Group somegroup
    </VirtualHost>

Example 12. Equivalent Apache 2.0 suexec configuration

    <VirtualHost vhost.example.com:80>
        SuexecUserGroup someone somegroup
    </VirtualHost>

## A. Packaging Changes

- The `apache`, `apache-devel` and `apache-manual` packages have been renamed as `httpd`, `httpd-devel` and `httpd-manual`.
- The `mod_dav` package has been incorporated into the `httpd` package.
- The `mod_put` and `mod_roaming` packages have been removed, since their functionality is a subset of that provided by `mod_dav`.
- The `mod_auth_any` and `mod_bandwidth` packages have been removed.
- `mod_ssl`'s version is now synchronised with `httpd`, which means that the `mod_ssl` package for Apache 2.0 has a lower version than `mod_ssl` package for 1.3.