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.5</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.5</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: By default, only a basic set of modules is loaded. The
  80       other <code class="directive">LoadModule</code> directives are commented
  81       out.</li>
  82
  83       <li>configure: the "most" module set gets built by default</li>
  84
  85       <li>configure: the "reallyall" module set adds developer modules
  86       to the "all" set</li>
  87     </ul>
  88
  89   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  90 <div class="section">
  91 <h2><a name="run-time" id="run-time">Run-Time Configuration Changes</a></h2>
  92
  93     <p>There have been significant changes in authorization configuration,
  94     and other minor configuration changes, that could require changes to your 2.2
  95     configuration files before using them for 2.4.</p>
  96
  97     <h3><a name="authz" id="authz">Authorization</a></h3>
  98
  99
 100       <p>Any configuration file that uses authorization will likely
 101       need changes.</p>
 102
 103     <p>You should review the <a href="howto/auth.html">Authentication,
 104     Authorization and Access Control Howto</a>, especially the section
 105     <a href="howto/auth.html#beyond">Beyond just authorization</a>
 106     which explains the new mechanisms for controlling the order in
 107     which the authorization directives are applied.</p>
 108
 109     <h4><a name="access" id="access">Access control</a></h4>
 110
 111
 112       <p>In 2.2, access control based on client hostname, IP address,
 113       and other characteristics of client requests was done using the
 114       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>
 115
 116       <p>In 2.4, such access control is done in the same way as other
 117       authorization checks, using the new module
 118       <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code>.  The old access control idioms
 119       should be replaced by the new authentication mechanisms,
 120       although for compatibility with old configurations, the new
 121       module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p>
 122
 123       <p>Here are some examples of old and new ways to do the same
 124       access control.</p>
 125
 126       <p>In this example, all requests are denied.</p>
 127       <div class="example"><h3>2.2 configuration:</h3><p><code>
 128
 129         Order deny,allow<br />
 130         Deny from all
 131       </code></p></div>
 132       <div class="example"><h3>2.4 configuration:</h3><p><code>
 133
 134         Require all denied
 135       </code></p></div>
 136
 137       <p>In this example, all requests are allowed.</p>
 138       <div class="example"><h3>2.2 configuration:</h3><p><code>
 139
 140         Order allow,deny<br />
 141         Allow from all
 142       </code></p></div>
 143       <div class="example"><h3>2.4 configuration:</h3><p><code>
 144
 145         Require all granted
 146       </code></p></div>
 147
 148       <p>In the following example, all hosts in the example.org domain
 149       are allowed access; all other hosts are denied access.</p>
 150
 151       <div class="example"><h3>2.2 configuration:</h3><p><code>
 152
 153         Order Deny,Allow<br />
 154         Deny from all<br />
 155         Allow from example.org
 156       </code></p></div>
 157       <div class="example"><h3>2.4 configuration:</h3><p><code>
 158
 159         Require host example.org
 160       </code></p></div>
 161
 162
 163
 164
 165     <h3><a name="config" id="config">Other configuration changes</a></h3>
 166
 167
 168       <p>Some other small adjustments may be necessary for particular
 169       configurations as discussed below.</p>
 170
 171       <ul>
 172         <li><code class="directive">MaxRequestsPerChild</code> has been renamed to
 173         <code class="directive"><a href="./mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>,
 174         describes more accurately what it does. The old name is still
 175         supported.</li>
 176
 177         <li><code class="directive">MaxClients</code> has been renamed to
 178         <code class="directive"><a href="./mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
 179         which describes more accurately what it does. For async MPMs, like
 180         <code class="module"><a href="./mod/event.html">event</a></code>, the maximum number of clients is not
 181         equivalent than the number of worker threads. The old name is still
 182         supported.</li>
 183
 184         <li>The <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
 185         directive no longer has any effect, other than to emit a
 186         warning if it's used with any value other than
 187         <code>none</code>.  You need to use other configuration
 188         settings to replace it in 2.4.
 189         </li>
 190
 191         <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
 192         defaults to Off.</li>
 193
 194         <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
 195         defaults to "MTime Size" (without INode).</li>
 196
 197         <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>
 198         matches whole cookie names.  Previously any substring would
 199         match.</li>
 200
 201         <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
 202         systems with inodes.  The old <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file must be deleted on
 203         upgrade.
 204         </li>
 205
 206         <li><code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> only
 207         accepts values of <code>On</code> or <code>Off</code>.
 208         Previously, any value other than "Off" or "0" was treated as
 209         "On".</li>
 210
 211         <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
 212         SSLStaplingMutex, and WatchdogMutexPath have been replaced
 213         with a single <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>
 214         directive.  You will need to evaluate any use of these removed
 215         directives in your 2.2 configuration to determine if they can
 216         just be deleted or will need to be replaced using <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>.</li>
 217
 218         <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>
 219         now does an exact match against the query string instead of a
 220         partial match.  If your configuration was using partial
 221         strings, e.g. using <code>sessionid</code> to match
 222         <code>/someapplication/image.gif;jsessionid=123456789</code>,
 223         then you will need to change to the full string
 224         <code>jsessionid</code>.
 225         </li>
 226
 227         <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
 228         consistently a per-directory setting only.  If you use this
 229         directive, review your configuration to make sure it is
 230         present in all the necessary directory contexts.</li>
 231
 232         <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
 233         now uses a boolean expression to determine if a filter is applied.
 234         </li>
 235
 236         <li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code>:
 237             <ul>
 238             <li>The <code>#if expr</code> element now uses the new <a href="expr.html">expression parser</a>. The old syntax can be
 239             restored with the new directive <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code>.
 240             </li>
 241             <li>An SSI* config directive in directory scope no longer causes
 242             all other per-directory SSI* directives to be reset to their
 243             default values.</li>
 244             </ul>
 245         </li>
 246
 247         <li><code class="module"><a href="./mod/mod_charset_lite.html">mod_charset_lite</a></code>: The <code>DebugLevel</code>
 248         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 249         </li>
 250
 251         <li><code class="module"><a href="./mod/mod_ext-filter.html">mod_ext-filter</a></code>: The <code>DebugLevel</code>
 252         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 253         </li>
 254
 255         <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: CRL based revocation checking
 256         now needs to be explicitly configured through <code class="directive"><a href="./mod/mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck</a></code>.
 257         </li>
 258
 259         <li><code class="module"><a href="./mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now
 260         limited to 1MB.
 261         </li>
 262
 263         <li><code class="module"><a href="./mod/mod_reqtimeout.html">mod_reqtimeout</a></code>: If the module is loaded, it
 264         will now set some default timeouts.</li>
 265
 266       </ul>
 267
 268   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 269 <div class="section">
 270 <h2><a name="misc" id="misc">Misc Changes</a></h2>
 271
 272
 273     <ul>
 274       <li><code class="module"><a href="./mod/mod_autoindex.html">mod_autoindex</a></code>: will now extract titles and
 275       display descriptions for .xhtml files, which were previously
 276       ignored.</li>
 277
 278       <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: The default format of the <code>*_DN</code>
 279       variables has changed. The old format can still be used with the new
 280       <code>LegacyDNStringFormat</code> argument to <code class="directive"><a href="./mod/mod_ssl.html#ssloptions">SSLOptions</a></code>. The SSLv2 protocol is
 281       no longer supported.</li>
 282
 283       <li><code class="program"><a href="./programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on
 284       all platforms.</li>
 285
 286       <li>The <code class="directive"><a href="./mod/core.html#namevirtualhost">NameVirtualHost</a></code>
 287       directive no longer has any effect, other than to emit a
 288       warning.  Any address/port combination appearing in multiple
 289       virtual hosts is implicitly treated as a name-based virtual host.
 290       </li>
 291
 292       <li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will now skip compression if it knows
 293       that the size overhead added by the compression is larger than the data
 294       to be compressed.
 295       </li>
 296
 297       <li>Multi-language error documents from 2.2.x may not work unless
 298       they are adjusted to the new syntax of <code class="module"><a href="./mod/mod_include.html">mod_include</a></code>'s
 299       <code>#if expr=</code> element or the directive
 300       <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code> is
 301       enabled for the directory containing the error documents.
 302       </li>
 303
 304     </ul>
 305
 306   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 307 <div class="section">
 308 <h2><a name="third-party" id="third-party">Third Party Modules</a></h2>
 309
 310     <p>All modules must be recompiled for 2.4 before being loaded.</p>
 311
 312     <p>Many third-party modules designed for version 2.2 will
 313     otherwise work unchanged with the Apache HTTP Server version 2.4.
 314     Some will require changes; see the <a href="developer/new_api_2_4.html">API
 315     update</a> overview.</p>
 316   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 317 <div class="section">
 318 <h2><a name="commonproblems" id="commonproblems">Common problems when upgrading</a></h2>
 319
 320     <ul><li>Startup errors:
 321     <ul>
 322       <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>
 323       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
 324 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
 325  - 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>
 326       <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>
 327       and replace with other configuration settings.</li>
 328     </ul></li>
 329     <li>Errors serving requests:
 330     <ul>
 331       <li><code>configuration error:  couldn't check user: /path</code> -
 332       load module <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.</li>
 333     </ul>
 334     </li>
 335 </ul>
 336   </div></div>
 337 <div class="bottomlang">
 338 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
 339 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 340 </div><div id="footer">
 341 <p class="apache">Copyright 2012 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>
 342 <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>
 343 </body></html>