From 371657c647306368940e0a7a4b54c147b6583a62 Mon Sep 17 00:00:00 2001 From: Daniel Earl Poirier Date: Sun, 20 Jun 2010 19:48:13 +0000 Subject: [PATCH] First pass at documentation for upgrading to 2.4. Went through CHANGES and tried to pick out things that would require a 2.2 user to make changes for 2.4. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@956396 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/upgrading.xml | 203 +++++++++++++++++++++++++++++++++++++- 1 file changed, 199 insertions(+), 4 deletions(-) diff --git a/docs/manual/upgrading.xml b/docs/manual/upgrading.xml index 8083712297..6b63944cf7 100644 --- a/docs/manual/upgrading.xml +++ b/docs/manual/upgrading.xml @@ -34,6 +34,12 @@ can find a summary of API changes in the API updates overview.

+

This document describes changes in server behavior that might + require you to change your configuration or how you use the server + in order to continue using 2.4 as you are currently using 2.2. + To take advantage of new features in 2.4, see the New Features + document.

+

This document describes only the changes from 2.2 to 2.4. If you are upgrading from version 2.0, you should also consult the 2.0 to 2.2 @@ -45,25 +51,214 @@

Compile-Time Configuration Changes - + +

The compilation process is very similar to the one used in + version 2.2. Your old configure command line (as + found in build/config.nice in the installed server + directory) can be used in most cases. There are some changes in + the default settings. Some details of changes:

+ +
    +
  • These modules have been removed: mod_authn_default, + mod_authz_default, mod_mem_cache. If you were using + mod_mem_cache in 2.2, look at mod_disk_cache in + 2.4.
    • + +
  • All load balancing implementations have been moved to + individual, self-contained mod_proxy submodules, e.g. + mod_lbmethod_bybusyness. You might need + to build and load any of these that your configuration + uses.
    • + +
  • Platform support has been removed for BeOS, OS/2, TPF, and + even older platforms such as A/UX, Next, and Tandem. These were + believed to be broken anyway.
    • + +
  • configure: dynamic modules (DSO) are built by default
    • + +
  • configure: the "most" module set gets built by default
    • +
Run-Time Configuration Changes +

There have been significant changes in authorization configuration, + and other minor configuration changes, that could require changes to your 2.2 + configuration files before using them for 2.4.

+ +
+ Authorization + +

Any configuration file that uses authorization will likely + need changes.

+ +

You should review the Authentication, + Authorization and Access Control Howto, especially the section + Beyond just authorization + which explains the new mechanisms for controlling the order in + which the authorization directives are applied.

+ +
+ Access control + +

In 2.2, access control based on client hostname, IP address, + and other characteristics of client requests was done using the + directives Order, Allow, Deny, and Satisfy.

+ +

In 2.4, such access control is done in the same way as other + authorization checks, using the new module + mod_authz_host. The old access control idioms + should be replaced by the new authentication mechanisms, + although for compatibility with old configurations, the new + module mod_access_compat is provided.

+ +

Here are some examples of old and new ways to do the same + access control.

+ +

In this example, all requests are denied.

+ + 2.2 configuration: + Order deny,allow
+ Deny from all + + + 2.4 configuration: + Require all denied + + +

In this example, all requests are allowed.

+ + 2.2 configuration: + Order allow,deny
+ Allow from all + + + 2.4 configuration: + Require all granted + - +

In the following example, all hosts in the apache.org domain + are allowed access; all other hosts are denied access.

+ + + 2.2 configuration: + Order Deny,Allow
+ Deny from all
+ Allow from apache.org + + + 2.4 configuration: + Require host apache.org + +
+ +
+ +
+ Other configuration changes + +

Some other small adjustments may be necessary for particular + configurations as discussed below.

+ +
    +
  • The DefaultType + directive no longer has any effect, other than to emit a + warning if it's used with any value other than + none. You need to use other configuration + settings to replace it in 2.4. +
    • + +
  • mod_log_config: ${cookie}C + matches whole cookie names. Previously any substring would + match.
    • + +
  • mod_dav_fs: The format of the DavLockDB file has changed for + systems with inodes. The old DavLockDB file must be deleted on + upgrade. +
    • + +
  • KeepAlive only + accepts values of On or Off. + Previously, any value other than "Off" or "0" was treated as + "On".
    • + +
  • Directives AcceptMutex, LockFile, RewriteLock, SSLMutex, + SSLStaplingMutex, and WatchdogMutexPath have been replaced + with a single Mutex + directive. You will need to evaluate any use of these removed + directives in your 2.2 configuration to determine if they can + just be deleted or will need to be replaced using Mutex.
    • + +
  • mod_cache: CacheIgnoreURLSessionIdentifiers + now does an exact match against the query string instead of a + partial match. If your configuration was using partial + strings, e.g. using sessionid to match + /someapplication/image.gif;jsessionid=123456789, + then you will need to change to the full string + jsessionid. +
    • + +
  • mod_ldap: LDAPTrustedClientCert is now + consistently a per-directory setting only. If you use this + directive, review your configuration to make sure it is + present in all the necessary directory contexts.
    • + +
+
Misc Changes + + +
Third Party Modules +

All modules must be recompiled for 2.4 before being loaded.

+ +

Many third-party modules designed for version 2.2 will + otherwise work unchanged with the Apache HTTP Server version 2.4. + Some will require changes; see the API + update overview.

+
+
+ Common problems when upgrading +
-- 2.40.0