Abstract
This HOWTO covers the migration of Momonga 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.
Table of Contents
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.
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.
If you have upgraded your server from a previous version of
Momonga 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
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.
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:
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 Momonga 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
Momonga 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.
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 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.
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 Momonga 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 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:
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:
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:
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:
Example 5. Apache 1.3 mod_include configuration
AddType text/html .shtml AddHandler server-parsed .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.
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:
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:
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.
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.
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>
apache,
apache-devel and apache-manual
packages have been renamed as httpd, httpd-devel
and httpd-manual.mod_dav package has been
incorporated into the httpd package.mod_put and
mod_roaming packages have been removed, since their
functionality is a subset of that provided by
mod_dav.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.