You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by po...@apache.org on 2010/06/20 21:48:13 UTC
svn commit: r956396 - /httpd/httpd/trunk/docs/manual/upgrading.xml
Author: poirier
Date: Sun Jun 20 19:48:13 2010
New Revision: 956396
URL: http://svn.apache.org/viewvc?rev=956396&view=rev
Log:
First pass at documentation for upgrading to 2.4.
Went through CHANGES and tried to pick out things that would
require a 2.2 user to make changes for 2.4.
Modified:
httpd/httpd/trunk/docs/manual/upgrading.xml
Modified: httpd/httpd/trunk/docs/manual/upgrading.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/upgrading.xml?rev=956396&r1=956395&r2=956396&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/upgrading.xml (original)
+++ httpd/httpd/trunk/docs/manual/upgrading.xml Sun Jun 20 19:48:13 2010
@@ -34,6 +34,12 @@
can find a summary of API changes in the <a href="new_api_2_4.html"
>API updates</a> overview.</p>
+ <p>This document describes changes in server behavior that might
+ require you to change your configuration or how you use the server
+ in order to continue using 2.4 as you are currently using 2.2.
+ To take advantage of new features in 2.4, see the New Features
+ document.</p>
+
<p>This document describes only the changes from 2.2 to 2.4. If you
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
@@ -45,25 +51,214 @@
<section id="compile-time">
<title>Compile-Time Configuration Changes</title>
- <!-- <ul>
- </ul> -->
+
+ <p>The compilation process is very similar to the one used in
+ version 2.2. Your old <code>configure</code> command line (as
+ found in <code>build/config.nice</code> in the installed server
+ directory) can be used in most cases. There are some changes in
+ the default settings. Some details of changes:</p>
+
+ <ul>
+ <li>These modules have been removed: mod_authn_default,
+ mod_authz_default, mod_mem_cache. If you were using
+ mod_mem_cache in 2.2, look at <module>mod_disk_cache</module> in
+ 2.4.</li>
+
+ <li>All load balancing implementations have been moved to
+ individual, self-contained mod_proxy submodules, e.g.
+ <module>mod_lbmethod_bybusyness</module>. You might need
+ to build and load any of these that your configuration
+ uses.</li>
+
+ <li>Platform support has been removed for BeOS, OS/2, TPF, and
+ even older platforms such as A/UX, Next, and Tandem. These were
+ believed to be broken anyway.</li>
+
+ <li>configure: dynamic modules (DSO) are built by default</li>
+
+ <li>configure: the "most" module set gets built by default</li>
+ </ul>
</section>
<section id="run-time">
<title>Run-Time Configuration Changes</title>
+ <p>There have been significant changes in authorization configuration,
+ and other minor configuration changes, that could require changes to your 2.2
+ configuration files before using them for 2.4.</p>
+
+ <section id="authz">
+ <title>Authorization</title>
+
+ <p>Any configuration file that uses authorization will likely
+ need changes.</p>
+
+ <p>You should review the <a href="howto/auth.html">Authentication,
+ Authorization and Access Control Howto</a>, especially the section
+ <a href="howto/auth.html#beyond">Beyond just authorization</a>
+ which explains the new mechanisms for controlling the order in
+ which the authorization directives are applied.</p>
+
+ <section id="access">
+ <title>Access control</title>
+
+ <p>In 2.2, access control based on client hostname, IP address,
+ and other characteristics of client requests was done using the
+ directives <directive
+ module="mod_access_compat">Order</directive>, <directive
+ module="mod_access_compat">Allow</directive>, <directive
+ module="mod_access_compat">Deny</directive>, and <directive
+ module="mod_access_compat">Satisfy</directive>.</p>
+
+ <p>In 2.4, such access control is done in the same way as other
+ authorization checks, using the new module
+ <module>mod_authz_host</module>. The old access control idioms
+ should be replaced by the new authentication mechanisms,
+ although for compatibility with old configurations, the new
+ module <module>mod_access_compat</module> is provided.</p>
+
+ <p>Here are some examples of old and new ways to do the same
+ access control.</p>
+
+ <p>In this example, all requests are denied.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ Order deny,allow<br />
+ Deny from all
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require all denied
+ </example>
+
+ <p>In this example, all requests are allowed.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ Order allow,deny<br />
+ Allow from all
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require all granted
+ </example>
+
+ <p>In the following example, all hosts in the apache.org domain
+ are allowed access; all other hosts are denied access.</p>
+
+ <example>
+ <title>2.2 configuration:</title>
+ Order Deny,Allow<br />
+ Deny from all<br />
+ Allow from apache.org
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require host apache.org
+ </example>
+ </section>
+
+ </section>
+
+ <section id="config">
+ <title>Other configuration changes</title>
+
+ <p>Some other small adjustments may be necessary for particular
+ configurations as discussed below.</p>
+
+ <ul>
+ <li>The <directive module="core">DefaultType</directive>
+ directive no longer has any effect, other than to emit a
+ warning if it's used with any value other than
+ <code>none</code>. You need to use other configuration
+ settings to replace it in 2.4.
+ </li>
+
+ <li><module>mod_log_config</module>: <a
+ href="modules/mod_log_config.html#formats">${cookie}C</a>
+ matches whole cookie names. Previously any substring would
+ match.</li>
+
+ <li><module>mod_dav_fs</module>: The format of the <directive
+ module="dav_fs">DavLockDB</directive> file has changed for
+ systems with inodes. The old <directive
+ module="dav_fs">DavLockDB</directive> file must be deleted on
+ upgrade.
+ </li>
+
+ <li><directive module="core">KeepAlive</directive> only
+ accepts values of <code>On</code> or <code>Off</code>.
+ Previously, any value other than "Off" or "0" was treated as
+ "On".</li>
+
+ <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
+ SSLStaplingMutex, and WatchdogMutexPath have been replaced
+ with a single <directive module="core">Mutex</directive>
+ directive. You will need to evaluate any use of these removed
+ directives in your 2.2 configuration to determine if they can
+ just be deleted or will need to be replaced using <directive
+ module="core">Mutex</directive>.</li>
+
+ <li><module>mod_cache</module>: <directive
+ module="cache">CacheIgnoreURLSessionIdentifiers</directive>
+ now does an exact match against the query string instead of a
+ partial match. If your configuration was using partial
+ strings, e.g. using <code>sessionid</code> to match
+ <code>/someapplication/image.gif;jsessionid=123456789</code>,
+ then you will need to change to the full string
+ <code>jsessionid</code>.
+ </li>
+
+ <li><module>mod_ldap</module>: <directive
+ module="ldap">LDAPTrustedClientCert</directive> is now
+ consistently a per-directory setting only. If you use this
+ directive, review your configuration to make sure it is
+ present in all the necessary directory contexts.</li>
- <!-- <ul>
- </ul> -->
+ </ul>
+ </section>
</section>
<section id="misc">
<title>Misc Changes</title>
+ <ul>
+ <li><module>mod_auto_index</module>: will now extract titles and
+ display descriptions for .xhtml files, which were previously
+ ignored.</li>
+ <li><program>htpasswd</program> now uses MD5 hash by default on
+ all platforms.</li>
+ </ul>
+
+
</section>
<section id="third-party">
<title>Third Party Modules</title>
+ <p>All modules must be recompiled for 2.4 before being loaded.</p>
+
+ <p>Many third-party modules designed for version 2.2 will
+ otherwise work unchanged with the Apache HTTP Server version 2.4.
+ Some will require changes; see the <a href="new_api_2_4.html">API
+ update</a> overview.</p>
+ </section>
+ <section id="commonproblems">
+ <title>Common problems when upgrading</title>
+ <ul><li>Startup errors:
+ <ul>
+ <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>
+ <li><code>Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration</code>, or
+<code>Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration</code>
+ - load module <module>mod_access_compat</module>, or update configuration to 2.4 authorization directives.</li>
+ <li><code>Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf</code> - remove <directive module="core">DefaultType</directive>
+ and replace with other configuration settings.</li>
+ </ul></li>
+ <li>Errors serving requests:
+ <ul>
+ <li><code>configuration error: couldn't check user: /path</code> -
+ load module <module>mod_authn_core</module>.</li>
+ </ul>
+ </li>
+</ul>
</section>
</manualpage>
Re: svn commit: r956396 - /httpd/httpd/trunk/docs/manual/upgrading.xml
Posted by Chris Darroch <ch...@pearsoncmg.com>.
poirier@apache.org wrote:
> Author: poirier
> Date: Sun Jun 20 19:48:13 2010
> New Revision: 956396
>
> URL: http://svn.apache.org/viewvc?rev=956396&view=rev
> Log:
> First pass at documentation for upgrading to 2.4.
> Went through CHANGES and tried to pick out things that would
> require a 2.2 user to make changes for 2.4.
>
> Modified:
> httpd/httpd/trunk/docs/manual/upgrading.xml
>
> Modified: httpd/httpd/trunk/docs/manual/upgrading.xml
> URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/upgrading.xml?rev=956396&r1=956395&r2=956396&view=diff
> ==============================================================================
> --- httpd/httpd/trunk/docs/manual/upgrading.xml (original)
> +++ httpd/httpd/trunk/docs/manual/upgrading.xml Sun Jun 20 19:48:13 2010
[snip]
> <section id="run-time">
> <title>Run-Time Configuration Changes</title>
> + <p>There have been significant changes in authorization configuration,
> + and other minor configuration changes, that could require changes to your 2.2
> + configuration files before using them for 2.4.</p>
> +
> + <section id="authz">
> + <title>Authorization</title>
> +
> + <p>Any configuration file that uses authorization will likely
> + need changes.</p>
> +
> + <p>You should review the <a href="howto/auth.html">Authentication,
> + Authorization and Access Control Howto</a>, especially the section
> + <a href="howto/auth.html#beyond">Beyond just authorization</a>
> + which explains the new mechanisms for controlling the order in
> + which the authorization directives are applied.</p>
> +
> + <section id="access">
> + <title>Access control</title>
> +
> + <p>In 2.2, access control based on client hostname, IP address,
> + and other characteristics of client requests was done using the
> + directives <directive
> + module="mod_access_compat">Order</directive>, <directive
> + module="mod_access_compat">Allow</directive>, <directive
> + module="mod_access_compat">Deny</directive>, and <directive
> + module="mod_access_compat">Satisfy</directive>.</p>
> +
> + <p>In 2.4, such access control is done in the same way as other
> + authorization checks, using the new module
> + <module>mod_authz_host</module>. The old access control idioms
> + should be replaced by the new authentication mechanisms,
> + although for compatibility with old configurations, the new
> + module <module>mod_access_compat</module> is provided.</p>
> +
> + <p>Here are some examples of old and new ways to do the same
> + access control.</p>
> +
> + <p>In this example, all requests are denied.</p>
> + <example>
> + <title>2.2 configuration:</title>
> + Order deny,allow<br />
> + Deny from all
> + </example>
> + <example>
> + <title>2.4 configuration:</title>
> + Require all denied
> + </example>
> +
> + <p>In this example, all requests are allowed.</p>
> + <example>
> + <title>2.2 configuration:</title>
> + Order allow,deny<br />
> + Allow from all
> + </example>
> + <example>
> + <title>2.4 configuration:</title>
> + Require all granted
> + </example>
> +
> + <p>In the following example, all hosts in the apache.org domain
> + are allowed access; all other hosts are denied access.</p>
> +
> + <example>
> + <title>2.2 configuration:</title>
> + Order Deny,Allow<br />
> + Deny from all<br />
> + Allow from apache.org
> + </example>
> + <example>
> + <title>2.4 configuration:</title>
> + Require host apache.org
> + </example>
> + </section>
Thanks for the work on documenting the trunk/2.4 authn/z stuff -- as
usual, I've been swamped with other work and unable to circle back to
any of it. Hopefully I can provide bits of info and support, though,
to help push 2.4 on its way.
One thing I should note overall about any work I did in the last
year or two is that the intention was always to ensure that (a) existing
modules written for 2.2 should continue to function without changes, and
(b) existing httpd configurations from 2.2 should work out-of-the-box
(so long as you loaded the necessary modules in 2.4), and not lose any
degree of security or functionality. I can't say that those goals were
achieved 100%, but that was the intention, at least. The previous
rewrite of trunk authn/z, which introduced the "containers", created
a number of incompatibilities, and the idea was to iron those out.
I think you've captured the key issues here very neatly. Thank you,
Chris.
--
GPG Key ID: 088335A9
GPG Key Fingerprint: 86CD 3297 7493 75BC F820 6715 F54F E648 0883 35A9