]> granicus.if.org Git - apache/blob - docs/manual/upgrading.xml
Give a hint about old multi-language error documents
[apache] / docs / manual / upgrading.xml
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$ -->
5
6 <!--
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
13
14      http://www.apache.org/licenses/LICENSE-2.0
15
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.
21 -->
22
23 <manualpage metafile="upgrading.xml.meta">
24
25 <title>Upgrading to 2.4 from 2.2</title>
26
27 <summary>
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>
36
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
41   document.</p>
42
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>
47
48 </summary>
49 <seealso><a href="new_features_2_4.html">Overview of new features in
50   Apache HTTP Server 2.4</a></seealso>
51
52   <section id="compile-time">
53     <title>Compile-Time Configuration Changes</title>
54
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>
60
61     <ul>
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
65       2.4.</li>
66
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
71       uses.</li>
72
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>
76
77       <li>configure: dynamic modules (DSO) are built by default</li>
78
79       <li>configure: the "most" module set gets built by default</li>
80     </ul>
81
82   </section>
83
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>
89
90     <section id="authz">
91       <title>Authorization</title>
92
93       <p>Any configuration file that uses authorization will likely
94       need changes.</p>
95
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>
101
102     <section id="access">
103       <title>Access control</title>
104
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>
112
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>
119
120       <p>Here are some examples of old and new ways to do the same
121       access control.</p>
122
123       <p>In this example, all requests are denied.</p>
124       <example>
125         <title>2.2 configuration:</title>
126         Order deny,allow<br />
127         Deny from all
128       </example>
129       <example>
130         <title>2.4 configuration:</title>
131         Require all denied
132       </example>
133
134       <p>In this example, all requests are allowed.</p>
135       <example>
136         <title>2.2 configuration:</title>
137         Order allow,deny<br />
138         Allow from all
139       </example>
140       <example>
141         <title>2.4 configuration:</title>
142         Require all granted
143       </example>
144
145       <p>In the following example, all hosts in the example.org domain
146       are allowed access; all other hosts are denied access.</p>
147
148       <example>
149         <title>2.2 configuration:</title>
150         Order Deny,Allow<br />
151         Deny from all<br />
152         Allow from example.org
153       </example>
154       <example>
155         <title>2.4 configuration:</title>
156         Require host example.org
157       </example>
158     </section>
159
160     </section>
161
162     <section id="config">
163       <title>Other configuration changes</title>
164
165       <p>Some other small adjustments may be necessary for particular
166       configurations as discussed below.</p>
167
168       <ul>
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
172         supported.</li>
173
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
179         supported.</li>
180
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.
186         </li>
187
188         <li><directive module="core">EnableSendfile</directive> now
189         defaults to Off.</li>
190
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
194         match.</li>
195
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
200         upgrade.
201         </li>
202
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
206         "On".</li>
207
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>
215
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>.
224         </li>
225
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>
231
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.
235         </li>
236
237         <li><module>mod_include</module>:
238             <ul>
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>.
243             </li>
244             <li>An SSI* config directive in directory scope no longer causes
245             all other per-directory SSI* directives to be reset to their
246             default values.</li>
247             </ul>
248         </li>
249
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.
253         </li>
254
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.
258         </li>
259
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>.
263         </li>
264
265       </ul>
266     </section>
267   </section>
268
269   <section id="misc">
270     <title>Misc Changes</title>
271
272     <ul>
273       <li><module>mod_autoindex</module>: will now extract titles and
274       display descriptions for .xhtml files, which were previously
275       ignored.</li>
276
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>
281
282       <li><program>htpasswd</program> now uses MD5 hash by default on
283       all platforms.</li>
284
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.
289       </li>
290
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
293       to be compressed.
294       </li>
295
296       <li>Multi-language error documents from 2.2.x may not work unless
297       they are adjusted to the new syntax of <module>mod_include</module>'s
298       <code>#if expr=</code> element or the directive
299       <directive module="mod_include">SSILegacyExprParser</directive> is
300       enabled for the directory containing the error documents.
301       </li>
302
303     </ul>
304
305   </section>
306
307   <section id="third-party">
308     <title>Third Party Modules</title>
309     <p>All modules must be recompiled for 2.4 before being loaded.</p>
310
311     <p>Many third-party modules designed for version 2.2 will
312     otherwise work unchanged with the Apache HTTP Server version 2.4.
313     Some will require changes; see the <a href="developer/new_api_2_4.html">API
314     update</a> overview.</p>
315   </section>
316
317   <section id="commonproblems">
318     <title>Common problems when upgrading</title>
319     <ul><li>Startup errors:
320     <ul>
321       <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>
322       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
323 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
324  - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
325       <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
326       and replace with other configuration settings.</li>
327     </ul></li>
328     <li>Errors serving requests:
329     <ul>
330       <li><code>configuration error:  couldn't check user: /path</code> -
331       load module <module>mod_authn_core</module>.</li>
332     </ul>
333     </li>
334 </ul>
335   </section>
336 </manualpage>