11.2.2. Migrating Apache HTTP Server 1.3 Configuration Files to 2.0
This section details migrating an Apache HTTP Server 1.3 configuration file to be utilized by Apache HTTP Server 2.0.
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:
11.2.2.1. Global Environment Configuration
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.
11.2.2.1.1. Interface and Port Binding
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:
11.2.2.1.2. Server-Pool Size Regulation
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:
11.2.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 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:
Include conf.d/*.conf
Omission of this directive results in the failure of all modules packaged in their own RPMs (such as mod_perl, php, and mod_ssl).
11.2.2.1.4. 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 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.
11.2.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 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.
11.2.2.2.1. UserDir Mapping
The UserDir directive is used to enable URLs such as http://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:
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:
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:
11.2.2.2.3. Directory Indexing
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:
11.2.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.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.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 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:
11.2.2.4. Modules and Apache HTTP Server 2.0
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:
AcceptPathInfo on
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.1. The suexec Module
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>
11.2.2.4.2. The mod_ssl Module
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 11.2.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
ErrorLog and
LogLevel for more information about these directives.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.3. 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_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:
11.2.2.4.4. The mod_include Module
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:
11.2.2.4.5. 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, 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.
|
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 11.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:
11.2.2.4.6. 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_perl to work, the statement
Include conf.d/*.conf must be included in
httpd.conf as described in
Section 11.2.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.
11.2.2.4.7. The mod_python Module
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 11.2.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 Fedora 13.
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:
11.2.2.4.9. The mod_authz_ldap Module
Fedora 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
http://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
http://authzldap.othello.ch/ for more information on configuring the
mod_authz_ldap third party module.
