| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| 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 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_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_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>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> |
| |
| <section id="authz"> |
| <title>Authorization</title> |
| |
| <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><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>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> |