upgrading.xml revision b44565f239485673d9486068588a5fb3af008be9
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina<!-- $LastChangedRevision$ -->
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina Licensed to the Apache Software Foundation (ASF) under one or more
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina contributor license agreements. See the NOTICE file distributed with
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina this work for additional information regarding copyright ownership.
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina The ASF licenses this file to You under the Apache License, Version 2.0
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina (the "License"); you may not use this file except in compliance with
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina the License. You may obtain a copy of the License at
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina Unless required by applicable law or agreed to in writing, software
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina distributed under the License is distributed on an "AS IS" BASIS,
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina See the License for the specific language governing permissions and
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina limitations under the License.
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <p>In order to assist folks upgrading, we maintain a document
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina describing information critical to existing Apache HTTP Server users. These
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina are intended to be brief notes, and you should be able to find
50c9d542e8bf641412debaa82a4dcf67ddb72258Lukas Slebodnik more information in either the <a
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina href="new_features_2_4.html">New Features</a> document, or in
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina the <code>src/CHANGES</code> file. Application and module developers
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina can find a summary of API changes in the <a href="developer/new_api_2_4.html"
bbc34d5a6e84d6c337bd89a22d33e365eb466226Pavel Březina <p>This document describes changes in server behavior that might
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina require you to change your configuration or how you use the server
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina in order to continue using 2.4 as you are currently using 2.2.
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina To take advantage of new features in 2.4, see the New Features
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina document.</p>
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <p>This document describes only the changes from 2.2 to 2.4. If you
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina are upgrading from version 2.0, you should also consult the <a
c4d4fe1603420fe8f3d256a3a446974699563ff3Petr Cech href="http://httpd.apache.org/docs/2.2/upgrading.html">2.0 to 2.2
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina<seealso><a href="new_features_2_4.html">Overview of new features in
4e5e846de22407f825fe3b4040d79606818a2419Jakub Hrozek <title>Compile-Time Configuration Changes</title>
4e5e846de22407f825fe3b4040d79606818a2419Jakub Hrozek <p>The compilation process is very similar to the one used in
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina version 2.2. Your old <code>configure</code> command line (as
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina found in <code>build/config.nice</code> in the installed server
4e5e846de22407f825fe3b4040d79606818a2419Jakub Hrozek directory) can be used in most cases. There are some changes in
4e5e846de22407f825fe3b4040d79606818a2419Jakub Hrozek the default settings. Some details of changes:</p>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>These modules have been removed: mod_authn_default,
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina mod_authz_default, mod_mem_cache. If you were using
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina mod_mem_cache in 2.2, look at <module>mod_cache_disk</module> in
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>All load balancing implementations have been moved to
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina individual, self-contained mod_proxy submodules, e.g.
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <module>mod_lbmethod_bybusyness</module>. You might need
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina to build and load any of these that your configuration
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>Platform support has been removed for BeOS, TPF, and
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina even older platforms such as A/UX, Next, and Tandem. These were
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina believed to be broken anyway.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>configure: dynamic modules (DSO) are built by default</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>configure: the "most" module set gets built by default</li>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <p>There have been significant changes in authorization configuration,
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina and other minor configuration changes, that could require changes to your 2.2
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina configuration files before using them for 2.4.</p>
5928fcbb57b92bfd18ad15aaaf4a5e1ab8dabe61Petr Cech <p>Any configuration file that uses authorization will likely
5928fcbb57b92bfd18ad15aaaf4a5e1ab8dabe61Petr Cech need changes.</p>
c4d4fe1603420fe8f3d256a3a446974699563ff3Petr Cech <p>You should review the <a href="howto/auth.html">Authentication,
5928fcbb57b92bfd18ad15aaaf4a5e1ab8dabe61Petr Cech Authorization and Access Control Howto</a>, especially the section
5928fcbb57b92bfd18ad15aaaf4a5e1ab8dabe61Petr Cech <a href="howto/auth.html#beyond">Beyond just authorization</a>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina which explains the new mechanisms for controlling the order in
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina which the authorization directives are applied.</p>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <p>In 2.2, access control based on client hostname, IP address,
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina and other characteristics of client requests was done using the
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina directives <directive
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina module="mod_access_compat">Order</directive>, <directive
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina module="mod_access_compat">Allow</directive>, <directive
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina module="mod_access_compat">Deny</directive>, and <directive
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina module="mod_access_compat">Satisfy</directive>.</p>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <p>In 2.4, such access control is done in the same way as other
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina authorization checks, using the new module
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <module>mod_authz_host</module>. The old access control idioms
54ed1b1214dbf9da1f481e8d193c81ce4312516bPavel Březina should be replaced by the new authentication mechanisms,
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina although for compatibility with old configurations, the new
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina module <module>mod_access_compat</module> is provided.</p>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina <p>Here are some examples of old and new ways to do the same
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina access control.</p>
e87b2a6e94c1066b3044fe683825ff5b4f8716c2Pavel Březina <p>In this example, all requests are denied.</p>
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina Order deny,allow<br />
360a4be4266d6a72be99dfd252623dc0527f5b84Pavel Březina Deny from all
3a5ea81007bd38ce511c37f65cc45d4b6b95ec44Pavel Březina Require all denied
3a5ea81007bd38ce511c37f65cc45d4b6b95ec44Pavel Březina <p>In this example, all requests are allowed.</p>
3a5ea81007bd38ce511c37f65cc45d4b6b95ec44Pavel Březina Order allow,deny<br />
3a5ea81007bd38ce511c37f65cc45d4b6b95ec44Pavel Březina Allow from all
3a5ea81007bd38ce511c37f65cc45d4b6b95ec44Pavel Březina Require all granted
641d684ee88c6540a4cf1d74d258614f615699fePavel Březina <p>In the following example, all hosts in the example.org domain
641d684ee88c6540a4cf1d74d258614f615699fePavel Březina are allowed access; all other hosts are denied access.</p>
641d684ee88c6540a4cf1d74d258614f615699fePavel Březina Order Deny,Allow<br />
e87b2a6e94c1066b3044fe683825ff5b4f8716c2Pavel Březina Deny from all<br />
71965bb18407ff45ada9e47cb6def086e48663c6Pavel Březina <p>Some other small adjustments may be necessary for particular
71965bb18407ff45ada9e47cb6def086e48663c6Pavel Březina configurations as discussed below.</p>
71965bb18407ff45ada9e47cb6def086e48663c6Pavel Březina <li><directive>MaxRequestsPerChild</directive> has been renamed to
71965bb18407ff45ada9e47cb6def086e48663c6Pavel Březina <directive module="mpm_common">MaxConnectionsPerChild</directive>,
71965bb18407ff45ada9e47cb6def086e48663c6Pavel Březina which describes more accurately what it does.</li>
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <li>The <directive module="core">DefaultType</directive>
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina directive no longer has any effect, other than to emit a
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina warning if it's used with any value other than
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <code>none</code>. You need to use other configuration
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina settings to replace it in 2.4.
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <li><directive module="core">EnableSendfile</directive> now
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina defaults to Off.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina href="modules/mod_log_config.html#formats">${cookie}C</a>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina matches whole cookie names. Previously any substring would
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <li><module>mod_dav_fs</module>: The format of the <directive
df9e9a1f9b7dc255eb62c390163c25917b08f5a2Lukas Slebodnik module="dav_fs">DavLockDB</directive> file has changed for
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina systems with inodes. The old <directive
c19374b2a9b676ca534f52ef76d80f0945fe8fb2Pavel Březina module="dav_fs">DavLockDB</directive> file must be deleted on
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><directive module="core">KeepAlive</directive> only
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina accepts values of <code>On</code> or <code>Off</code>.
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina Previously, any value other than "Off" or "0" was treated as
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina SSLStaplingMutex, and WatchdogMutexPath have been replaced
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina with a single <directive module="core">Mutex</directive>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina directive. You will need to evaluate any use of these removed
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina directives in your 2.2 configuration to determine if they can
6c2e507bd1571f9c7e26c5c9d60753b29fb75578Jakub Hrozek just be deleted or will need to be replaced using <directive
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina module="cache">CacheIgnoreURLSessionIdentifiers</directive>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina now does an exact match against the query string instead of a
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina partial match. If your configuration was using partial
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina strings, e.g. using <code>sessionid</code> to match
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <code>/someapplication/image.gif;jsessionid=123456789</code>,
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina then you will need to change to the full string
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina module="ldap">LDAPTrustedClientCert</directive> is now
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina consistently a per-directory setting only. If you use this
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina directive, review your configuration to make sure it is
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina present in all the necessary directory contexts.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina module="filter">FilterProvider</directive> syntax has changed and
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina now uses a boolean expression to determine if a filter is applied.
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><module>mod_include</module>: An SSI* config directive in directory
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina scope no longer causes all other per-directory SSI* directives to be
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina reset to their default values.
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <li><module>mod_autoindex</module>: will now extract titles and
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina display descriptions for .xhtml files, which were previously
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina ignored.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><module>mod_ssl</module>: The default format of the <code>*_DN</code>
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina variables has changed. The old format can still be used with the new
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <code>LegacyDNStringFormat</code> argument to <directive
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina <li><program>htpasswd</program> now uses MD5 hash by default on
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina all platforms.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>The <directive module="core">NameVirtualHost</directive>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina directive no longer has any effect, other than to emit a
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina warning. Any address/port combination appearing in multiple
8be4efb91f9af1bf49628c497a9de4b258bb893ePavel Březina virtual hosts is implicitly treated as a name-based virtual host.
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <p>All modules must be recompiled for 2.4 before being loaded.</p>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <p>Many third-party modules designed for version 2.2 will
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina otherwise work unchanged with the Apache HTTP Server version 2.4.
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina Some will require changes; see the <a href="developer/new_api_2_4.html">API
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><code>Invalid command 'User', perhaps misspelled or defined by a module not included in the server configuration</code> - load module <module>mod_unixd</module></li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina<code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina and replace with other configuration settings.</li>
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li>Errors serving requests:
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina <li><code>configuration error: couldn't check user: /path</code> -
3688374991afb34bbaf2b7843683fc13dd77879dPavel Březina load module <module>mod_authn_core</module>.</li>