This section details migrating an Apache HTTP Server 1.3 configuration file to
be utilized by Apache HTTP Server 2.0.
If upgrading to Red Hat Enterprise Linux 4 from Red Hat Enterprise Linux 2.1, note that the new
stock configuration file for the Apache HTTP Server 2.0 package is installed as
/etc/httpd/conf/httpd.conf.rpmnew and the original
version 1.3 httpd.conf is left untouched. It is
entirely up to you whether to use the new configuration file and migrate
the old settings to it, or use the 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 version 1.3 and 2.0 are divided into three sections.
This command highlights any modifications made. If a copy of the
original file is not available, extract it from an RPM package using the
rpm2cpio and cpio commands, as in
the following example:
Finally, it is useful to know that the Apache HTTP Server has a testing mode to
check for configuration errors. To use access it, type the following
command:
The global environment section of the configuration file contains
directives which affect the overall operation of the Apache HTTP Server, such as
the number of concurrent requests it can handle and the locations of
the various files. This section requires a large number of changes
and should be based on the Apache HTTP Server 2.0 configuration file, while
migrating the old settings into it.
The BindAddress and Port
directives no longer exist; their functionality is now provided by a
more flexible Listen directive.
If Port 80 was set in the 1.3 version
configuration file, change it to Listen 80 in the
2.0 configuration file. If Port was set to some
value other than 80, then append the port
number to the contents of the 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:
When the Apache HTTP Server accepts requests, it dispatches child processes or
threads to handle them. This group of child processes or threads is
known as a server-pool. Under Apache HTTP Server 2.0,
the responsibility for creating and maintaining these server-pools
has been abstracted to 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. There are three MPM
modules that ship with 2.0: prefork,
worker, and
perchild. Currently only the
prefork and worker MPMs are
available, although the perchild MPM may be
available at a later date.
The original Apache HTTP Server 1.3 behavior has been moved into the
prefork MPM. The prefork MPM
accepts the same directives as Apache HTTP Server 1.3, so the following
directives may be migrated directly:
StartServers
MinSpareServers
MaxSpareServers
MaxClients
MaxRequestsPerChild
The worker MPM implements a multi-process,
multi-threaded server providing greater scalability. When using this
MPM, requests are handled by threads, conserving system resources
and allowing large numbers of requests to be served
efficiently. Although some of the directives accepted by the
worker MPM are the same as those accepted by the
prefork MPM, the values for those directives
should not be transfered directly from an Apache HTTP Server 1.3
installation. It is best to instead use the default values as a
guide, then experiment to determine what values work best.
 | Important |
