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.min.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.4</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.4</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"> en </a> | 25<a href="/fr/upgrading.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </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 <p>If you use <code class="module"><a href="/mod/mod_authz_dbm.html">mod_authz_dbm</a></code>, you must port your 122 configuration to use <code>Require dbm-group ...</code> in place 123 of <code>Require group ...</code>.</p> 124 125 <h4><a name="access" id="access">Access control</a></h4> 126 127 128 <p>In 2.2, access control based on client hostname, IP address, 129 and other characteristics of client requests was done using the 130 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> 131 132 <p>In 2.4, such access control is done in the same way as other 133 authorization checks, using the new module 134 <code class="module"><a href="/mod/mod_authz_host.html">mod_authz_host</a></code>. The old access control idioms 135 should be replaced by the new authentication mechanisms, 136 although for compatibility with old configurations, the new 137 module <code class="module"><a href="/mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p> 138 139 <p>Here are some examples of old and new ways to do the same 140 access control.</p> 141 142 <p>In this example, all requests are denied.</p> 143 <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order deny,allow 144Deny from all</pre> 145</div> 146 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require all denied</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">Order allow,deny 151Allow from all</pre> 152</div> 153 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require all granted</pre> 154</div> 155 156 <p>In the following example, all hosts in the example.org domain 157 are allowed access; all other hosts are denied access.</p> 158 159 <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order Deny,Allow 160Deny from all 161Allow from example.org</pre> 162</div> 163 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require host example.org</pre> 164</div> 165 166 167 168 169 <h3><a name="config" id="config">Other configuration changes</a></h3> 170 171 172 <p>Some other small adjustments may be necessary for particular 173 configurations as discussed below.</p> 174 175 <ul> 176 <li><code class="directive">MaxRequestsPerChild</code> has been renamed to 177 <code class="directive"><a href="/mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>, 178 describes more accurately what it does. The old name is still 179 supported.</li> 180 181 <li><code class="directive">MaxClients</code> has been renamed to 182 <code class="directive"><a href="/mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>, 183 which describes more accurately what it does. For async MPMs, like 184 <code class="module"><a href="/mod/event.html">event</a></code>, the maximum number of clients is not 185 equivalent than the number of worker threads. The old name is still 186 supported.</li> 187 188 <li>The <code class="directive"><a href="/mod/core.html#defaulttype">DefaultType</a></code> 189 directive no longer has any effect, other than to emit a 190 warning if it's used with any value other than 191 <code>none</code>. You need to use other configuration 192 settings to replace it in 2.4. 193 </li> 194 195 <li><code class="directive"><a href="/mod/core.html#allowoverride">AllowOverride</a></code> now 196 defaults to <code>None</code>.</li> 197 198 <li><code class="directive"><a href="/mod/core.html#enablesendfile">EnableSendfile</a></code> now 199 defaults to Off.</li> 200 201 <li><code class="directive"><a href="/mod/core.html#fileetag">FileETag</a></code> now 202 defaults to "MTime Size" (without INode).</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_cache.html">mod_cache</a></code>: The second parameter to 231 <code class="directive"><a href="/mod/mod_cache.html#cacheenable">CacheEnable</a></code> only 232 matches forward proxy content if it begins with the correct 233 protocol. In 2.2 and earlier, a parameter of '/' matched all 234 content.</li> 235 236 <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 237 consistently a per-directory setting only. If you use this 238 directive, review your configuration to make sure it is 239 present in all the necessary directory contexts.</li> 240 241 <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 242 now uses a boolean expression to determine if a filter is applied. 243 </li> 244 245 <li><code class="module"><a href="/mod/mod_include.html">mod_include</a></code>: 246 <ul> 247 <li>The <code>#if expr</code> element now uses the new <a href="expr.html">expression parser</a>. The old syntax can be 248 restored with the new directive <code class="directive"><a href="/mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code>. 249 </li> 250 <li>An SSI* config directive in directory scope no longer causes 251 all other per-directory SSI* directives to be reset to their 252 default values.</li> 253 </ul> 254 </li> 255 256 <li><code class="module"><a href="/mod/mod_charset_lite.html">mod_charset_lite</a></code>: The <code>DebugLevel</code> 257 option has been removed in favour of per-module <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> configuration. 258 </li> 259 260 <li><code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>: The <code>DebugLevel</code> 261 option has been removed in favour of per-module <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> configuration. 262 </li> 263 264 <li><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>: CRL based revocation checking 265 now needs to be explicitly configured through <code class="directive"><a href="/mod/mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck</a></code>. 266 </li> 267 268 <li><code class="module"><a href="/mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now 269 limited to 1MB. 270 </li> 271 272 <li><code class="module"><a href="/mod/mod_reqtimeout.html">mod_reqtimeout</a></code>: If the module is loaded, it 273 will now set some default timeouts.</li> 274 275 <li><code class="module"><a href="/mod/mod_dumpio.html">mod_dumpio</a></code>: <code class="directive">DumpIOLogLevel</code> 276 is no longer supported. Data is always logged at <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> <code>trace7</code>.</li> 277 278 <li>On Unix platforms, piped logging commands configured using 279 either <code class="directive"><a href="/mod/core.html#errorlog">ErrorLog</a></code> or 280 <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> were invoked using 281 <code>/bin/sh -c</code> in 2.2 and earlier. In 2.4 and later, 282 piped logging commands are executed directly. To restore the 283 old behaviour, see the <a href="logs.html#piped">piped logging 284 documentation</a>.</li> 285 286 </ul> 287 288 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 289<div class="section"> 290<h2><a name="misc" id="misc">Misc Changes</a></h2> 291 292 293 <ul> 294 <li><code class="module"><a href="/mod/mod_autoindex.html">mod_autoindex</a></code>: will now extract titles and 295 display descriptions for .xhtml files, which were previously 296 ignored.</li> 297 298 <li><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>: The default format of the <code>*_DN</code> 299 variables has changed. The old format can still be used with the new 300 <code>LegacyDNStringFormat</code> argument to <code class="directive"><a href="/mod/mod_ssl.html#ssloptions">SSLOptions</a></code>. The SSLv2 protocol is 301 no longer supported. <code class="directive"><a href="/mod/mod_ssl.html#sslproxycheckpeercn">SSLProxyCheckPeerCN 302 </a></code> and <code class="directive"><a href="/mod/mod_ssl.html#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire 303 </a></code> now default to On, causing proxy requests to HTTPS hosts 304 with bad or outdated certificates to fail with a 502 status code (Bad 305 gateway)</li> 306 307 <li><code class="program"><a href="/programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on 308 all platforms.</li> 309 310 <li>The <code class="directive"><a href="/mod/core.html#namevirtualhost">NameVirtualHost</a></code> 311 directive no longer has any effect, other than to emit a 312 warning. Any address/port combination appearing in multiple 313 virtual hosts is implicitly treated as a name-based virtual host. 314 </li> 315 316 <li><code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code> will now skip compression if it knows 317 that the size overhead added by the compression is larger than the data 318 to be compressed. 319 </li> 320 321 <li>Multi-language error documents from 2.2.x may not work unless 322 they are adjusted to the new syntax of <code class="module"><a href="/mod/mod_include.html">mod_include</a></code>'s 323 <code>#if expr=</code> element or the directive 324 <code class="directive"><a href="/mod/mod_include.html#ssilegacyexprparser">SSILegacyExprParser</a></code> is 325 enabled for the directory containing the error documents. 326 </li> 327 328 <li>The functionality provided by <code>mod_authn_alias</code> 329 in previous versions (i.e., the <code class="directive"><a href="/mod/mod_authn_core.html#authnprovideralias">AuthnProviderAlias</a></code> directive) 330 has been moved into <code class="module"><a href="/mod/mod_authn_core.html">mod_authn_core</a></code>. 331 </li> 332 333 <li>The RewriteLog and RewriteLogLevel directives have been removed. 334 This functionality is now provided by configuring the appropriate 335 level of logging for the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> module using 336 the <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> directive. 337 See also the <a href="mod/mod_rewrite.html#logging">mod_rewrite logging</a> 338 section.</li> 339 340 </ul> 341 342 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 343<div class="section"> 344<h2><a name="third-party" id="third-party">Third Party Modules</a></h2> 345 346 <p>All modules must be recompiled for 2.4 before being loaded.</p> 347 348 <p>Many third-party modules designed for version 2.2 will 349 otherwise work unchanged with the Apache HTTP Server version 2.4. 350 Some will require changes; see the <a href="developer/new_api_2_4.html">API 351 update</a> overview.</p> 352 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 353<div class="section"> 354<h2><a name="commonproblems" id="commonproblems">Common problems when upgrading</a></h2> 355 356 <ul><li>Startup errors: 357 <ul> 358 <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> 359 <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or 360<code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code> 361 - 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> 362 <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> 363 and replace with other configuration settings.</li> 364 <li><code>Invalid command 'AddOutputFilterByType', perhaps misspelled 365 or defined by a module not included in the server configuration 366 </code> - <code class="directive"><a href="/mod/mod_filter.html#addoutputfilterbytype">AddOutputFilterByType</a></code> 367 has moved from the core to mod_filter, which must be loaded.</li> 368 </ul></li> 369 <li>Errors serving requests: 370 <ul> 371 <li><code>configuration error: couldn't check user: /path</code> - 372 load module <code class="module"><a href="/mod/mod_authn_core.html">mod_authn_core</a></code>.</li> 373 <li><code>.htaccess</code> files aren't being processed - Check for an 374 appropriate <code class="directive"><a href="/mod/core.html#allowoverride">AllowOverride</a></code> directive; 375 the default changed to <code>None</code> in 2.4.</li> 376 </ul> 377 </li> 378</ul> 379 </div></div> 380<div class="bottomlang"> 381<p><span>Available Languages: </span><a href="/en/upgrading.html" title="English"> en </a> | 382<a href="/fr/upgrading.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 383</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&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> 384<script type="text/javascript"><!--//--><![CDATA[//><!-- 385var comments_shortname = 'httpd'; 386var comments_identifier = 'http://httpd.apache.org/docs/2.4/upgrading.html'; 387(function(w, d) { 388 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 389 d.write('<div id="comments_thread"><\/div>'); 390 var s = d.createElement('script'); 391 s.type = 'text/javascript'; 392 s.async = true; 393 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 394 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 395 } 396 else { 397 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 398 } 399})(window, document); 400//--><!]]></script></div><div id="footer"> 401<p class="apache">Copyright 2014 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> 402<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[//><!-- 403if (typeof(prettyPrint) !== 'undefined') { 404 prettyPrint(); 405} 406//--><!]]></script> 407</body></html>
