<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
-<manualpage>
-<relativepath href="."/>
+<!-- $LastChangedRevision$ -->
-<title>Upgrading to 2.0 from 1.3</title>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manualpage metafile="upgrading.xml.meta">
+
+<title>Upgrading to 2.4 from 2.2</title>
<summary>
<p>In order to assist folks upgrading, we maintain a document
- describing information critical to existing Apache users. These
+ describing information critical to existing Apache HTTP Server users. These
are intended to be brief notes, and you should be able to find
more information in either the <a
- href="new_features_2_0.html">New Features</a> document, or in
- the <code>src/CHANGES</code> file.</p>
+ href="new_features_2_4.html">New Features</a> document, or in
+ the <code>src/CHANGES</code> file. Application and module developers
+ can find a summary of API changes in the <a href="developer/new_api_2_4.html"
+ >API updates</a> overview.</p>
+
+ <p>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.</p>
+
+ <p>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 <a
+ href="http://httpd.apache.org/docs/2.2/upgrading.html">2.0 to 2.2
+ upgrading document.</a></p>
+
</summary>
-<seealso><a href="new_features_2_0.html">New Features in 2.0</a></seealso>
+<seealso><a href="new_features_2_4.html">Overview of new features in
+ Apache HTTP Server 2.4</a></seealso>
<section id="compile-time">
<title>Compile-Time Configuration Changes</title>
+ <p>The compilation process is very similar to the one used in
+ version 2.2. Your old <code>configure</code> command line (as
+ found in <code>build/config.nice</code> in the installed server
+ directory) can be used in most cases. There are some changes in
+ the default settings. Some details of changes:</p>
+
<ul>
- <li>Apache now uses an <code>autoconf</code> and
- <code>libtool</code> system for <a
- href="install.html">configuring the build processes</a>.
- Using this system is similar to, but not the same as, using
- the APACI system in Apache 1.3.</li>
-
- <li>In addition to the usual selection of modules which you
- can choose to compile, Apache 2.0 has moved the main part of
- request processing into <a href="mpm.html">Multi-Processing
- Modules</a> (MPMs).</li>
+ <li>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 <module>mod_cache_disk</module> in
+ 2.4.</li>
+
+ <li>All load balancing implementations have been moved to
+ individual, self-contained mod_proxy submodules, e.g.
+ <module>mod_lbmethod_bybusyness</module>. You might need
+ to build and load any of these that your configuration
+ uses.</li>
+
+ <li>Platform support has been removed for BeOS, TPF, and
+ even older platforms such as A/UX, Next, and Tandem. These were
+ believed to be broken anyway.</li>
+
+ <li>configure: dynamic modules (DSO) are built by default</li>
+
+ <li>configure: By default, only a basic set of modules is loaded. The
+ other <directive>LoadModule</directive> directives are commented
+ out in the configuration file.</li>
+
+ <li>configure: the "most" module set gets built by default</li>
+
+ <li>configure: the "reallyall" module set adds developer modules
+ to the "all" set</li>
</ul>
+
</section>
<section id="run-time">
<title>Run-Time Configuration Changes</title>
+ <p>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.</p>
- <ul>
- <li>Many directives that were in the core server in Apache
- 1.3 are now in the MPMs. If you wish the behavior of the
- server to be as similar as possible to the behavior of Apache
- 1.3, you should select the <module>prefork</module> MPM. Other MPMs
- will have different directives to control process creation and request
- processing.</li>
-
- <li>The <a href="mod/mod_proxy.html">proxy module</a> has been
- revamped to bring it up to HTTP/1.1. Among the important changes,
- proxy access control is now placed inside a <directive type="section"
- module="mod_proxy">Proxy</directive> block rather than a
- <code><Directory proxy:></code> block.</li>
-
- <li>The handling of <code>PATH_INFO</code> (trailing path information
- after the true filename) has changed for some modules. Modules
- that were previously implemented as a handler but are now
- implemented as a filter may no longer accept requests with
- <code>PATH_INFO</code>. Filters such as <a
- href="mod/mod_include.html">INCLUDES</a> are implemented on top
- of the core handler, and therefore reject requests with
- <code>PATH_INFO</code>. You can use the <directive
- module="core">AcceptPathInfo</directive> directive to
- force the core handler to accept requests with <code>PATH_INFO</code>
- and thereby restore the ability to use <code>PATH_INFO</code> in
- server-side includes.</li>
-
- <li>The <directive
- module="mod_negotiation">CacheNegotiatedDocs</directive>
- directive now takes the argument <code>on</code> or
- <code>off</code>. Existing instances of <directive
- >CacheNegotiatedDocs</directive> should be
- replaced with <code>CacheNegotiatedDocs on</code>.</li>
-
- <li>
- The <directive module="core">ErrorDocument</directive>
- directive no longer uses a quote at the beginning of the
- argument to indicate a text message. Instead, you should
- enclose the message in double quotes. For example, existing
- instances of
-
- <example>
- ErrorDocument 403 "Some Message
- </example>
- should be replaced with
-
- <example>
- ErrorDocument 403 "Some Message"
- </example>
-
- As long as the second argument is not a valid URL or
- pathname, it will be treated as a text message.
- </li>
+ <section id="authz">
+ <title>Authorization</title>
- <li>The <code>AccessConfig</code> and
- <code>ResourceConfig</code> directives no longer exist.
- Existing instances of these directives can be replaced with
- the <directive module="core">Include</directive>
- directive which has equivalent functionality. If you were
- making use of the default values of these directives without
- including them in the configuration files, you may need to
- add <code>Include conf/access.conf</code> and <code>Include
- conf/srm.conf</code> to your <code>httpd.conf</code>. In order to
- assure that Apache reads the configuration files in the same order
- as was implied by the older directives, the <directive
- module="core">Include</directive> directives should be placed at the end
- of <code>httpd.conf</code>, with the one for <code>srm.conf</code>
- preceding the one for <code>access.conf</code>.</li>
-
- <li>The <code>BindAddress</code> and <code>Port</code>
- directives no longer exist. Equivalent functionality is
- provided with the more flexible
- <directive module="mpm_common">Listen</directive>
- directive.</li>
-
- <li>Another use of the <code>Port</code>
- directive in Apache-1.3 was setting the port number to be used
- in self-referential URL's. The Apache-2.0 equivalent is
- the new <directive module="core">ServerName</directive>
- syntax: it has been changed to allow specifying both the
- hostname <em>and</em> the port number for self-referential URL's
- in one directive.</li>
-
- <li>The <code>ServerType</code> directive no longer exists.
- The method used to serve requests is now determined by the
- selection of MPM. There is currently no MPM designed to be
- launched by inetd.</li>
-
- <li>The <code>mod_log_agent</code> and <code>mod_log_referer</code>
- modules which provided the <code>AgentLog</code>,
- <code>RefererLog</code> and <code>RefererIgnore</code> directives have
- been removed. Agent and referer logs are still available using the
- <directive module="mod_log_config">CustomLog</directive>
- directive of <module>mod_log_config</module>.</li>
-
- <li>The <code>AddModule</code> and
- <code>ClearModuleList</code> directives no longer exist.
- These directives were 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.</li>
-
- <li>The <code>FancyIndexing</code> directive has been removed.
- The same functionality is available through the
- <code>FancyIndexing</code> option to the <directive
- module="mod_autoindex">IndexOptions</directive>
- directive.</li>
- </ul>
+ <p>Any configuration file that uses authorization will likely
+ need changes.</p>
+
+ <p>You should review the <a href="howto/auth.html">Authentication,
+ Authorization and Access Control Howto</a>, especially the section
+ <a href="howto/auth.html#beyond">Beyond just authorization</a>
+ which explains the new mechanisms for controlling the order in
+ which the authorization directives are applied.</p>
+
+ <p>Directives that control how authorization modules respond when they don't match
+ the authenticated user have been removed: This includes
+ AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative,
+ AuthzGroupFileAuthoritative, AuthzUserAuthoritative,
+ and AuthzOwnerAuthoritative. These directives have been replaced by the
+ more expressive <directive module="mod_authz_core">RequireAny</directive>,
+ <directive module="mod_authz_core">RequireNone</directive>, and
+ <directive module="mod_authz_core">RequireAll</directive>.</p>
+
+ <p>If you use <module>mod_authz_dbm</module>, you must port your
+ configuration to use <code>Require dbm-group ...</code> in place
+ of <code>Require group ...</code>.</p>
+
+ <section id="access">
+ <title>Access control</title>
+
+ <p>In 2.2, access control based on client hostname, IP address,
+ and other characteristics of client requests was done using the
+ directives <directive
+ module="mod_access_compat">Order</directive>, <directive
+ module="mod_access_compat">Allow</directive>, <directive
+ module="mod_access_compat">Deny</directive>, and <directive
+ module="mod_access_compat">Satisfy</directive>.</p>
+
+ <p>In 2.4, such access control is done in the same way as other
+ authorization checks, using the new module
+ <module>mod_authz_host</module>. The old access control idioms
+ should be replaced by the new authentication mechanisms,
+ although for compatibility with old configurations, the new
+ module <module>mod_access_compat</module> is provided.</p>
+
+ <note><title>Mixing old and new directives</title>
+ <p>Mixing old directives like <directive
+ module="mod_access_compat">Order</directive>, <directive
+ module="mod_access_compat">Allow</directive> or <directive
+ module="mod_access_compat">Deny</directive> with new ones like
+ <directive
+ module="mod_authz_core">Require</directive> is technically possible
+ but discouraged. <module>mod_access_compat</module> was created to support
+ configurations containing only old directives to facilitate the 2.4 upgrade.
+ Please check the examples below to get a better idea about issues that might arise.
+ </p>
+ </note>
+
+ <p>Here are some examples of old and new ways to do the same
+ access control.</p>
+
+ <p>In this example, all requests are denied.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ <highlight language="config">
+Order deny,allow
+Deny from all
+ </highlight>
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ <highlight language="config">
+ Require all denied
+ </highlight>
+ </example>
+
+ <p>In this example, all requests are allowed.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ <highlight language="config">
+Order allow,deny
+Allow from all
+ </highlight>
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ <highlight language="config">
+ Require all granted
+ </highlight>
+ </example>
+
+ <p>In the following example, all hosts in the example.org domain
+ are allowed access; all other hosts are denied access.</p>
+
+ <example>
+ <title>2.2 configuration:</title>
+ <highlight language="config">
+Order Deny,Allow
+Deny from all
+Allow from example.org
+ </highlight>
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ <highlight language="config">
+ Require host example.org
+ </highlight>
+ </example>
+
+ <p>In the following example, mixing old and new directives leads to
+ unexpected results.</p>
+
+ <example>
+ <title>Mixing old and new directives: NOT WORKING AS EXPECTED</title>
+ <highlight language="config">
+DocumentRoot "/var/www/html"
+
+<Directory "/">
+ AllowOverride None
+ Order deny,allow
+ Deny from all
+</Directory>
+
+<Location "/server-status">
+ SetHandler server-status
+ Require 127.0.0.1
+</Location>
+
+access.log - GET /server-status 403 127.0.0.1
+error.log - AH01797: client denied by server configuration: /var/www/html/server-status
+ </highlight>
+ </example>
+ <p>Why httpd denies access to servers-status even if the configuration seems to allow it?
+ Because <module>mod_access_compat</module> directives take precedence
+ over the <module>mod_authz_host</module> one in this configuration
+ <a href="sections.html#merging">merge</a> scenario.</p>
+
+ <p>This example conversely works as expected:</p>
+
+ <example>
+ <title>Mixing old and new directives: WORKING AS EXPECTED</title>
+ <highlight language="config">
+DocumentRoot "/var/www/html"
+
+<Directory "/">
+ AllowOverride None
+ Require all denied
+</Directory>
+
+<Location "/server-status">
+ SetHandler server-status
+ Order deny,allow
+ Deny from all
+ Allow From 127.0.0.1
+</Location>
+
+access.log - GET /server-status 200 127.0.0.1
+ </highlight>
+ </example>
+ <p>So even if mixing configuration is still
+ possible, please try to avoid it when upgrading: either keep old directives and then migrate
+ to the new ones on a later stage or just migrate everything in bulk.
+ </p>
+ </section>
+
+ </section>
+
+ <section id="config">
+ <title>Other configuration changes</title>
+
+ <p>Some other small adjustments may be necessary for particular
+ configurations as discussed below.</p>
+
+ <ul>
+ <li><directive>MaxRequestsPerChild</directive> has been renamed to
+ <directive module="mpm_common">MaxConnectionsPerChild</directive>,
+ describes more accurately what it does. The old name is still
+ supported.</li>
+
+ <li><directive>MaxClients</directive> has been renamed to
+ <directive module="mpm_common">MaxRequestWorkers</directive>,
+ which describes more accurately what it does. For async MPMs, like
+ <module>event</module>, the maximum number of clients is not
+ equivalent than the number of worker threads. The old name is still
+ supported.</li>
+
+ <li>The <directive module="core">DefaultType</directive>
+ directive no longer has any effect, other than to emit a
+ warning if it's used with any value other than
+ <code>none</code>. You need to use other configuration
+ settings to replace it in 2.4.
+ </li>
+
+ <li><directive module="core">AllowOverride</directive> now
+ defaults to <code>None</code>.</li>
+
+ <li><directive module="core">EnableSendfile</directive> now
+ defaults to Off.</li>
+
+ <li><directive module="core">FileETag</directive> now
+ defaults to "MTime Size" (without INode).</li>
+
+ <li><module>mod_dav_fs</module>: The format of the <directive
+ module="mod_dav_fs">DavLockDB</directive> file has changed for
+ systems with inodes. The old <directive
+ module="mod_dav_fs">DavLockDB</directive> file must be deleted on
+ upgrade.
+ </li>
+
+ <li><directive module="core">KeepAlive</directive> only
+ accepts values of <code>On</code> or <code>Off</code>.
+ Previously, any value other than "Off" or "0" was treated as
+ "On".</li>
+
+ <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
+ SSLStaplingMutex, and WatchdogMutexPath have been replaced
+ with a single <directive module="core">Mutex</directive>
+ 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 <directive
+ module="core">Mutex</directive>.</li>
+
+ <li><module>mod_cache</module>: <directive
+ module="mod_cache">CacheIgnoreURLSessionIdentifiers</directive>
+ now does an exact match against the query string instead of a
+ partial match. If your configuration was using partial
+ strings, e.g. using <code>sessionid</code> to match
+ <code>/someapplication/image.gif;jsessionid=123456789</code>,
+ then you will need to change to the full string
+ <code>jsessionid</code>.
+ </li>
+
+ <li><module>mod_cache</module>: The second parameter to
+ <directive module="mod_cache">CacheEnable</directive> only
+ matches forward proxy content if it begins with the correct
+ protocol. In 2.2 and earlier, a parameter of '/' matched all
+ content.</li>
+
+ <li><module>mod_ldap</module>: <directive
+ module="mod_ldap">LDAPTrustedClientCert</directive> 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.</li>
+
+ <li><module>mod_filter</module>: <directive
+ module="mod_filter">FilterProvider</directive> syntax has changed and
+ now uses a boolean expression to determine if a filter is applied.
+ </li>
+
+ <li><module>mod_include</module>:
+ <ul>
+ <li>The <code>#if expr</code> element now uses the new <a
+ href="expr.html">expression parser</a>. The old syntax can be
+ restored with the new directive <directive module="mod_include"
+ >SSILegacyExprParser</directive>.
+ </li>
+ <li>An SSI* config directive in directory scope no longer causes
+ all other per-directory SSI* directives to be reset to their
+ default values.</li>
+ </ul>
+ </li>
+
+ <li><module>mod_charset_lite</module>: The <code>DebugLevel</code>
+ option has been removed in favour of per-module <directive
+ module="core">LogLevel</directive> configuration.
+ </li>
+
+ <li><module>mod_ext_filter</module>: The <code>DebugLevel</code>
+ option has been removed in favour of per-module <directive
+ module="core">LogLevel</directive> configuration.
+ </li>
+
+ <li><module>mod_proxy_scgi</module>: The default setting for
+ <code>PATH_INFO</code> has changed from httpd 2.2, and
+ some web applications will no longer operate properly with
+ the new <code>PATH_INFO</code> setting. The previous setting
+ can be restored by configuring the <code>proxy-scgi-pathinfo</code>
+ variable.</li>
+
+ <li><module>mod_ssl</module>: CRL based revocation checking
+ now needs to be explicitly configured through <directive
+ module="mod_ssl">SSLCARevocationCheck</directive>.
+ </li>
+
+ <li><module>mod_substitute</module>: The maximum line length is now
+ limited to 1MB.
+ </li>
+
+ <li><module>mod_reqtimeout</module>: If the module is loaded, it
+ will now set some default timeouts.</li>
+
+ <li><module>mod_dumpio</module>: <directive>DumpIOLogLevel</directive>
+ is no longer supported. Data is always logged at <directive
+ module="core">LogLevel</directive> <code>trace7</code>.</li>
+
+ <li>On Unix platforms, piped logging commands configured using
+ either <directive module="core">ErrorLog</directive> or
+ <directive module="mod_log_config">CustomLog</directive> were invoked using
+ <code>/bin/sh -c</code> in 2.2 and earlier. In 2.4 and later,
+ piped logging commands are executed directly. To restore the
+ old behaviour, see the <a href="logs.html#piped">piped logging
+ documentation</a>.</li>
+
+ </ul>
+ </section>
</section>
<section id="misc">
<title>Misc Changes</title>
<ul>
- <li>The <code>httpd</code> command line option
- <code>-S</code> which was used for printing the virtual host
- configuration has been replaced by <code>-t -D
- DUMP_VHOSTS</code>.</li>
-
- <li>The module <module>mod_auth_digest</module>, which was
- experimental in Apache 1.3, is now a standard module.</li>
-
- <li>The <code>mod_mmap_static</code> module, which was experimental in
- Apache 1.3, has been replaced with <module>mod_file_cache</module>.</li>
-
- <li>The distribution has been completely reorganized so that
- it no longer contains an independent <code>src</code>
- directory. Instead, the sources are logically organized under
- the main distribution directory, and installations of the
- compiled server should be directed to a separate
- directory.</li>
+ <li><module>mod_autoindex</module>: will now extract titles and
+ display descriptions for .xhtml files, which were previously
+ ignored.</li>
+
+ <li><module>mod_ssl</module>: The default format of the <code>*_DN</code>
+ variables has changed. The old format can still be used with the new
+ <code>LegacyDNStringFormat</code> argument to <directive
+ module="mod_ssl">SSLOptions</directive>. The SSLv2 protocol is
+ no longer supported. <directive module="mod_ssl">SSLProxyCheckPeerCN
+ </directive> and <directive module="mod_ssl">SSLProxyCheckPeerExpire
+ </directive> now default to On, causing proxy requests to HTTPS hosts
+ with bad or outdated certificates to fail with a 502 status code (Bad
+ gateway)</li>
+
+ <li><program>htpasswd</program> now uses MD5 hash by default on
+ all platforms.</li>
+
+ <li>The <directive module="core">NameVirtualHost</directive>
+ directive no longer has any effect, other than to emit a
+ warning. Any address/port combination appearing in multiple
+ virtual hosts is implicitly treated as a name-based virtual host.
+ </li>
+
+ <li><module>mod_deflate</module> will now skip compression if it knows
+ that the size overhead added by the compression is larger than the data
+ to be compressed.
+ </li>
+
+ <li>Multi-language error documents from 2.2.x may not work unless
+ they are adjusted to the new syntax of <module>mod_include</module>'s
+ <code>#if expr=</code> element or the directive
+ <directive module="mod_include">SSILegacyExprParser</directive> is
+ enabled for the directory containing the error documents.
+ </li>
+
+ <li>The functionality provided by <code>mod_authn_alias</code>
+ in previous versions (i.e., the <directive
+ module="mod_authn_core">AuthnProviderAlias</directive> directive)
+ has been moved into <module>mod_authn_core</module>.
+ </li>
+
+ <li><module>mod_cgid</module> uses the servers <directive module="core"
+ >Timeout</directive> to limit the length of time to wait for CGI output.
+ This timeout can be overridden with <directive module="mod_cgid">
+ CGIDScriptTImeout</directive>.
+ </li>
+
</ul>
+
</section>
<section id="third-party">
<title>Third Party Modules</title>
+ <p>All modules must be recompiled for 2.4 before being loaded.</p>
- <p>Extensive changes were made to the server API in Apache 2.0.
- Existing modules designed for the Apache 1.3 API will
- <strong>not</strong> work in Apache 2.0 without modification.
- Details are provided in the <a href="developer/">developer
- documentation</a>.</p>
+ <p>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 <a href="developer/new_api_2_4.html">API
+ update</a> overview.</p>
+ </section>
+
+ <section id="commonproblems">
+ <title>Common problems when upgrading</title>
+ <ul><li>Startup errors:
+ <ul>
+ <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>
+ <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
+<code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
+ - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
+ <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
+ and replace with other configuration settings.</li>
+ <li><code>Invalid command 'AddOutputFilterByType', perhaps misspelled
+ or defined by a module not included in the server configuration
+ </code> - <directive module="mod_filter">AddOutputFilterByType</directive>
+ has moved from the core to mod_filter, which must be loaded.</li>
+ </ul></li>
+ <li>Errors serving requests:
+ <ul>
+ <li><code>configuration error: couldn't check user: /path</code> -
+ load module <module>mod_authn_core</module>.</li>
+ <li><code>.htaccess</code> files aren't being processed - Check for an
+ appropriate <directive module="core">AllowOverride</directive> directive;
+ the default changed to <code>None</code> in 2.4.</li>
+ </ul>
+ </li>
+</ul>
</section>
</manualpage>
projects / apache / blobdiff