1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="upgrading.xml.meta">
25 <title>Upgrading to 2.4 from 2.2</title>
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
32 href="new_features_2_4.html">New Features</a> document, or in
33 the <code>src/CHANGES</code> file. Application and module developers
34 can find a summary of API changes in the <a href="developer/new_api_2_4.html"
35 >API updates</a> overview.</p>
37 <p>This document describes changes in server behavior that might
38 require you to change your configuration or how you use the server
39 in order to continue using 2.4 as you are currently using 2.2.
40 To take advantage of new features in 2.4, see the New Features
43 <p>This document describes only the changes from 2.2 to 2.4. If you
44 are upgrading from version 2.0, you should also consult the <a
45 href="http://httpd.apache.org/docs/2.2/upgrading.html">2.0 to 2.2
46 upgrading document.</a></p>
49 <seealso><a href="new_features_2_4.html">Overview of new features in
50 Apache HTTP Server 2.4</a></seealso>
52 <section id="compile-time">
53 <title>Compile-Time Configuration Changes</title>
55 <p>The compilation process is very similar to the one used in
56 version 2.2. Your old <code>configure</code> command line (as
57 found in <code>build/config.nice</code> in the installed server
58 directory) can be used in most cases. There are some changes in
59 the default settings. Some details of changes:</p>
62 <li>These modules have been removed: mod_authn_default,
63 mod_authz_default, mod_mem_cache. If you were using
64 mod_mem_cache in 2.2, look at <module>mod_cache_disk</module> in
67 <li>All load balancing implementations have been moved to
68 individual, self-contained mod_proxy submodules, e.g.
69 <module>mod_lbmethod_bybusyness</module>. You might need
70 to build and load any of these that your configuration
73 <li>Platform support has been removed for BeOS, TPF, and
74 even older platforms such as A/UX, Next, and Tandem. These were
75 believed to be broken anyway.</li>
77 <li>configure: dynamic modules (DSO) are built by default</li>
79 <li>configure: By default, only a basic set of modules is loaded. The
80 other <directive>LoadModule</directive> directives are commented
81 out in the configuration file.</li>
83 <li>configure: the "most" module set gets built by default</li>
85 <li>configure: the "reallyall" module set adds developer modules
91 <section id="run-time">
92 <title>Run-Time Configuration Changes</title>
93 <p>There have been significant changes in authorization configuration,
94 and other minor configuration changes, that could require changes to your 2.2
95 configuration files before using them for 2.4.</p>
98 <title>Authorization</title>
100 <p>Any configuration file that uses authorization will likely
103 <p>You should review the <a href="howto/auth.html">Authentication,
104 Authorization and Access Control Howto</a>, especially the section
105 <a href="howto/auth.html#beyond">Beyond just authorization</a>
106 which explains the new mechanisms for controlling the order in
107 which the authorization directives are applied.</p>
109 <p>Directives that control how authorization modules respond when they don't match
110 the authenticated user have been removed: This includes
111 AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative,
112 AuthzGroupFileAuthoritative, AuthzUserAuthoritative,
113 and AuthzOwnerAuthoritative. These directives have been replaced by the
114 more expressive <directive module="mod_authz_core">RequireAny</directive>,
115 <directive module="mod_authz_core">RequireNone</directive>, and
116 <directive module="mod_authz_core">RequireAll</directive>.</p>
118 <p>If you use <module>mod_authz_dbm</module>, you must port your
119 configuration to use <code>Require dbm-group ...</code> in place
120 of <code>Require group ...</code>.</p>
122 <section id="access">
123 <title>Access control</title>
125 <p>In 2.2, access control based on client hostname, IP address,
126 and other characteristics of client requests was done using the
127 directives <directive
128 module="mod_access_compat">Order</directive>, <directive
129 module="mod_access_compat">Allow</directive>, <directive
130 module="mod_access_compat">Deny</directive>, and <directive
131 module="mod_access_compat">Satisfy</directive>.</p>
133 <p>In 2.4, such access control is done in the same way as other
134 authorization checks, using the new module
135 <module>mod_authz_host</module>. The old access control idioms
136 should be replaced by the new authentication mechanisms,
137 although for compatibility with old configurations, the new
138 module <module>mod_access_compat</module> is provided.</p>
140 <note><title>Mixing old and new directives</title>
141 <p>Mixing old directives like <directive
142 module="mod_access_compat">Order</directive>, <directive
143 module="mod_access_compat">Allow</directive> or <directive
144 module="mod_access_compat">Deny</directive> with new ones like
146 module="mod_authz_core">Require</directive> is technically possible
147 but discouraged. <module>mod_access_compat</module> was created to support
148 configurations containing only old directives to facilitate the 2.4 upgrade.
149 Please check the examples below to get a better idea about issues that might arise.
153 <p>Here are some examples of old and new ways to do the same
156 <p>In this example, there is no authentication and all requests are denied.</p>
158 <title>2.2 configuration:</title>
159 <highlight language="config">
165 <title>2.4 configuration:</title>
166 <highlight language="config">
171 <p>In this example, there is no authentication and all requests are allowed.</p>
173 <title>2.2 configuration:</title>
174 <highlight language="config">
180 <title>2.4 configuration:</title>
181 <highlight language="config">
186 <p>In the following example, there is no authentication and all hosts in the example.org domain
187 are allowed access; all other hosts are denied access.</p>
190 <title>2.2 configuration:</title>
191 <highlight language="config">
194 Allow from example.org
198 <title>2.4 configuration:</title>
199 <highlight language="config">
200 Require host example.org
204 <p>In the following example, mixing old and new directives leads to
205 unexpected results.</p>
208 <title>Mixing old and new directives: NOT WORKING AS EXPECTED</title>
209 <highlight language="config">
210 DocumentRoot "/var/www/html"
212 <Directory "/">
218 <Location "/server-status">
219 SetHandler server-status
223 access.log - GET /server-status 403 127.0.0.1
224 error.log - AH01797: client denied by server configuration: /var/www/html/server-status
227 <p>Why httpd denies access to servers-status even if the configuration seems to allow it?
228 Because <module>mod_access_compat</module> directives take precedence
229 over the <module>mod_authz_host</module> one in this configuration
230 <a href="sections.html#merging">merge</a> scenario.</p>
232 <p>This example conversely works as expected:</p>
235 <title>Mixing old and new directives: WORKING AS EXPECTED</title>
236 <highlight language="config">
237 DocumentRoot "/var/www/html"
239 <Directory "/">
244 <Location "/server-status">
245 SetHandler server-status
251 access.log - GET /server-status 200 127.0.0.1
254 <p>So even if mixing configuration is still
255 possible, please try to avoid it when upgrading: either keep old directives and then migrate
256 to the new ones on a later stage or just migrate everything in bulk.
260 <p>In many configurations with authentication, where the value of the
261 <directive>Satisfy</directive> was the default of <em>ALL</em>, snippets
262 that simply disabled host-based access control are omitted:</p>
265 <title>2.2 configuration:</title>
266 <highlight language="config">
269 AuthBasicProvider File
270 AuthUserFile /example.com/conf/users.passwd
276 <title>2.4 configuration:</title>
277 <highlight language="config">
278 # No replacement needed
279 AuthBasicProvider File
280 AuthUserFile /example.com/conf/users.passwd
286 <p>In configurations where both authentication and access control were meaningfully combined, the
287 access control directives should be migrated. This example allows requests meeting <em>both</em> criteria:</p>
289 <title>2.2 configuration:</title>
290 <highlight language="config">
293 # Satisfy ALL is the default
296 AuthBasicProvider File
297 AuthUserFile /example.com/conf/users.passwd
303 <title>2.4 configuration:</title>
304 <highlight language="config">
305 AuthBasicProvider File
306 AuthUserFile /example.com/conf/users.passwd
315 <p>In configurations where both authentication and access control were meaningfully combined, the
316 access control directives should be migrated. This example allows requests meeting <em>either</em> criteria:</p>
318 <title>2.2 configuration:</title>
319 <highlight language="config">
324 AuthBasicProvider File
325 AuthUserFile /example.com/conf/users.passwd
331 <title>2.4 configuration:</title>
332 <highlight language="config">
333 AuthBasicProvider File
334 AuthUserFile /example.com/conf/users.passwd
336 # Implicitly <RequireAny>
344 <section id="config">
345 <title>Other configuration changes</title>
347 <p>Some other small adjustments may be necessary for particular
348 configurations as discussed below.</p>
351 <li><directive>MaxRequestsPerChild</directive> has been renamed to
352 <directive module="mpm_common">MaxConnectionsPerChild</directive>,
353 describes more accurately what it does. The old name is still
356 <li><directive>MaxClients</directive> has been renamed to
357 <directive module="mpm_common">MaxRequestWorkers</directive>,
358 which describes more accurately what it does. For async MPMs, like
359 <module>event</module>, the maximum number of clients is not
360 equivalent than the number of worker threads. The old name is still
363 <li>The <directive module="core">DefaultType</directive>
364 directive no longer has any effect, other than to emit a
365 warning if it's used with any value other than
366 <code>none</code>. You need to use other configuration
367 settings to replace it in 2.4.
370 <li><directive module="core">AllowOverride</directive> now
371 defaults to <code>None</code>.</li>
373 <li><directive module="core">EnableSendfile</directive> now
374 defaults to Off.</li>
376 <li><directive module="core">FileETag</directive> now
377 defaults to "MTime Size" (without INode).</li>
379 <li><module>mod_dav_fs</module>: The format of the <directive
380 module="mod_dav_fs">DavLockDB</directive> file has changed for
381 systems with inodes. The old <directive
382 module="mod_dav_fs">DavLockDB</directive> file must be deleted on
386 <li><directive module="core">KeepAlive</directive> only
387 accepts values of <code>On</code> or <code>Off</code>.
388 Previously, any value other than "Off" or "0" was treated as
391 <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
392 SSLStaplingMutex, and WatchdogMutexPath have been replaced
393 with a single <directive module="core">Mutex</directive>
394 directive. You will need to evaluate any use of these removed
395 directives in your 2.2 configuration to determine if they can
396 just be deleted or will need to be replaced using <directive
397 module="core">Mutex</directive>.</li>
399 <li><module>mod_cache</module>: <directive
400 module="mod_cache">CacheIgnoreURLSessionIdentifiers</directive>
401 now does an exact match against the query string instead of a
402 partial match. If your configuration was using partial
403 strings, e.g. using <code>sessionid</code> to match
404 <code>/someapplication/image.gif;jsessionid=123456789</code>,
405 then you will need to change to the full string
406 <code>jsessionid</code>.
409 <li><module>mod_cache</module>: The second parameter to
410 <directive module="mod_cache">CacheEnable</directive> only
411 matches forward proxy content if it begins with the correct
412 protocol. In 2.2 and earlier, a parameter of '/' matched all
415 <li><module>mod_ldap</module>: <directive
416 module="mod_ldap">LDAPTrustedClientCert</directive> is now
417 consistently a per-directory setting only. If you use this
418 directive, review your configuration to make sure it is
419 present in all the necessary directory contexts.</li>
421 <li><module>mod_filter</module>: <directive
422 module="mod_filter">FilterProvider</directive> syntax has changed and
423 now uses a boolean expression to determine if a filter is applied.
426 <li><module>mod_include</module>:
428 <li>The <code>#if expr</code> element now uses the new <a
429 href="expr.html">expression parser</a>. The old syntax can be
430 restored with the new directive <directive module="mod_include"
431 >SSILegacyExprParser</directive>.
433 <li>An SSI* config directive in directory scope no longer causes
434 all other per-directory SSI* directives to be reset to their
439 <li><module>mod_charset_lite</module>: The <code>DebugLevel</code>
440 option has been removed in favour of per-module <directive
441 module="core">LogLevel</directive> configuration.
444 <li><module>mod_ext_filter</module>: The <code>DebugLevel</code>
445 option has been removed in favour of per-module <directive
446 module="core">LogLevel</directive> configuration.
449 <li><module>mod_proxy_scgi</module>: The default setting for
450 <code>PATH_INFO</code> has changed from httpd 2.2, and
451 some web applications will no longer operate properly with
452 the new <code>PATH_INFO</code> setting. The previous setting
453 can be restored by configuring the <code>proxy-scgi-pathinfo</code>
456 <li><module>mod_ssl</module>: CRL based revocation checking
457 now needs to be explicitly configured through <directive
458 module="mod_ssl">SSLCARevocationCheck</directive>.
461 <li><module>mod_substitute</module>: The maximum line length is now
465 <li><module>mod_reqtimeout</module>: If the module is loaded, it
466 will now set some default timeouts.</li>
468 <li><module>mod_dumpio</module>: <directive>DumpIOLogLevel</directive>
469 is no longer supported. Data is always logged at <directive
470 module="core">LogLevel</directive> <code>trace7</code>.</li>
472 <li>On Unix platforms, piped logging commands configured using
473 either <directive module="core">ErrorLog</directive> or
474 <directive module="mod_log_config">CustomLog</directive> were invoked using
475 <code>/bin/sh -c</code> in 2.2 and earlier. In 2.4 and later,
476 piped logging commands are executed directly. To restore the
477 old behaviour, see the <a href="logs.html#piped">piped logging
478 documentation</a>.</li>
485 <title>Misc Changes</title>
488 <li><module>mod_autoindex</module>: will now extract titles and
489 display descriptions for .xhtml files, which were previously
492 <li><module>mod_ssl</module>: The default format of the <code>*_DN</code>
493 variables has changed. The old format can still be used with the new
494 <code>LegacyDNStringFormat</code> argument to <directive
495 module="mod_ssl">SSLOptions</directive>. The SSLv2 protocol is
496 no longer supported. <directive module="mod_ssl">SSLProxyCheckPeerCN
497 </directive> and <directive module="mod_ssl">SSLProxyCheckPeerExpire
498 </directive> now default to On, causing proxy requests to HTTPS hosts
499 with bad or outdated certificates to fail with a 502 status code (Bad
502 <li><program>htpasswd</program> now uses MD5 hash by default on
505 <li>The <directive module="core">NameVirtualHost</directive>
506 directive no longer has any effect, other than to emit a
507 warning. Any address/port combination appearing in multiple
508 virtual hosts is implicitly treated as a name-based virtual host.
511 <li><module>mod_deflate</module> will now skip compression if it knows
512 that the size overhead added by the compression is larger than the data
516 <li>Multi-language error documents from 2.2.x may not work unless
517 they are adjusted to the new syntax of <module>mod_include</module>'s
518 <code>#if expr=</code> element or the directive
519 <directive module="mod_include">SSILegacyExprParser</directive> is
520 enabled for the directory containing the error documents.
523 <li>The functionality provided by <code>mod_authn_alias</code>
524 in previous versions (i.e., the <directive
525 module="mod_authn_core">AuthnProviderAlias</directive> directive)
526 has been moved into <module>mod_authn_core</module>.
529 <li><module>mod_cgid</module> uses the servers <directive module="core"
530 >Timeout</directive> to limit the length of time to wait for CGI output.
531 This timeout can be overridden with <directive module="mod_cgid">
532 CGIDScriptTImeout</directive>.
539 <section id="third-party">
540 <title>Third Party Modules</title>
541 <p>All modules must be recompiled for 2.4 before being loaded.</p>
543 <p>Many third-party modules designed for version 2.2 will
544 otherwise work unchanged with the Apache HTTP Server version 2.4.
545 Some will require changes; see the <a href="developer/new_api_2_4.html">API
546 update</a> overview.</p>
549 <section id="commonproblems">
550 <title>Common problems when upgrading</title>
551 <ul><li>Startup errors:
553 <li><code>Invalid command 'User', perhaps misspelled or defined by a module not included in the server configuration</code> - load module <module>mod_unixd</module></li>
554 <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
555 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
556 - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
557 <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
558 and replace with other configuration settings.</li>
559 <li><code>Invalid command 'AddOutputFilterByType', perhaps misspelled
560 or defined by a module not included in the server configuration
561 </code> - <directive module="mod_filter">AddOutputFilterByType</directive>
562 has moved from the core to mod_filter, which must be loaded.</li>
564 <li>Errors serving requests:
566 <li><code>configuration error: couldn't check user: /path</code> -
567 load module <module>mod_authn_core</module>.</li>
568 <li><code>.htaccess</code> files aren't being processed - Check for an
569 appropriate <directive module="core">AllowOverride</directive> directive;
570 the default changed to <code>None</code> in 2.4.</li>