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" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" />
  12 <script src="./style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="./images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  21 <div id="path">
  22 <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>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  26 </div>
  27
  28   <p>In order to assist folks upgrading, we maintain a document
  29   describing information critical to existing Apache HTTP Server users. These
  30   are intended to be brief notes, and you should be able to find
  31   more information in either the <a href="new_features_2_4.html">New Features</a> document, or in
  32   the <code>src/CHANGES</code> file.  Application and module developers
  33   can find a summary of API changes in the <a href="developer/new_api_2_4.html">API updates</a> overview.</p>
  34
  35   <p>This document describes changes in server behavior that might
  36   require you to change your configuration or how you use the server
  37   in order to continue using 2.4 as you are currently using 2.2.
  38   To take advantage of new features in 2.4, see the New Features
  39   document.</p>
  40
  41   <p>This document describes only the changes from 2.2 to 2.4.  If you
  42   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
  43   upgrading document.</a></p>
  44
  45 </div>
  46 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#compile-time">Compile-Time Configuration Changes</a></li>
  47 <li><img alt="" src="./images/down.gif" /> <a href="#run-time">Run-Time Configuration Changes</a></li>
  48 <li><img alt="" src="./images/down.gif" /> <a href="#misc">Misc Changes</a></li>
  49 <li><img alt="" src="./images/down.gif" /> <a href="#third-party">Third Party Modules</a></li>
  50 <li><img alt="" src="./images/down.gif" /> <a href="#commonproblems">Common problems when upgrading</a></li>
  51 </ul><h3>See also</h3><ul class="seealso"><li><a href="new_features_2_4.html">Overview of new features in
  52   Apache HTTP Server 2.4</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  53 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  54 <div class="section">
  55 <h2><a name="compile-time" id="compile-time">Compile-Time Configuration Changes</a></h2>
  56
  57
  58     <p>The compilation process is very similar to the one used in
  59     version 2.2.  Your old <code>configure</code> command line (as
  60     found in <code>build/config.nice</code> in the installed server
  61     directory) can be used in most cases.  There are some changes in
  62     the default settings.  Some details of changes:</p>
  63
  64     <ul>
  65       <li>These modules have been removed: mod_authn_default,
  66       mod_authz_default, mod_mem_cache.  If you were using
  67       mod_mem_cache in 2.2, look at <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> in
  68       2.4.</li>
  69
  70       <li>All load balancing implementations have been moved to
  71       individual, self-contained mod_proxy submodules, e.g.
  72       <code class="module"><a href="./mod/mod_lbmethod_bybusyness.html">mod_lbmethod_bybusyness</a></code>.  You might need
  73       to build and load any of these that your configuration
  74       uses.</li>
  75
  76       <li>Platform support has been removed for BeOS, TPF, and
  77       even older platforms such as A/UX, Next, and Tandem.  These were
  78       believed to be broken anyway.</li>
  79
  80       <li>configure: dynamic modules (DSO) are built by default</li>
  81
  82       <li>configure: By default, only a basic set of modules is loaded. The
  83       other <code class="directive">LoadModule</code> directives are commented
  84       out.</li>
  85
  86       <li>configure: the "most" module set gets built by default</li>
  87
  88       <li>configure: the "reallyall" module set adds developer modules
  89       to the "all" set</li>
  90     </ul>
  91
  92   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  93 <div class="section">
  94 <h2><a name="run-time" id="run-time">Run-Time Configuration Changes</a></h2>
  95
  96     <p>There have been significant changes in authorization configuration,
  97     and other minor configuration changes, that could require changes to your 2.2
  98     configuration files before using them for 2.4.</p>
  99
 100     <h3><a name="authz" id="authz">Authorization</a></h3>
 101
 102
 103       <p>Any configuration file that uses authorization will likely
 104       need changes.</p>
 105
 106     <p>You should review the <a href="howto/auth.html">Authentication,
 107     Authorization and Access Control Howto</a>, especially the section
 108     <a href="howto/auth.html#beyond">Beyond just authorization</a>
 109     which explains the new mechanisms for controlling the order in
 110     which the authorization directives are applied.</p>
 111
 112     <p>Directives that control how authorization modules respond when they don't match
 113     the authenticated user have been removed: This includes
 114     AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative,
 115     AuthzGroupFileAuthoritative, AuthzUserAuthoritative,
 116     and AuthzOwnerAuthoritative.   These directives have been replaced by the
 117     more expressive <code class="directive"><a href="./mod/mod_authz_core.html#requireany">RequireAny</a></code>,
 118     <code class="directive"><a href="./mod/mod_authz_core.html#requirenone">RequireNone</a></code>, and
 119     <code class="directive"><a href="./mod/mod_authz_core.html#requireall">RequireAll</a></code>.</p>
 120
 121     <h4><a name="access" id="access">Access control</a></h4>
 122
 123
 124       <p>In 2.2, access control based on client hostname, IP address,
 125       and other characteristics of client requests was done using the
 126       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>
 127
 128       <p>In 2.4, such access control is done in the same way as other
 129       authorization checks, using the new module
 130       <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code>.  The old access control idioms
 131       should be replaced by the new authentication mechanisms,
 132       although for compatibility with old configurations, the new
 133       module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p>
 134
 135       <p>Here are some examples of old and new ways to do the same
 136       access control.</p>
 137
 138       <p>In this example, all requests are denied.</p>
 139       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 140 Order deny,allow
 141 Deny from all
 142         </pre>
 143 </div>
 144       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 145         Require all denied
 146         </pre>
 147 </div>
 148
 149       <p>In this example, all requests are allowed.</p>
 150       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 151 Order allow,deny
 152 Allow from all
 153         </pre>
 154 </div>
 155       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 156         Require all granted
 157         </pre>
 158 </div>
 159
 160       <p>In the following example, all hosts in the example.org domain
 161       are allowed access; all other hosts are denied access.</p>
 162
 163       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 164 Order Deny,Allow
 165 Deny from all
 166 Allow from example.org
 167         </pre>
 168 </div>
 169       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 170         Require host example.org
 171         </pre>
 172 </div>
 173
 174
 175
 176
 177     <h3><a name="config" id="config">Other configuration changes</a></h3>
 178
 179
 180       <p>Some other small adjustments may be necessary for particular
 181       configurations as discussed below.</p>
 182
 183       <ul>
 184         <li><code class="directive">MaxRequestsPerChild</code> has been renamed to
 185         <code class="directive"><a href="./mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>,
 186         describes more accurately what it does. The old name is still
 187         supported.</li>
 188
 189         <li><code class="directive">MaxClients</code> has been renamed to
 190         <code class="directive"><a href="./mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
 191         which describes more accurately what it does. For async MPMs, like
 192         <code class="module"><a href="./mod/event.html">event</a></code>, the maximum number of clients is not
 193         equivalent than the number of worker threads. The old name is still
 194         supported.</li>
 195
 196         <li>The <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
 197         directive no longer has any effect, other than to emit a
 198         warning if it's used with any value other than
 199         <code>none</code>.  You need to use other configuration
 200         settings to replace it in 2.4.
 201         </li>
 202
 203         <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
 204         defaults to Off.</li>
 205
 206         <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
 207         defaults to "MTime Size" (without INode).</li>
 208
 209         <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>
 210         matches whole cookie names.  Previously any substring would
 211         match.</li>
 212
 213         <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
 214         systems with inodes.  The old <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file must be deleted on
 215         upgrade.
 216         </li>
 217
 218         <li><code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> only
 219         accepts values of <code>On</code> or <code>Off</code>.
 220         Previously, any value other than "Off" or "0" was treated as
 221         "On".</li>
 222
 223         <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
 224         SSLStaplingMutex, and WatchdogMutexPath have been replaced
 225         with a single <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>
 226         directive.  You will need to evaluate any use of these removed
 227         directives in your 2.2 configuration to determine if they can
 228         just be deleted or will need to be replaced using <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>.</li>
 229
 230         <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>
 231         now does an exact match against the query string instead of a
 232         partial match.  If your configuration was using partial
 233         strings, e.g. using <code>sessionid</code> to match
 234         <code>/someapplication/image.gif;jsessionid=123456789</code>,
 235         then you will need to change to the full string
 236         <code>jsessionid</code>.
 237         </li>
 238
 239         <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
 240         consistently a per-directory setting only.  If you use this
 241         directive, review your configuration to make sure it is
 242         present in all the necessary directory contexts.</li>
 243
 244         <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
 245         now uses a boolean expression to determine if a filter is applied.
 246         </li>
 247
 248         <li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code>:
 249             <ul>
 250             <li>The <code>#if expr</code> element now uses the new <a href="expr.html">expression parser</a>. The old syntax can be
 251             restored with the new directive <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code>.
 252             </li>
 253             <li>An SSI* config directive in directory scope no longer causes
 254             all other per-directory SSI* directives to be reset to their
 255             default values.</li>
 256             </ul>
 257         </li>
 258
 259         <li><code class="module"><a href="./mod/mod_charset_lite.html">mod_charset_lite</a></code>: The <code>DebugLevel</code>
 260         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 261         </li>
 262
 263         <li><code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code>: The <code>DebugLevel</code>
 264         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 265         </li>
 266
 267         <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: CRL based revocation checking
 268         now needs to be explicitly configured through <code class="directive"><a href="./mod/mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck</a></code>.
 269         </li>
 270
 271         <li><code class="module"><a href="./mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now
 272         limited to 1MB.
 273         </li>
 274
 275         <li><code class="module"><a href="./mod/mod_reqtimeout.html">mod_reqtimeout</a></code>: If the module is loaded, it
 276         will now set some default timeouts.</li>
 277
 278       </ul>
 279
 280   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 281 <div class="section">
 282 <h2><a name="misc" id="misc">Misc Changes</a></h2>
 283
 284
 285     <ul>
 286       <li><code class="module"><a href="./mod/mod_autoindex.html">mod_autoindex</a></code>: will now extract titles and
 287       display descriptions for .xhtml files, which were previously
 288       ignored.</li>
 289
 290       <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: The default format of the <code>*_DN</code>
 291       variables has changed. The old format can still be used with the new
 292       <code>LegacyDNStringFormat</code> argument to <code class="directive"><a href="./mod/mod_ssl.html#ssloptions">SSLOptions</a></code>. The SSLv2 protocol is
 293       no longer supported. <code class="directive"><a href="./mod/mod_ssl.html#sslproxycheckpeercn&#10;&#9;  ">SSLProxyCheckPeerCN
 294           </a></code> and <code class="directive"><a href="./mod/mod_ssl.html#sslproxycheckpeerexpire&#10;&#9;  ">SSLProxyCheckPeerExpire
 295           </a></code> now default to On, causing proxy requests to HTTPS hosts
 296           with bad or outdated certificates to fail with a 502 status code (Bad
 297           gateway)</li>
 298
 299       <li><code class="program"><a href="./programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on
 300       all platforms.</li>
 301
 302       <li>The <code class="directive"><a href="./mod/core.html#namevirtualhost">NameVirtualHost</a></code>
 303       directive no longer has any effect, other than to emit a
 304       warning.  Any address/port combination appearing in multiple
 305       virtual hosts is implicitly treated as a name-based virtual host.
 306       </li>
 307
 308       <li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will now skip compression if it knows
 309       that the size overhead added by the compression is larger than the data
 310       to be compressed.
 311       </li>
 312
 313       <li>Multi-language error documents from 2.2.x may not work unless
 314       they are adjusted to the new syntax of <code class="module"><a href="./mod/mod_include.html">mod_include</a></code>'s
 315       <code>#if expr=</code> element or the directive
 316       <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code> is
 317       enabled for the directory containing the error documents.
 318       </li>
 319
 320       <li>The functionality provided by <code>mod_authn_alias</code>
 321       in previous versions (i.e., the <code class="directive"><a href="./mod/mod_authn_core.html#authnprovideralias">AuthnProviderAlias</a></code> directive)
 322       has been moved into <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.
 323       </li>
 324
 325     </ul>
 326
 327   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 328 <div class="section">
 329 <h2><a name="third-party" id="third-party">Third Party Modules</a></h2>
 330
 331     <p>All modules must be recompiled for 2.4 before being loaded.</p>
 332
 333     <p>Many third-party modules designed for version 2.2 will
 334     otherwise work unchanged with the Apache HTTP Server version 2.4.
 335     Some will require changes; see the <a href="developer/new_api_2_4.html">API
 336     update</a> overview.</p>
 337   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 338 <div class="section">
 339 <h2><a name="commonproblems" id="commonproblems">Common problems when upgrading</a></h2>
 340
 341     <ul><li>Startup errors:
 342     <ul>
 343       <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>
 344       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
 345 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
 346  - 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>
 347       <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>
 348       and replace with other configuration settings.</li>
 349     </ul></li>
 350     <li>Errors serving requests:
 351     <ul>
 352       <li><code>configuration error:  couldn't check user: /path</code> -
 353       load module <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.</li>
 354     </ul>
 355     </li>
 356 </ul>
 357   </div></div>
 358 <div class="bottomlang">
 359 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
 360 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 361 </div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 362 <script type="text/javascript"><!--//--><![CDATA[//><!--
 363 var comments_shortname = 'httpd';
 364 var comments_identifier = 'http://httpd.apache.org/docs/trunk/upgrading.html';
 365 (function(w, d) {
 366     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 367         d.write('<div id="comments_thread"><\/div>');
 368         var s = d.createElement('script');
 369         s.type = 'text/javascript';
 370         s.async = true;
 371         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 372         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 373     }
 374     else {
 375         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 376     }
 377 })(window, document);
 378 //--><!]]></script></div><div id="footer">
 379 <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>
 380 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 381 if (typeof(prettyPrint) !== 'undefined') {
 382     prettyPrint();
 383 }
 384 //--><!]]></script>
 385 </body></html>