|---|
| | To use the worker MPM, create the file
/etc/sysconfig/httpd and add the following
directive:
HTTPD=/usr/sbin/httpd.worker |
|
For more on the topic of MPMs, refer to the following documentation
on the Apache Software Foundation's website:
There are many changes required here, and it is highly recommended
that anyone trying to modify an Apache HTTP Server 1.3 configuration to suit
version 2.0 (as opposed to migrating the changes into the version
2.0 configuration) copy this section from the stock Apache HTTP Server 2.0
configuration file.
Those who 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 HTTP Server 2.0 API allows
modules to specify their ordering, eliminating the need for
these two directives.
The order of the LoadModule lines are no
longer relevant in most cases.
Many modules have been added, removed, renamed, split
up, or incorporated into others.
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 their
relevant files within the
/etc/httpd/conf.d/ directory.
The various HAVE_XXX definitions are no
longer defined.
| Important |
|---|
| | If modifying the original file, note that it is of paramount
importance that the httpd.conf contains the
following directive:
Omission of this directive results in the failure of all modules packaged in
their own RPMs (such as mod_perl,
php, and mod_ssl).
|
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 as they mirror the
functionality of the Include directive. If
the AccessConfig and
ResourceConfig directives are set, replace
them 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 the
httpd.conf, with the one corresponding to
ResourceConfig preceding the one
corresponding to AccessConfig. If using the
default values, include them explicitly as
conf/srm.conf and
conf/access.conf files.
The main server configuration section of the configuration file sets
up the main server, which responds to any requests that are not
handled by a virtual host defined within a
<VirtualHost> container. Values here also
provide defaults for any <VirtualHost>
containers defined.
The directives used in this section have changed little between
Apache HTTP Server 1.3 and version 2.0. If the main server configuration is
heavily customized, it may be easier to modify the existing
configuration file to suit Apache HTTP Server 2.0. Users with only lightly
customized main server sections should migrate their changes into the
default 2.0 configuration.
The UserDir directive is used to enable URLs such
as https://example.com/~bob/ to map to a
subdirectory within the home directory of the user
bob, such as
/home/bob/public_html/. A side-effect of this
feature allows a potential attacker to determine whether a given
username is present on the system. For this reason, the default
configuration for Apache HTTP Server 2.0 disables this directive.
To enable UserDir mapping, change the
directive in httpd.conf from:
to the following:
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
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:
The deprecated FancyIndexing directive has now
been removed. The same functionality is available through the
FancyIndexing option within
the IndexOptions directive.
The VersionSort option to the
IndexOptions directive causes files containing
version numbers to be sorted in a more natural way. For example,
httpd-2.0.6.tar appears 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:
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:
To use a hard-coded message with the
ErrorDocument directive, the message should be
enclosed in a pair of double quotation marks ["],
rather than just preceded by a double quotation mark as required in
Apache HTTP Server 1.3.
For example, the following is a sample Apache HTTP Server 1.3 directive:
ErrorDocument 404 "The document was not found |
To migrate an ErrorDocument setting to Apache HTTP Server
2.0, use the following structure:
ErrorDocument 404 "The document was not found" |
Note the trailing double quote in the previous
ErrorDocument directive example.
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
In Apache HTTP Server 2.0, the module system has been changed to allow modules to
be chained together or combined in new and interesting
ways. Common Gateway Interface
(CGI) scripts, for example, can generate
server-parsed HTML documents which can then be processed by
mod_include. This opens up a tremendous number of
possibilities with regards to how modules can be combined to achieve a
specific goal.
The way this works is that each request is served by exactly
one handler module followed by zero or more
filter modules.
Under Apache HTTP Server 1.3, for example, a Perl script would be handled in its
entirety by the Perl module (mod_perl). Under
Apache HTTP Server 2.0, the request is initially handled by
the core module — which serves static files — and is then
filtered by mod_perl.
Exactly how to use this, and all other new features of Apache HTTP Server 2.0, is
beyond the scope of this document; however, the change has
ramifications if the PATH_INFO directive is used
for a document which is handled by a module that is now implemented as
a filter, as each contains trailing path information after the true
file name. The core module, which initially handles the request, does
not by default understand PATH_INFO and returns
404 Not Found errors for requests
that contain such information. As an alternative, use the
AcceptPathInfo directive to coerce the core module
into accepting requests with PATH_INFO.
The following is an example of this directive:
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
In Apache HTTP Server 2.0, the mod_suexec module uses
the SuexecUserGroup directive, rather than
the User and Group
directives, which is used for configuring virtual hosts.
The User and Group
directives can still be used in general, but are deprecated for
configuring virtual hosts.
For example, the following is a sample Apache HTTP Server 1.3 directive:
<VirtualHost vhost.example.com:80>
User someone
Group somegroup
</VirtualHost> |
To migrate this setting to Apache HTTP Server 2.0, use the following
structure:
<VirtualHost vhost.example.com:80>
SuexecUserGroup someone somegroup
</VirtualHost> |
The configuration for mod_ssl has been moved
from the httpd.conf file into the
/etc/httpd/conf.d/ssl.conf file. For this file
to be loaded, and for mod_ssl to work,
the statement Include conf.d/*.conf must be in
the httpd.conf file as described in Section 10.2.1.3 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:
<VirtualHost _default_:443>
# General setup for the virtual host
ServerName ssl.example.name
...
</VirtualHost> |
To migrate this setting to Apache HTTP Server 2.0, use the following
structure:
<VirtualHost _default_:443>
# General setup for the virtual host
ServerName ssl.host.name:443
...
</VirtualHost> |
It is also important to note that both the SSLLog
and SSLLogLevel directives have been removed. The
mod_ssl module now obeys the
ErrorLog and LogLevel
directives. Refer to Section 10.5.35 ErrorLog and Section 10.5.36 LogLevel for more information about these
directives.
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
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_mem_cache
These generally use directives similar to the older versions of the
mod_proxy module, but it is advisable to verify
each directive before migrating any cache settings.
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
The mod_include module is now implemented as a
filter and is therefore enabled differently. Refer to Section 10.2.4 Modules and Apache HTTP Server 2.0 for more about filters.
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 the Options +Includes directive is
still required for the <Directory>
container or in a .htaccess file.
For more on this topic, refer to the following documentation on the
Apache Software Foundation's website:
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, configuration files should be
adjusted by replacing AuthDBUserFile and
AuthDBGroupFile with the
mod_auth_dbm equivalents,
AuthDBMUserFile and
AuthDBMGroupFile. Also, the directive
AuthDBMType DB must be added to indicate the type
of database file in use.
The following example shows a sample
mod_auth_db configuration for Apache HTTP Server 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 10-1 shows how to migrate from a DBM-format
database to htdbm format using
dbmmanage.
| Action | dbmmanage command (1.3) | Equivalent htdbm command (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 |
Table 10-1. Migrating from dbmmanage to htdbm
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:
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, the
statement Include conf.d/*.conf must be included
in httpd.conf as described in Section 10.2.1.3 Dynamic Shared Object (DSO) Support.
Occurrences of Apache:: in
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
PerlResponseHandler ModPerl::Registry
Options +ExecCGI
</Directory> |
Most modules for mod_perl 1.x should work
without modification with mod_perl 2.x. XS
modules require recompilation and may require minor Makefile
modifications.
Configuration for mod_python has moved from
httpd.conf to the
/etc/httpd/conf.d/python.conf file. For this
file to be loaded, and hence for mod_python to
work, the statement Include conf.d/*.conf must be
in httpd.conf as described in Section 10.2.1.3 Dynamic Shared Object (DSO) Support.
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, the statement Include conf.d/*.conf must
be in httpd.conf as described in Section 10.2.1.3 Dynamic Shared Object (DSO) Support.
 | Note |
|---|
| | Any PHP configuration directives used in Apache HTTP Server 1.3 are now fully
compatible, when migrating to Apache HTTP Server 2.0 on Red Hat Enterprise Linux 4.
|
In PHP version 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. 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:
Red Hat Enterprise Linux ships with the mod_authz_ldap module for
the Apache HTTP Server. This module uses the short form of the distinguished name
for a subject and the issuer of the client SSL certificate to
determine the distinguished name of the user within an LDAP directory.
It is also capable of authorizing users based on attributes of that
user's LDAP directory entry, determining access to assets based on the
user and group privileges of the asset, and denying access for users
with expired passwords. The mod_ssl module is
required when using the mod_authz_ldap module.
| Important |
|---|
| | The mod_authz_ldap module does not
authenticate a user to an LDAP directory using an encrypted
password hash. This functionality is provided by the experimental
mod_auth_ldap module. Refer to the
mod_auth_ldap module documentation online at
https://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html
for details on the status of this module.
|
The /etc/httpd/conf.d/authz_ldap.conf file
configures the mod_authz_ldap
module.
Refer to
/usr/share/doc/mod_authz_ldap-<version>/index.html
(replacing <version> with the
version number of the package) or https://authzldap.othello.ch/
for more information on configuring the
mod_authz_ldap third party module.
