granicus.if.org Git - apache/blob - 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="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_disk_cache</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, OS/2, 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 apache.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 apache.org
 153       </example>
 154       <example>
 155         <title>2.4 configuration:</title>
 156         Require host apache.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>The <directive module="core">DefaultType</directive>
 170         directive no longer has any effect, other than to emit a
 171         warning if it's used with any value other than
 172         <code>none</code>.  You need to use other configuration
 173         settings to replace it in 2.4.
 174         </li>
 175
 176         <li><module>mod_log_config</module>: <a
 177         href="modules/mod_log_config.html#formats">${cookie}C</a>
 178         matches whole cookie names.  Previously any substring would
 179         match.</li>
 180
 181         <li><module>mod_dav_fs</module>: The format of the <directive
 182         module="dav_fs">DavLockDB</directive> file has changed for
 183         systems with inodes.  The old <directive
 184         module="dav_fs">DavLockDB</directive> file must be deleted on
 185         upgrade.
 186         </li>
 187
 188         <li><directive module="core">KeepAlive</directive> only
 189         accepts values of <code>On</code> or <code>Off</code>.
 190         Previously, any value other than "Off" or "0" was treated as
 191         "On".</li>
 192
 193         <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
 194         SSLStaplingMutex, and WatchdogMutexPath have been replaced
 195         with a single <directive module="core">Mutex</directive>
 196         directive.  You will need to evaluate any use of these removed
 197         directives in your 2.2 configuration to determine if they can
 198         just be deleted or will need to be replaced using <directive
 199         module="core">Mutex</directive>.</li>
 200
 201         <li><module>mod_cache</module>: <directive
 202         module="cache">CacheIgnoreURLSessionIdentifiers</directive>
 203         now does an exact match against the query string instead of a
 204         partial match.  If your configuration was using partial
 205         strings, e.g. using <code>sessionid</code> to match
 206         <code>/someapplication/image.gif;jsessionid=123456789</code>,
 207         then you will need to change to the full string
 208         <code>jsessionid</code>.
 209         </li>
 210
 211         <li><module>mod_ldap</module>: <directive
 212         module="ldap">LDAPTrustedClientCert</directive> is now
 213         consistently a per-directory setting only.  If you use this
 214         directive, review your configuration to make sure it is
 215         present in all the necessary directory contexts.</li>
 216
 217       </ul>
 218     </section>
 219   </section>
 220
 221   <section id="misc">
 222     <title>Misc Changes</title>
 223
 224     <ul>
 225       <li><module>mod_auto_index</module>: will now extract titles and
 226       display descriptions for .xhtml files, which were previously
 227       ignored.</li>
 228       <li><program>htpasswd</program> now uses MD5 hash by default on
 229       all platforms.</li>
 230     </ul>
 231
 232
 233   </section>
 234
 235   <section id="third-party">
 236     <title>Third Party Modules</title>
 237     <p>All modules must be recompiled for 2.4 before being loaded.</p>
 238
 239     <p>Many third-party modules designed for version 2.2 will
 240     otherwise work unchanged with the Apache HTTP Server version 2.4.
 241     Some will require changes; see the <a href="new_api_2_4.html">API
 242     update</a> overview.</p>
 243   </section>
 244
 245   <section id="commonproblems">
 246     <title>Common problems when upgrading</title>
 247     <ul><li>Startup errors:
 248     <ul>
 249       <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>
 250       <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
 251 <code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
 252  - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
 253       <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
 254       and replace with other configuration settings.</li>
 255     </ul></li>
 256     <li>Errors serving requests:
 257     <ul>
 258       <li><code>configuration error:  couldn't check user: /path</code> -
 259       load module <module>mod_authn_core</module>.</li>
 260     </ul>
 261     </li>
 262 </ul>
 263   </section>
 264 </manualpage>