From 8474e1bc2f6a87873aa2b49e5cfee049f96411af Mon Sep 17 00:00:00 2001 From: jorton Date: May 09 2007 10:23:43 +0000 Subject: - remove old migration guide --- diff --git a/migration.css b/migration.css deleted file mode 100644 index 5d6aff8..0000000 --- a/migration.css +++ /dev/null @@ -1,18 +0,0 @@ - -p { margin-left: 0.4em; margin-right: 0.4em; } - -pre.programlisting { - background-color: #dddddd; - margin-left: 0.6em; margin-right: 1em; - padding: 0.3em; width: 50em; -} - -h1.title { border-bottom: solid #cc3333; } - -div.toc { - border-right: thin solid #cc3333; - } - -h2 { border-top: thin solid #cc3333; - padding-top: 1em; } - diff --git a/migration.xml b/migration.xml deleted file mode 100644 index e20c087..0000000 --- a/migration.xml +++ /dev/null @@ -1,956 +0,0 @@ - - -httpd"> -httpd.conf"> -mod_ssl"> -mod_proxy"> -mod_include"> -mod_auth_db"> -mod_auth_dbm"> -mod_perl"> -mod_python"> - -htdbm"> -dbmmanage"> - - - -prefork"> -worker"> - -]> - -
- - -Apache Migration HOWTO - - - -This HOWTO covers the migration of &distro; 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. - - - - - -Naming and filesystem changes - - -Packaging changes - -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 -. - - - - -Filesystem 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 ); the logrotate configuration file has been -renamed from /etc/logrotate.d/apache to -/etc/logrotate.d/httpd. - - - - - -Migrating your configuration - -If you have upgraded your server from a previous version of -&distro; 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 &httpdconf; 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 &httpdconf; 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 - - - - - -Global Environment - -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. - - -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 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: - - -Apache 1.3 port configuration - -Port 123 -ServerName www.example.com - - - -Equivalent Apache 2.0 port configuration - -Listen 123 -ServerName www.example.com:123 - - - -See also: - - -Listen - -ServerName - - - - - -Server-pool size regulation - -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 &distro; 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: - - -Apache -Multi-Processing Modules - - - - - -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) simply copy this section from the stock -&distro; 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 &httpdconf; 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. - - - - - - -Other changes - -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 &httpdconf;, 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. - - - - - -Main server configuration - -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. - - -UserDir mapping - -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: - - -UserDir - - - - - -Logging - -The AgentLog, RefererLog -and RefererIgnore directives have been removed. -Agent and referrer logs are still available using the -CustomLog and LogFormat -directives. - -See also: - - -CustomLog - -LogFormat - - - - - -Directory Indexing - -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: - - -IndexOptions - -ReadmeName - -HeaderName - - - - - -Content Negotiation - -The CacheNegotiatedDocs directive now takes -the argument: on or off. Existing instances of -CacheNegotiatedDocs should be replaced with -CacheNegotiatedDocs on. - -See also: - - -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. For instance, change: - - - -ErrorDocument 404 "The document was not found - - -to - - - -ErrorDocument 404 "The document was not found" - - - - - -See also: - - -ErrorDocument - - - - - -Default Character Set - -The default character set which will be sent in a -Content-Type header has changed from previous -versions. By default, the configuration in &distro; uses a UTF-8 -locale, the default character set used in &httpdconf; 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 - - - - - - - -Virtual Hosts - -The contents of all <VirtualHost> -containers should be migrated in the same way as the main server -section as described in . Note that -the SSL virtual host context has been moved into the file -/etc/httpd/conf.d/ssl.conf. - -See also: - - -Apache -Virtual Host Documentation - - - - - -Modules - -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: - - -AcceptPathInfo - -Apache's -Handler Use - -Filters - - - - -mod_ssl - -The configuration for &mod_ssl; has been moved from &httpdconf; -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 -&httpdconf; as described in . - -ServerName directives in SSL virtual hosts -must explicitly specify the port number: - - -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> - - - -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: - - -Apache -Module mod_ssl - -Apache -Virtual Host Documentation - - - - - -mod_proxy - -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: - - -Apache -Module mod_proxy - - - - - -mod_include - -&mod_include; is now implemented as a filter and must therefore be enabled -differently: - - -Apache 1.3 &mod_include; configuration - -AddType text/html .shtml -AddHandler server-parsed .shtml - - - - -Equivalent Apache 2.0 &mod_include; configuration - -AddOutputFilter INCLUDES .shtml - - - -Note that Options +Includes is still -required. - -See also: - - -Apache -Module mod_include - - - - - -mod_auth_dbm and mod_auth_db - -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. - - shows a sample &mod_auth_db; -configuration for Apache 1.3, and shows how -it would be migrated to Apache 2.0. Note that the -AuthDBUserFile directive can also be used in -.htaccess files. - - -Apache 1.3 &mod_auth_db; configuration - -<Location /private/> - AuthType Basic - AuthName "My Private Files" - AuthDBUserFile /var/www/authdb - require valid-user -</Location> - - - - -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. shows how to -migrate from using &dbmmanage; on a DBM-format database with Apache -1.3, to &htdbm; in 2.0. - - - -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: - - -Apache -Module mod_auth_dbm - - - - - -PHP - -The configuration for PHP has been moved from &httpdconf; 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 &httpdconf; -as described in . - -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 &httpdconf; 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: - - -display_errors is now Off -log_errors now On -magic_quotes_gpc is now Off - - -See also: - - -PHP 4.1.0 Release -Announcement for details of the global scope changes - - - - - -mod_perl - -The configuration for &mod_perl; has been moved from &httpdconf; -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 -&httpdconf; as described in . - -Occurances of Apache:: in your &httpdconf; -must be replaced with ModPerl::. Additionally, the -manner in which handlers are registered has been changed, for -example: - - -Apache 1.3 &mod_perl; configuration - -<Directory /var/www/perl> - SetHandler perl-script - PerlHandler Apache::Registry - Options +ExecCGI -</Directory> - - - - -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. - - - - - - -mod_python - -The configuration for &mod_python; has been moved from &httpdconf; -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 -&httpdconf; as described in . - - - - -suexec - -In Apache 2.0, suexec is configured using the new -SuexecUserGroup directive rather than -User and Group. - - -Apache 1.3 suexec configuration - -<VirtualHost vhost.example.com:80> - User someone - Group somegroup -</VirtualHost> - - - - -Equivalent Apache 2.0 suexec configuration - -<VirtualHost vhost.example.com:80> - SuexecUserGroup someone somegroup -</VirtualHost> - - - - - - - -Packaging Changes - - - -The apache, -apache-devel and apache-manual -packages have been renamed as &httpd;, httpd-devel -and httpd-manual. - -The mod_dav package has been -incorporated into the &httpd; package. - -The mod_put and -mod_roaming packages have been removed, since their -functionality is a subset of that provided by -mod_dav. - -The 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. - - - - - -