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