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
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">
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="<-" alt="<-" src="./images/left.gif" /></a></div>
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.5</a></div><div id="page-content"><div id="preamble"><h1>Upgrading to 2.4 from 2.2</h1>
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>
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>
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
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>
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>
55 <h2><a name="compile-time" id="compile-time">Compile-Time Configuration Changes</a></h2>
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>
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
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
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>
80 <li>configure: dynamic modules (DSO) are built by default</li>
82 <li>configure: By default, only a basic set of modules is loaded. The
83 other <code class="directive">LoadModule</code> directives are commented
86 <li>configure: the "most" module set gets built by default</li>
88 <li>configure: the "reallyall" module set adds developer modules
92 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
94 <h2><a name="run-time" id="run-time">Run-Time Configuration Changes</a></h2>
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>
100 <h3><a name="authz" id="authz">Authorization</a></h3>
103 <p>Any configuration file that uses authorization will likely
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>
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#requireaall">RequireAall</a></code>.</p>
121 <h4><a name="access" id="access">Access control</a></h4>
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>
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>
135 <p>Here are some examples of old and new ways to do the same
138 <p>In this example, all requests are denied.</p>
139 <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
144 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
149 <p>In this example, all requests are allowed.</p>
150 <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
155 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
160 <p>In the following example, all hosts in the example.org domain
161 are allowed access; all other hosts are denied access.</p>
163 <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">
166 Allow from example.org
169 <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">
170 Require host example.org
177 <h3><a name="config" id="config">Other configuration changes</a></h3>
180 <p>Some other small adjustments may be necessary for particular
181 configurations as discussed below.</p>
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
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
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.
203 <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
204 defaults to Off.</li>
206 <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
207 defaults to "MTime Size" (without INode).</li>
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
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
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
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>
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>.
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>
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.
248 <li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code>:
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>.
253 <li>An SSI* config directive in directory scope no longer causes
254 all other per-directory SSI* directives to be reset to their
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.
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.
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>.
271 <li><code class="module"><a href="./mod/mod_substitute.html">mod_substitute</a></code>: The maximum line length is now
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>
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>
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
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 	 ">SSLProxyCheckPeerCN
294 </a></code> and <code class="directive"><a href="./mod/mod_ssl.html#sslproxycheckpeerexpire 	 ">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
299 <li><code class="program"><a href="./programs/htpasswd.html">htpasswd</a></code> now uses MD5 hash by default on
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.
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
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.
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>.
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>
331 <p>All modules must be recompiled for 2.4 before being loaded.</p>
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>
341 <ul><li>Startup errors:
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>
350 <li>Errors serving requests:
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>
358 <div class="bottomlang">
359 <p><span>Available Languages: </span><a href="./en/upgrading.html" title="English"> en </a> |
360 <a href="./fr/upgrading.html" hreflang="fr" rel="alternate" title="Français"> fr </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&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';
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';
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);
375 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
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') {