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     <h4><a name="access" id="access">Access control</a></h4>
 113
 114
 115       <p>In 2.2, access control based on client hostname, IP address,
 116       and other characteristics of client requests was done using the
 117       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>
 118
 119       <p>In 2.4, such access control is done in the same way as other
 120       authorization checks, using the new module
 121       <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code>.  The old access control idioms
 122       should be replaced by the new authentication mechanisms,
 123       although for compatibility with old configurations, the new
 124       module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p>
 125
 126       <p>Here are some examples of old and new ways to do the same
 127       access control.</p>
 128
 129       <p>In this example, all requests are denied.</p>
 130       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 131 Order deny,allow
 132 Deny from all
 133         </pre>
 134 </div>
 135       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 136         Require all denied
 137         </pre>
 138 </div>
 139
 140       <p>In this example, all requests are allowed.</p>
 141       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 142 Order allow,deny
 143 Allow from all
 144         </pre>
 145 </div>
 146       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 147         Require all granted
 148         </pre>
 149 </div>
 150
 151       <p>In the following example, all hosts in the example.org domain
 152       are allowed access; all other hosts are denied access.</p>
 153
 154       <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
 155 Order Deny,Allow
 156 Deny from all
 157 Allow from example.org
 158         </pre>
 159 </div>
 160       <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
 161         Require host example.org
 162         </pre>
 163 </div>
 164
 165
 166
 167
 168     <h3><a name="config" id="config">Other configuration changes</a></h3>
 169
 170
 171       <p>Some other small adjustments may be necessary for particular
 172       configurations as discussed below.</p>
 173
 174       <ul>
 175         <li><code class="directive">MaxRequestsPerChild</code> has been renamed to
 176         <code class="directive"><a href="./mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>,
 177         describes more accurately what it does. The old name is still
 178         supported.</li>
 179
 180         <li><code class="directive">MaxClients</code> has been renamed to
 181         <code class="directive"><a href="./mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
 182         which describes more accurately what it does. For async MPMs, like
 183         <code class="module"><a href="./mod/event.html">event</a></code>, the maximum number of clients is not
 184         equivalent than the number of worker threads. The old name is still
 185         supported.</li>
 186
 187         <li>The <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
 188         directive no longer has any effect, other than to emit a
 189         warning if it's used with any value other than
 190         <code>none</code>.  You need to use other configuration
 191         settings to replace it in 2.4.
 192         </li>
 193
 194         <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
 195         defaults to Off.</li>
 196
 197         <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
 198         defaults to "MTime Size" (without INode).</li>
 199
 200         <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>
 201         matches whole cookie names.  Previously any substring would
 202         match.</li>
 203
 204         <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
 205         systems with inodes.  The old <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file must be deleted on
 206         upgrade.
 207         </li>
 208
 209         <li><code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> only
 210         accepts values of <code>On</code> or <code>Off</code>.
 211         Previously, any value other than "Off" or "0" was treated as
 212         "On".</li>
 213
 214         <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
 215         SSLStaplingMutex, and WatchdogMutexPath have been replaced
 216         with a single <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>
 217         directive.  You will need to evaluate any use of these removed
 218         directives in your 2.2 configuration to determine if they can
 219         just be deleted or will need to be replaced using <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>.</li>
 220
 221         <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>
 222         now does an exact match against the query string instead of a
 223         partial match.  If your configuration was using partial
 224         strings, e.g. using <code>sessionid</code> to match
 225         <code>/someapplication/image.gif;jsessionid=123456789</code>,
 226         then you will need to change to the full string
 227         <code>jsessionid</code>.
 228         </li>
 229
 230         <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
 231         consistently a per-directory setting only.  If you use this
 232         directive, review your configuration to make sure it is
 233         present in all the necessary directory contexts.</li>
 234
 235         <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
 236         now uses a boolean expression to determine if a filter is applied.
 237         </li>
 238
 239         <li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code>:
 240             <ul>
 241             <li>The <code>#if expr</code> element now uses the new <a href="expr.html">expression parser</a>. The old syntax can be
 242             restored with the new directive <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code>.
 243             </li>
 244             <li>An SSI* config directive in directory scope no longer causes
 245             all other per-directory SSI* directives to be reset to their
 246             default values.</li>
 247             </ul>
 248         </li>
 249
 250         <li><code class="module"><a href="./mod/mod_charset_lite.html">mod_charset_lite</a></code>: The <code>DebugLevel</code>
 251         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 252         </li>
 253
 254         <li><code class="module"><a href="./mod/mod_ext-filter.html">mod_ext-filter</a></code>: The <code>DebugLevel</code>
 255         option has been removed in favour of per-module <code class="directive"><a href="./mod/core.html#loglevel">LogLevel</a></code> configuration.
 256         </li>
 257
 258         <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: CRL based revocation checking
 259         now needs to be explicitly configured through <code class="directive"><a href="./mod/mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck</a></code>.
 260         </li>
 261
 262         <li><code class="module"><a href="./mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now
 263         limited to 1MB.
 264         </li>
 265
 266         <li><code class="module"><a href="./mod/mod_reqtimeout.html">mod_reqtimeout</a></code>: If the module is loaded, it
 267         will now set some default timeouts.</li>
 268
 269       </ul>
 270
 271   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 272 <div class="section">
 273 <h2><a name="misc" id="misc">Misc Changes</a></h2>
 274
 275
 276     <ul>
 277       <li><code class="module"><a href="./mod/mod_autoindex.html">mod_autoindex</a></code>: will now extract titles and
 278       display descriptions for .xhtml files, which were previously
 279       ignored.</li>
 280
 281       <li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>: The default format of the <code>*_DN</code>
 282       variables has changed. The old format can still be used with the new
 283       <code>LegacyDNStringFormat</code> argument to <code class="directive"><a href="./mod/mod_ssl.html#ssloptions">SSLOptions</a></code>. The SSLv2 protocol is
 284       no longer supported. <code class="directive"><a href="./mod/mod_ssl.html#sslproxycheckpeercn&#10;&#9;  ">SSLProxyCheckPeerCN
 285           </a></code> and <code class="directive"><a href="./mod/mod_ssl.html#sslproxycheckpeerexpire&#10;&#9;  ">SSLProxyCheckPeerExpire
 286           </a></code> now default to On, causing proxy requests to HTTPS hosts
 287           with bad or outdated certificates to fail with a 502 status code (Bad
 288           gateway)</li>
 289
 290       <li><code class="program"><a href="./programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on
 291       all platforms.</li>
 292
 293       <li>The <code class="directive"><a href="./mod/core.html#namevirtualhost">NameVirtualHost</a></code>
 294       directive no longer has any effect, other than to emit a
 295       warning.  Any address/port combination appearing in multiple
 296       virtual hosts is implicitly treated as a name-based virtual host.
 297       </li>
 298
 299       <li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will now skip compression if it knows
 300       that the size overhead added by the compression is larger than the data
 301       to be compressed.
 302       </li>
 303
 304       <li>Multi-language error documents from 2.2.x may not work unless
 305       they are adjusted to the new syntax of <code class="module"><a href="./mod/mod_include.html">mod_include</a></code>'s
 306       <code>#if expr=</code> element or the directive
 307       <code class="directive"><a href="./mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code> is
 308       enabled for the directory containing the error documents.
 309       </li>
 310
 311       <li>The functionality provided by <code>mod_authn_alias</code>
 312       in previous versions (i.e., the <code class="directive"><a href="./mod/mod_authn_core.html#authnprovideralias">AuthnProviderAlias</a></code> directive)
 313       has been moved into <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.
 314       </li>
 315
 316     </ul>
 317
 318   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 319 <div class="section">
 320 <h2><a name="third-party" id="third-party">Third Party Modules</a></h2>
 321
 322     <p>All modules must be recompiled for 2.4 before being loaded.</p>
 323
 324     <p>Many third-party modules designed for version 2.2 will
 325     otherwise work unchanged with the Apache HTTP Server version 2.4.
 326     Some will require changes; see the <a href="developer/new_api_2_4.html">API
 327     update</a> overview.</p>
 328   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 329 <div class="section">
 330 <h2><a name="commonproblems" id="commonproblems">Common problems when upgrading</a></h2>
 331
 332     <ul><li>Startup errors:
 333     <ul>
 334       <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>
 335       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
 336 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
 337  - 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>
 338       <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>
 339       and replace with other configuration settings.</li>
 340     </ul></li>
 341     <li>Errors serving requests:
 342     <ul>
 343       <li><code>configuration error:  couldn't check user: /path</code> -
 344       load module <code class="module"><a href="./mod/mod_authn_core.html">mod_authn_core</a></code>.</li>
 345     </ul>
 346     </li>
 347 </ul>
 348   </div></div>
 349 <div class="bottomlang">
 350 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English">&nbsp;en&nbsp;</a> |
 351 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 352 </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>This section is experimental!</strong><br />Comments placed here should not be expected
 353 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
 354 <script type="text/javascript"><!--//--><![CDATA[//><!--
 355 var disqus_shortname = 'httpd';
 356 var disqus_identifier = 'http://httpd.apache.org/docs/2.4/upgrading.html.en';
 357 (function(w, d) {
 358     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 359         d.write('<div id="disqus_thread"><\/div>');
 360         var s = d.createElement('script');
 361         s.type = 'text/javascript';
 362         s.async = true;
 363         s.src = 'http' + '://' + disqus_shortname + '.disqus.com/embed.js';
 364         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 365     }
 366     else {
 367         d.write('<div id="disqus_thread">Comments have been disabled for offline viewing.<\/div>');
 368     }
 369 })(window, document);
 370 //--><!]]></script></div><div id="footer">
 371 <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>
 372 <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[//><!--
 373 if (typeof(prettyPrint) !== 'undefined') {
 374     prettyPrint();
 375 }
 376 //--><!]]></script>
 377 </body></html>