Migrating Apache HTTP Server 1.3 Configuration Files

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 in your 1.3 version configuration file, you should change it to Listen 80 instead. If you had set Port to some value other than 80 then you must also append the port number to the contents of your ServerName directive.

For example, the following is a sample Apache HTTP Server 1.3 directive:

Port 123
ServerName www.example.com

To migrate this setting to Apache HTTP Server 2.0, use the following structure:

Listen 123
ServerName www.example.com:123 

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mpm_common.html#listen

• http://httpd.apache.org/docs-2.0/mod/core.html#servername

Server-pool Size Regulation

In Apache HTTP Server 2.0, the responsibility for accepting requests and dispatching child-processes to handle them has been abstracted into a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server because an MPM module is responsible for basic request handling and dispatching. There are three MPM modules that ship with version 2.0: prefork, worker, and perchild.

The original Apache HTTP Server 1.3 behavior has been moved into the prefork MPM. Currently only the prefork MPM is available on Red Hat Linux, although other MPMs may be made available at some later date.

The MPM supplied by default on Red Hat Linux is prefork which accepts the same directives as Apache HTTP Server 1.3. The following directives may be migrated directly:

• StartServers

• MinSpareServers

• MaxSpareServers

• MaxClients

• MaxRequestsPerChild

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mpm.html

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) copy this section from the stock Red Hat Linux Apache HTTP Server 2.0 configuration file.

	Important
	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: Include conf.d/*.conf Omission of this directive will result in the failure of all modules packaged in their own RPMs (such as mod_perl, php, and mod_ssl).

Those who still do not want to copy the section from the stock Apache HTTP Server 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 Apache 2.0 API allows modules to specify their ordering, eliminating the need for these two directives.

• The order of the LoadModule lines is 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 /etc/httpd/conf.d/ directory.

• The various HAVE_XXX definitions are no longer defined.

Other Global Environment Changes

The following directives have been removed from Apache HTTP Server 2.0's configuration:

• ServerType — The Apache HTTP Server can only be run as ServerType standalone making this directive irrelevant.

• AccessConfig and ResourceConfig — These 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.

UserDir Mapping

The UserDir directive is used to enable URLs such as http://example.com/~jim/ to map to a subdirectory within 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 HTTP Server 2.0 disables this directive.

To enable UserDir mapping, change the directive in httpd.conf from:

UserDir disable

to the following:

UserDir public_html

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_userdir.html#userdir

Logging

The following logging directives have been removed:

• AgentLog

• RefererLog

• RefererIgnore

However, agent and referrer logs are still available using the CustomLog and LogFormat directives.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_log_config.html#customlog

• http://httpd.apache.org/docs-2.0/mod/mod_log_config.html#logformat

Directory Indexing

The deprecated FancyIndexing directive has now been removed. The same functionality is available through the FancyIndexing option within 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 httpd-2.0.6.tar would appear before httpd-2.0.36.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.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_autoindex.html#indexoptions

• http://httpd.apache.org/docs-2.0/mod/mod_autoindex.html#readmename

• http://httpd.apache.org/docs-2.0/mod/mod_autoindex.html#headername

Content Negotiation

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

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_negotiation.html#cachenegotiateddocs

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.

To migrate an ErrorDocument setting to Apache HTTP Server 2.0, use the following structure:

ErrorDocument 404 "The document was not found"

Note that there is a trailing double quote in the example ErrorDocument directive above.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/core.html#errordocument

The mod_ssl Module

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 the Section called Dynamic Shared Object (DSO) Support.

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

For example, the following is a sample Apache HTTP Server 1.3 directive:

##
## SSL Virtual Host Context
##

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

To migrate this setting to Apache HTTP Server 2.0, use the following structure:

##
## SSL Virtual Host Context
##

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

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_ssl.html

• http://httpd.apache.org/docs-2.0/vhosts/

The mod_proxy Module

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 the following three modules:

• mod_cache

• mod_disk_cache

• mod_file_cache

These generally use the same or similar directives as the older versions of the mod_proxy module.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_proxy.html

The mod_include Module

The mod_include module is now implemented as a filter (see the Section called Modules and Apache HTTP Server 2.0 for more on filters) and is therefore enabled differently.

For example, the following is a sample Apache HTTP Server 1.3 directive:

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

To migrate this setting to Apache HTTP Server 2.0, use the following structure:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

Note that just as before, the Options +Includes directive is still required for the <Directory> section or in a .htaccess file.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_include.html

The mod_auth_dbm and mod_auth_db Modules

Apache HTTP Server 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 HTTP Server 2.0, which can access several different database formats. To migrate from mod_auth_db in version 1.3, configuration files should be adjusted by replacing AuthDBUserFile and AuthDBGroupFile with the mod_auth_dbm equivalents: AuthDBMUserFile and AuthDBMGroupFile. Also, you must add the directive AuthDBMType DB to indicate the type of database file in use.

The following example shows a sample mod_auth_db configuration for Apache 1.3:

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

To migrate this setting to version 2.0 of Apache HTTP Server, use the following structure:

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

Note that the AuthDBMUserFile directive can also be used in .htaccess files.

The dbmmanage Perl script, used to manipulate username and password databases, has been replaced by htdbm in Apache HTTP Server 2.0. The htdbm program offers equivalent functionality and like mod_auth_dbm can operate a variety of database formats; the -T option can be used on the command line to specify the format to use.

Table 14-1 shows how to migrate from a DBM-format database to htdbm format using dbmmanage.

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.

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

• http://httpd.apache.org/docs-2.0/mod/mod_auth_dbm.html

The mod_perl Module

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_perlto work, you must have the statement Include conf.d/*.conf in your httpd.conf as described in the Section called 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.

This is a sample Apache HTTP Server 1.3 mod_perl configuration:

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

This is the equivalent mod_perl for Apache HTTP Server 2.0:

<Directory /var/www/perl>
    SetHandler perl-script
    PerlModule ModPerl::Registry
    PerlHandler ModPerl::Registry::handler
    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.

The mod_python Module

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 the Section called Dynamic Shared Object (DSO) Support.

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, you must have the statement Include conf.d/*.conf in your httpd.conf as described in the Section called Dynamic Shared Object (DSO) Support.

The PHP is now implemented as a filter and must therefore be enabled in a different manor. See the Section called Modules and Apache HTTP Server 2.0 for more about filters.

Under Apache HTTP Server 1.3, PHP was implemented using the following directives:

AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

Under Apache HTTP Server 2.0, use the following directives instead:

<Files *.php>
    SetOutputFilter PHP
    SetInputFilter PHP
</Files>

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. This change may cause scripts to break. You may revert to the old behavior by setting register_globals to On in the file /etc/php.ini.

For more on this topic, refer to the following URL for details concerning the global scope changes:

• http://www.php.net/release_4_1_0.php