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: the "most" module set gets built by default</li>
84 <section id="run-time">
85 <title>Run-Time Configuration Changes</title>
86 <p>There have been significant changes in authorization configuration,
87 and other minor configuration changes, that could require changes to your 2.2
88 configuration files before using them for 2.4.</p>
91 <title>Authorization</title>
93 <p>Any configuration file that uses authorization will likely
96 <p>You should review the <a href="howto/auth.html">Authentication,
97 Authorization and Access Control Howto</a>, especially the section
98 <a href="howto/auth.html#beyond">Beyond just authorization</a>
99 which explains the new mechanisms for controlling the order in
100 which the authorization directives are applied.</p>
102 <section id="access">
103 <title>Access control</title>
105 <p>In 2.2, access control based on client hostname, IP address,
106 and other characteristics of client requests was done using the
107 directives <directive
108 module="mod_access_compat">Order</directive>, <directive
109 module="mod_access_compat">Allow</directive>, <directive
110 module="mod_access_compat">Deny</directive>, and <directive
111 module="mod_access_compat">Satisfy</directive>.</p>
113 <p>In 2.4, such access control is done in the same way as other
114 authorization checks, using the new module
115 <module>mod_authz_host</module>. The old access control idioms
116 should be replaced by the new authentication mechanisms,
117 although for compatibility with old configurations, the new
118 module <module>mod_access_compat</module> is provided.</p>
120 <p>Here are some examples of old and new ways to do the same
123 <p>In this example, all requests are denied.</p>
125 <title>2.2 configuration:</title>
126 Order deny,allow<br />
130 <title>2.4 configuration:</title>
134 <p>In this example, all requests are allowed.</p>
136 <title>2.2 configuration:</title>
137 Order allow,deny<br />
141 <title>2.4 configuration:</title>
145 <p>In the following example, all hosts in the example.org domain
146 are allowed access; all other hosts are denied access.</p>
149 <title>2.2 configuration:</title>
150 Order Deny,Allow<br />
152 Allow from example.org
155 <title>2.4 configuration:</title>
156 Require host example.org
162 <section id="config">
163 <title>Other configuration changes</title>
165 <p>Some other small adjustments may be necessary for particular
166 configurations as discussed below.</p>
169 <li><directive>MaxRequestsPerChild</directive> has been renamed to
170 <directive module="mpm_common">MaxConnectionsPerChild</directive>,
171 describes more accurately what it does. The old name is still
174 <li><directive>MaxClients</directive> has been renamed to
175 <directive module="mpm_common">MaxRequestWorkers</directive>,
176 which describes more accurately what it does. For async MPMs, like
177 <module>event</module>, the maximum number of clients is not
178 equivalent than the number of worker threads. The old name is still
181 <li>The <directive module="core">DefaultType</directive>
182 directive no longer has any effect, other than to emit a
183 warning if it's used with any value other than
184 <code>none</code>. You need to use other configuration
185 settings to replace it in 2.4.
188 <li><directive module="core">EnableSendfile</directive> now
189 defaults to Off.</li>
191 <li><module>mod_log_config</module>: <a
192 href="modules/mod_log_config.html#formats">${cookie}C</a>
193 matches whole cookie names. Previously any substring would
196 <li><module>mod_dav_fs</module>: The format of the <directive
197 module="mod_dav_fs">DavLockDB</directive> file has changed for
198 systems with inodes. The old <directive
199 module="mod_dav_fs">DavLockDB</directive> file must be deleted on
203 <li><directive module="core">KeepAlive</directive> only
204 accepts values of <code>On</code> or <code>Off</code>.
205 Previously, any value other than "Off" or "0" was treated as
208 <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
209 SSLStaplingMutex, and WatchdogMutexPath have been replaced
210 with a single <directive module="core">Mutex</directive>
211 directive. You will need to evaluate any use of these removed
212 directives in your 2.2 configuration to determine if they can
213 just be deleted or will need to be replaced using <directive
214 module="core">Mutex</directive>.</li>
216 <li><module>mod_cache</module>: <directive
217 module="mod_cache">CacheIgnoreURLSessionIdentifiers</directive>
218 now does an exact match against the query string instead of a
219 partial match. If your configuration was using partial
220 strings, e.g. using <code>sessionid</code> to match
221 <code>/someapplication/image.gif;jsessionid=123456789</code>,
222 then you will need to change to the full string
223 <code>jsessionid</code>.
226 <li><module>mod_ldap</module>: <directive
227 module="mod_ldap">LDAPTrustedClientCert</directive> is now
228 consistently a per-directory setting only. If you use this
229 directive, review your configuration to make sure it is
230 present in all the necessary directory contexts.</li>
232 <li><module>mod_filter</module>: <directive
233 module="mod_filter">FilterProvider</directive> syntax has changed and
234 now uses a boolean expression to determine if a filter is applied.
237 <li><module>mod_include</module>:
239 <li>The <code>#if expr</code> element now uses the new <a
240 href="expr.html">expression parser</a>. The old syntax can be
241 restored with the new directive <directive module="mod_include"
242 >SSILegacyExprParser</directive>.
244 <li>An SSI* config directive in directory scope no longer causes
245 all other per-directory SSI* directives to be reset to their
250 <li><module>mod_charset_lite</module>: The <code>DebugLevel</code>
251 option has been removed in favour of per-module <directive
252 module="core">LogLevel</directive> configuration.
255 <li><module>mod_ext-filter</module>: The <code>DebugLevel</code>
256 option has been removed in favour of per-module <directive
257 module="core">LogLevel</directive> configuration.
260 <li><module>mod_ssl</module>: CRL based revocation checking
261 now needs to be explicitly configured through <directive
262 module="mod_ssl">SSLCARevocationCheck</directive>.
270 <title>Misc Changes</title>
273 <li><module>mod_autoindex</module>: will now extract titles and
274 display descriptions for .xhtml files, which were previously
277 <li><module>mod_ssl</module>: The default format of the <code>*_DN</code>
278 variables has changed. The old format can still be used with the new
279 <code>LegacyDNStringFormat</code> argument to <directive
280 module="mod_ssl">SSLOptions</directive>.</li>
282 <li><program>htpasswd</program> now uses MD5 hash by default on
285 <li>The <directive module="core">NameVirtualHost</directive>
286 directive no longer has any effect, other than to emit a
287 warning. Any address/port combination appearing in multiple
288 virtual hosts is implicitly treated as a name-based virtual host.
291 <li><module>mod_deflate</module> will now skip compression if it knows
292 that the size overhead added by the compression is larger than the data
299 <section id="third-party">
300 <title>Third Party Modules</title>
301 <p>All modules must be recompiled for 2.4 before being loaded.</p>
303 <p>Many third-party modules designed for version 2.2 will
304 otherwise work unchanged with the Apache HTTP Server version 2.4.
305 Some will require changes; see the <a href="developer/new_api_2_4.html">API
306 update</a> overview.</p>
309 <section id="commonproblems">
310 <title>Common problems when upgrading</title>
311 <ul><li>Startup errors:
313 <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>
314 <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
315 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
316 - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
317 <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
318 and replace with other configuration settings.</li>
320 <li>Errors serving requests:
322 <li><code>configuration error: couldn't check user: /path</code> -
323 load module <module>mod_authn_core</module>.</li>