Apache Migration HOWTO

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:

Port 123
ServerName www.example.com

Listen 123
ServerName www.example.com:123

See also:

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 Red Hat Enterprise 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:

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 Red Hat Enterprise 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 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.

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:

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

See also:

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:

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

See also:

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:

The default character set which will be sent in a Content-Type header has changed from previous versions. By default, the configuration in Red Hat Enterprise 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

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:

##
## SSL Virtual Host Context
##

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

##
## SSL Virtual Host Context
##

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

See also:

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:

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

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

AddOutputFilter INCLUDES .shtml

Note that Options +Includes is still required.

See also:

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.

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

<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.

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:

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:

See also:

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:

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

<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.

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”.

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

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

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