granicus.if.org Git - apache/blob - docs/manual/upgrading.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Upgrading to 2.4 from 2.2 - Apache HTTP Server</title>
   9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.3</p>
  16 <img alt="" src="./images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Upgrading to 2.4 from 2.2</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  23 </div>
  24
  25   <p>In order to assist folks upgrading, we maintain a document
  26   describing information critical to existing Apache HTTP Server users. These
  27   are intended to be brief notes, and you should be able to find
  28   more information in either the <a href="new_features_2_4.html">New Features</a> document, or in
  29   the <code>src/CHANGES</code> file.  Application and module developers
  30   can find a summary of API changes in the <a href="developer/new_api_2_4.html">API updates</a> overview.</p>
  31
  32   <p>This document describes changes in server behavior that might
  33   require you to change your configuration or how you use the server
  34   in order to continue using 2.4 as you are currently using 2.2.
  35   To take advantage of new features in 2.4, see the New Features
  36   document.</p>
  37
  38   <p>This document describes only the changes from 2.2 to 2.4.  If you
  39   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
  40   upgrading document.</a></p>
  41
  42 </div>
  43 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#compile-time">Compile-Time Configuration Changes</a></li>
  44 <li><img alt="" src="./images/down.gif" /> <a href="#run-time">Run-Time Configuration Changes</a></li>
  45 <li><img alt="" src="./images/down.gif" /> <a href="#misc">Misc Changes</a></li>
  46 <li><img alt="" src="./images/down.gif" /> <a href="#third-party">Third Party Modules</a></li>
  47 <li><img alt="" src="./images/down.gif" /> <a href="#commonproblems">Common problems when upgrading</a></li>
  48 </ul><h3>See also</h3><ul class="seealso"><li><a href="new_features_2_4.html">Overview of new features in
  49   Apache HTTP Server 2.4</a></li></ul></div>
  50 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  51 <div class="section">
  52 <h2><a name="compile-time" id="compile-time">Compile-Time Configuration Changes</a></h2>
  53
  54
  55     <p>The compilation process is very similar to the one used in
  56     version 2.2.  Your old <code>configure</code> command line (as
  57     found in <code>build/config.nice</code> in the installed server
  58     directory) can be used in most cases.  There are some changes in
  59     the default settings.  Some details of changes:</p>
  60
  61     <ul>
  62       <li>These modules have been removed: mod_authn_default,
  63       mod_authz_default, mod_mem_cache.  If you were using
  64       mod_mem_cache in 2.2, look at <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> in
  65       2.4.</li>
  66
  67       <li>All load balancing implementations have been moved to
  68       individual, self-contained mod_proxy submodules, e.g.
  69       <code class="module"><a href="./mod/mod_lbmethod_bybusyness.html">mod_lbmethod_bybusyness</a></code>.  You might need
  70       to build and load any of these that your configuration
  71       uses.</li>
  72
  73       <li>Platform support has been removed for BeOS, TPF, and
  74       even older platforms such as A/UX, Next, and Tandem.  These were
  75       believed to be broken anyway.</li>
  76
  77       <li>configure: dynamic modules (DSO) are built by default</li>
  78
  79       <li>configure: the "most" module set gets built by default</li>
  80     </ul>
  81
  82   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  83 <div class="section">
  84 <h2><a name="run-time" id="run-time">Run-Time Configuration Changes</a></h2>
  85
  86     <p>There have been significant changes in authorization configuration,
  87     and other minor configuration changes, that could require changes to your 2.2
  88     configuration files before using them for 2.4.</p>
  89
  90     <h3><a name="authz" id="authz">Authorization</a></h3>
  91
  92
  93       <p>Any configuration file that uses authorization will likely
  94       need changes.</p>
  95
  96     <p>You should review the <a href="howto/auth.html">Authentication,
  97     Authorization and Access Control Howto</a>, especially the section
  98     <a href="howto/auth.html#beyond">Beyond just authorization</a>
  99     which explains the new mechanisms for controlling the order in
 100     which the authorization directives are applied.</p>
 101
 102     <h4><a name="access" id="access">Access control</a></h4>
 103
 104
 105       <p>In 2.2, access control based on client hostname, IP address,
 106       and other characteristics of client requests was done using the
 107       directives <code class="directive"><a href="./mod/mod_access_compat.html#order">Order</a></code>, <code class="directive"><a href="./mod/mod_access_compat.html#allow">Allow</a></code>, <code class="directive"><a href="./mod/mod_access_compat.html#deny">Deny</a></code>, and <code class="directive"><a href="./mod/mod_access_compat.html#satisfy">Satisfy</a></code>.</p>
 108
 109       <p>In 2.4, such access control is done in the same way as other
 110       authorization checks, using the new module
 111       <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code>.  The old access control idioms
 112       should be replaced by the new authentication mechanisms,
 113       although for compatibility with old configurations, the new
 114       module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p>
 115
 116       <p>Here are some examples of old and new ways to do the same
 117       access control.</p>
 118
 119       <p>In this example, all requests are denied.</p>
 120       <div class="example"><h3>2.2 configuration:</h3><p><code>
 121
 122         Order deny,allow<br />
 123         Deny from all
 124       </code></p></div>
 125       <div class="example"><h3>2.4 configuration:</h3><p><code>
 126
 127         Require all denied
 128       </code></p></div>
 129
 130       <p>In this example, all requests are allowed.</p>
 131       <div class="example"><h3>2.2 configuration:</h3><p><code>
 132
 133         Order allow,deny<br />
 134         Allow from all
 135       </code></p></div>
 136       <div class="example"><h3>2.4 configuration:</h3><p><code>
 137
 138         Require all granted
 139       </code></p></div>
 140
 141       <p>In the following example, all hosts in the example.org domain
 142       are allowed access; all other hosts are denied access.</p>
 143
 144       <div class="example"><h3>2.2 configuration:</h3><p><code>
 145
 146         Order Deny,Allow<br />
 147         Deny from all<br />
 148         Allow from example.org
 149       </code></p></div>
 150       <div class="example"><h3>2.4 configuration:</h3><p><code>
 151
 152         Require host example.org
 153       </code></p></div>
 154
 155
 156
 157
 158     <h3><a name="config" id="config">Other configuration changes</a></h3>
 159
 160
 161       <p>Some other small adjustments may be necessary for particular
 162       configurations as discussed below.</p>
 163
 164       <ul>
 165         <li><code class="directive">MaxRequestsPerChild</code> has been renamed to
 166         <code class="directive"><a href="./mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>,
 167         describes more accurately what it does. The old name is still
 168         supported.</li>
 169
 170         <li><code class="directive">MaxClients</code> has been renamed to
 171         <code class="directive"><a href="./mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
 172         which describes more accurately what it does. For async MPMs, like
 173         <code class="module"><a href="./mod/event.html">event</a></code>, the maximum number of clients is not
 174         equivalent than the number of worker threads. The old name is still
 175         supported.</li>
 176
 177         <li>The <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
 178         directive no longer has any effect, other than to emit a
 179         warning if it's used with any value other than
 180         <code>none</code>.  You need to use other configuration
 181         settings to replace it in 2.4.
 182         </li>
 183
 184         <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
 185         defaults to Off.</li>
 186
 187         <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
 188         defaults to "MTime Size" (without INode).</li>
 189
 190         <li><code class="module"><a href="./mod/mod_log_config.html">mod_log_config</a></code>: <a href="modules/mod_log_config.html#formats">${cookie}C</a>
 191         matches whole cookie names.  Previously any substring would
 192         match.</li>
 193
 194         <li><code class="module"><a href="./mod/mod_dav_fs.html">mod_dav_fs</a></code>: The format of the <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file has changed for
 195         systems with inodes.  The old <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file must be deleted on
 196         upgrade.
 197         </li>
 198
 199         <li><code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> only
 200         accepts values of <code>On</code> or <code>Off</code>.
 201         Previously, any value other than "Off" or "0" was treated as
 202         "On".</li>
 203
 204         <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
 205         SSLStaplingMutex, and WatchdogMutexPath have been replaced
 206         with a single <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>
 207         directive.  You will need to evaluate any use of these removed
 208         directives in your 2.2 configuration to determine if they can
 209         just be deleted or will need to be replaced using <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>.</li>
 210
 211         <li><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>: <code class="directive"><a href="./mod/mod_cache.html#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></code>
 212         now does an exact match against the query string instead of a
 213         partial match.  If your configuration was using partial
 214         strings, e.g. using <code>sessionid</code> to match
 215         <code>/someapplication/image.gif;jsessionid=123456789</code>,
 216         then you will need to change to the full string
 217         <code>jsessionid</code>.
 218         </li>
 219
 220         <li><code class="module"><a href="./mod/mod_ldap.html">mod_ldap</a></code>: <code class="directive"><a href="./mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code> is now
 221         consistently a per-directory setting only.  If you use this
 222         directive, review your configuration to make sure it is
 223         present in all the necessary directory contexts.</li>
 224
 225         <li><code class="module"><a href="./mod/mod_filter.html">mod_filter</a></code>: <code class="directive"><a href="./mod/mod_filter.html#filterprovider">FilterProvider</a></code> syntax has changed and
 226         now uses a boolean expression to determine if a filter is applied.
 227         </li>
 228
 229         <li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code>:
 230             <ul>
 231             <li>The <code>#if expr</code> element now uses the new <a href="expr.html">expression parser</a>. The old syntax can be
 232             restored with the new directive <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code>.
 233             </li>
 234             <li>An SSI* config directive in directory scope no longer causes
 235             all other per-directory SSI* directives to be reset to their
 236             default values.</li>
 237             </ul>
 238         </li>
 239
 240         <li><code class="module"><a href="./mod/mod_charset_lite.html">mod_charset_lite</a></code>: The <code>DebugLevel</code>
 241         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 242         </li>
 243
 244         <li><code class="module"><a href="./mod/mod_ext-filter.html">mod_ext-filter</a></code>: The <code>DebugLevel</code>
 245         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 246         </li>
 247
 248         <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: CRL based revocation checking
 249         now needs to be explicitly configured through <code class="directive"><a href="./mod/mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck</a></code>.
 250         </li>
 251
 252         <li><code class="module"><a href="./mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now
 253         limited to 1MB.
 254         </li>
 255
 256       </ul>
 257
 258   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 259 <div class="section">
 260 <h2><a name="misc" id="misc">Misc Changes</a></h2>
 261
 262
 263     <ul>
 264       <li><code class="module"><a href="./mod/mod_autoindex.html">mod_autoindex</a></code>: will now extract titles and
 265       display descriptions for .xhtml files, which were previously
 266       ignored.</li>
 267
 268       <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: The default format of the <code>*_DN</code>
 269       variables has changed. The old format can still be used with the new
 270       <code>LegacyDNStringFormat</code> argument to <code class="directive"><a href="./mod/mod_ssl.html#ssloptions">SSLOptions</a></code>.</li>
 271
 272       <li><code class="program"><a href="./programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on
 273       all platforms.</li>
 274
 275       <li>The <code class="directive"><a href="./mod/core.html#namevirtualhost">NameVirtualHost</a></code>
 276       directive no longer has any effect, other than to emit a
 277       warning.  Any address/port combination appearing in multiple
 278       virtual hosts is implicitly treated as a name-based virtual host.
 279       </li>
 280
 281       <li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will now skip compression if it knows
 282       that the size overhead added by the compression is larger than the data
 283       to be compressed.
 284       </li>
 285
 286       <li>Multi-language error documents from 2.2.x may not work unless
 287       they are adjusted to the new syntax of <code class="module"><a href="./mod/mod_include.html">mod_include</a></code>'s
 288       <code>#if expr=</code> element or the directive
 289       <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code> is
 290       enabled for the directory containing the error documents.
 291       </li>
 292
 293     </ul>
 294
 295   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 296 <div class="section">
 297 <h2><a name="third-party" id="third-party">Third Party Modules</a></h2>
 298
 299     <p>All modules must be recompiled for 2.4 before being loaded.</p>
 300
 301     <p>Many third-party modules designed for version 2.2 will
 302     otherwise work unchanged with the Apache HTTP Server version 2.4.
 303     Some will require changes; see the <a href="developer/new_api_2_4.html">API
 304     update</a> overview.</p>
 305   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 306 <div class="section">
 307 <h2><a name="commonproblems" id="commonproblems">Common problems when upgrading</a></h2>
 308
 309     <ul><li>Startup errors:
 310     <ul>
 311       <li><code>Invalid command 'User', perhaps misspelled or defined by a module not included in the server configuration</code> - load module <code class="module"><a href="./mod/mod_unixd.html">mod_unixd</a></code></li>
 312       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
 313 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
 314  - load module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code>, or update configuration to 2.4 authorization directives.</li>
 315       <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
 316       and replace with other configuration settings.</li>
 317     </ul></li>
 318     <li>Errors serving requests:
 319     <ul>
 320       <li><code>configuration error:  couldn't check user: /path</code> -
 321       load module <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.</li>
 322     </ul>
 323     </li>
 324 </ul>
 325   </div></div>
 326 <div class="bottomlang">
 327 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
 328 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 329 </div><div id="footer">
 330 <p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 331 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
 332 </body></html>