+ <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>
+
+ <h3><a name="authz" id="authz">Authorization</a></h3>
+
+
+ <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>
+
+ <p>Directives that control how authorization modules respond when they don't match
+ the authenticated user have been removed: This includes
+ AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative,
+ AuthzGroupFileAuthoritative, AuthzUserAuthoritative,
+ and AuthzOwnerAuthoritative. These directives have been replaced by the
+ more expressive <code class="directive"><a href="./mod/mod_authz_core.html#requireany">RequireAny</a></code>,
+ <code class="directive"><a href="./mod/mod_authz_core.html#requirenone">RequireNone</a></code>, and
+ <code class="directive"><a href="./mod/mod_authz_core.html#requireall">RequireAll</a></code>.</p>
+
+ <p>If you use <code class="module"><a href="./mod/mod_authz_dbm.html">mod_authz_dbm</a></code>, you must port your
+ configuration to use <code>Require dbm-group ...</code> in place
+ of <code>Require group ...</code>.</p>
+
+ <h4><a name="access" id="access">Access control</a></h4>
+
+
+ <p>In 2.2, access control based on client hostname, IP address,
+ and other characteristics of client requests was done using the
+ directives <code class="directive"><a href="./mod/mod_access_compat.html#order">Order</a></code>, <code class="directive"><a href="./mod/mod_access_compat.html#allow">Allow</a></code>, <code class="directive"><a href="./mod/mod_access_compat.html#deny">Deny</a></code>, and <code class="directive"><a href="./mod/mod_access_compat.html#satisfy">Satisfy</a></code>.</p>
+
+ <p>In 2.4, such access control is done in the same way as other
+ authorization checks, using the new module
+ <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code>. The old access control idioms
+ should be replaced by the new authentication mechanisms,
+ although for compatibility with old configurations, the new
+ module <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> is provided.</p>
+
+ <div class="note"><h3>Mixing old and new directives</h3>
+ <p>Mixing old directives like <code class="directive"><a href="./mod/mod_access_compat.html#order">Order</a></code>, <code class="directive"><a href="./mod/mod_access_compat.html#allow">Allow</a></code> or <code class="directive"><a href="./mod/mod_access_compat.html#deny">Deny</a></code> with new ones like
+ <code class="directive"><a href="./mod/mod_authz_core.html#require">Require</a></code> is technically possible
+ but discouraged. <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> was created to support
+ configurations containing only old directives to facilitate the 2.4 upgrade.
+ Please check the examples below to get a better idea about issues that might arise.
+ </p>
+ </div>
+
+ <p>Here are some examples of old and new ways to do the same
+ access control.</p>
+
+ <p>In this example, there is no authentication and all requests are denied.</p>
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order deny,allow
+Deny from all</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require all denied</pre>
+</div>
+
+ <p>In this example, there is no authentication and all requests are allowed.</p>
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order allow,deny
+Allow from all</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require all granted</pre>
+</div>
+
+ <p>In the following example, there is no authentication and all hosts in the example.org domain
+ are allowed access; all other hosts are denied access.</p>
+
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order Deny,Allow
+Deny from all
+Allow from example.org</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">Require host example.org</pre>
+</div>
+
+ <p>In the following example, mixing old and new directives leads to
+ unexpected results.</p>
+
+ <div class="example"><h3>Mixing old and new directives: NOT WORKING AS EXPECTED</h3><pre class="prettyprint lang-config">DocumentRoot "/var/www/html"
+
+<Directory "/">
+ AllowOverride None
+ Order deny,allow
+ Deny from all
+</Directory>
+
+<Location "/server-status">
+ SetHandler server-status
+ Require 127.0.0.1
+</Location>
+
+access.log - GET /server-status 403 127.0.0.1
+error.log - AH01797: client denied by server configuration: /var/www/html/server-status</pre>
+</div>
+ <p>Why httpd denies access to servers-status even if the configuration seems to allow it?
+ Because <code class="module"><a href="./mod/mod_access_compat.html">mod_access_compat</a></code> directives take precedence
+ over the <code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</a></code> one in this configuration
+ <a href="sections.html#merging">merge</a> scenario.</p>
+
+ <p>This example conversely works as expected:</p>
+
+ <div class="example"><h3>Mixing old and new directives: WORKING AS EXPECTED</h3><pre class="prettyprint lang-config">DocumentRoot "/var/www/html"
+
+<Directory "/">
+ AllowOverride None
+ Require all denied
+</Directory>
+
+<Location "/server-status">
+ SetHandler server-status
+ Order deny,allow
+ Deny from all
+ Allow From 127.0.0.1
+</Location>
+
+access.log - GET /server-status 200 127.0.0.1</pre>
+</div>
+ <p>So even if mixing configuration is still
+ possible, please try to avoid it when upgrading: either keep old directives and then migrate
+ to the new ones on a later stage or just migrate everything in bulk.
+ </p>
+
+
+ <p>In many configurations with authentication, where the value of the
+ <code class="directive">Satisfy</code> was the default of <em>ALL</em>, snippets
+ that simply disabled host-based access control are omitted:</p>
+
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order Deny,Allow
+Deny from all
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config"># No replacement needed
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user</pre>
+</div>
+
+ <p>In configurations where both authentication and access control were meaningfully combined, the
+ access control directives should be migrated. This example allows requests meeting <em>both</em> criteria:</p>
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order allow,deny
+Deny from all
+# Satisfy ALL is the default
+Satisfy ALL
+Allow from 127.0.0.1
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+<RequireAll>
+ Require valid-user
+ Require ip 127.0.0.1
+</RequireAll></pre>
+</div>
+
+ <p>In configurations where both authentication and access control were meaningfully combined, the
+ access control directives should be migrated. This example allows requests meeting <em>either</em> criteria:</p>
+ <div class="example"><h3>2.2 configuration:</h3><pre class="prettyprint lang-config">Order allow,deny
+Deny from all
+Satisfy any
+Allow from 127.0.0.1
+AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+Require valid-user</pre>
+</div>
+ <div class="example"><h3>2.4 configuration:</h3><pre class="prettyprint lang-config">AuthBasicProvider File
+AuthUserFile /example.com/conf/users.passwd
+AuthName secure
+# Implicitly <RequireAny>
+Require valid-user
+Require ip 127.0.0.1</pre>
+</div>
+
+
+
+ <h3><a name="config" id="config">Other configuration changes</a></h3>
+
+
+ <p>Some other small adjustments may be necessary for particular
+ configurations as discussed below.</p>
+
+ <ul>
+ <li><code class="directive">MaxRequestsPerChild</code> has been renamed to
+ <code class="directive"><a href="./mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>,
+ describes more accurately what it does. The old name is still
+ supported.</li>
+
+ <li><code class="directive">MaxClients</code> has been renamed to
+ <code class="directive"><a href="./mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
+ which describes more accurately what it does. For async MPMs, like
+ <code class="module"><a href="./mod/event.html">event</a></code>, the maximum number of clients is not
+ equivalent than the number of worker threads. The old name is still
+ supported.</li>
+
+ <li>The <code class="directive"><a href="./mod/core.html#defaulttype">DefaultType</a></code>
+ 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><code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> now
+ defaults to <code>None</code>.</li>
+
+ <li><code class="directive"><a href="./mod/core.html#enablesendfile">EnableSendfile</a></code> now
+ defaults to Off.</li>
+
+ <li><code class="directive"><a href="./mod/core.html#fileetag">FileETag</a></code> now
+ defaults to "MTime Size" (without INode).</li>
+
+ <li><code class="module"><a href="./mod/mod_dav_fs.html">mod_dav_fs</a></code>: The format of the <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file has changed for
+ systems with inodes. The old <code class="directive"><a href="./mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code> file must be deleted on
+ upgrade.
+ </li>
+
+ <li><code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> 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 <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>
+ 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 <code class="directive"><a href="./mod/core.html#mutex">Mutex</a></code>.</li>
+
+ <li><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>: <code class="directive"><a href="./mod/mod_cache.html#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></code>
+ 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><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>: The second parameter to
+ <code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> only
+ matches forward proxy content if it begins with the correct
+ protocol. In 2.2 and earlier, a parameter of '/' matched all
+ content.</li>
+
+ <li><code class="module"><a href="./mod/mod_ldap.html">mod_ldap</a></code>: <code class="directive"><a href="./mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code> 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>