Apache 2.4 on Gentoo with MPM ITK

I recently upgraded my Gentoo development server from Linux Apache 2.2 to Apache 2.4. Though there are some notable changes between Apache 2.2 and Apache 2.4, the ITK MPM required some configuration to be able to use it.

And in a hurry with a broken Apache, it was sort of difficult to find good results online.

With Apache 2.2, the ITK MPM is embedded with the ebuild and included in the build when building Apache with setting APACHE2_MPMS to itk in /etc/make.conf.

# /etc/make.conf
# Old Apache 2.2 configuration
APACHE2_MPMS="itk"

With the new Apache 2.4, there where two changes I had to make. One was the Order to Require change, the other was ITK changes.

Apache 2.4 upgrade from Apache 2.2 in Gentoo

I had to do these two steps to make the installation of Apache 2.4 to start (and additional steps per site afterwards).

1. Replace Order with Require in the server configuration.
2. Enable the ITK MPM.
3. Repair any sites with incompitable .htaccess-rules.

Replace Order with Require

This is the easiest step. Apache will tell you what file is wrong, and what is wrong with that particular file.

AH00526: Syntax error on line 450 of /etc/apache2/vhosts.d/10_vhost.conf:
Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration

I’m not going to give a complete guide for all Order combination changes, but here are the most important ones. The one true guide is located at https://httpd.apache.org/docs/2.4/upgrading.html.

Deny all access

This will deny any and every access to this particular part of a site.

2.2 configuration
Order deny,allow
Deny from all

2.4 configuration
Require all denied

Grant all access

This will grant access to anyone and everyone accessing the part of the site where this is defined for.

2.2 configuration:
Order allow,deny
Allow from all

2.4 configuration:
Require all granted

Grant from hostname (not IP!)

Grant access from a hostname (not IP!).

2.2 configuration:
Order Deny,Allow
Deny from all
Allow from example.org

2.4 configuration:
Require host example.org

Grant from IP

Grant from an explicit IP-address.

2.2 configuration:
Order Deny,Allow
Deny from all
Allow from 10.0.0.1/24

2.4 configuration:
Require ip 10.0.0.1/24

Negate options

To negate any configuration, you must first allow it, and the deny it. This will deny 10.0.0.1 all access to the part of the site where this is active.

Require all granted
Require not ip 10.0.0.1

Combining Apache 2.2 and Apache 2.4 configuration

If you’re writing a plugin for WordPress (or any other software running under Apache), you can’t require the users to either use Apache 2.2 or Apache 2.4. Then you must use a syntax which both versions can handle.

Deny all with both 2.2 and 2.4 in one file

# Apache 2.2
<IfModule !mod_authz_core.c>
    Order Deny,Allow
    Deny from all
</IfModule>

# Apache 2.4
<IfModule mod_authz_core.c>
    Require all denied
</IfModule>

Grant/allow all with both 2.2 and 2.4 in one file

# Apache 2.2
<IfModule !mod_authz_core.c>
    Order Allow,Deny
    Allow from all
</IfModule>

# Apache 2.4
<IfModule mod_authz_core.c>
    Require all granted
</IfModule>

Enable the ITK MPM

To enable the ITK MPM, you must emerge it as a separate package, and you probably have to add a keyword to /etc/portage/package.keywords to allow installation of the MPM.

A modern version of portage will give you the option of adding that keyword. All you have to do is to use etc-update to review the changes to the package.keywords file.

emerge -av www-apache/mpm_itk

After the successful emerge, you must edit the Apache service configuration file at /etc/conf.d/apache2. There is a variable called APACHE2_OPTS with a couple of defines.

Within the quotes, add -D MPM_ITK. This will enable loading of the MPM ITK module.

It’s now time to try to restart the Apache 2.4 server.

/etc/init.d/apache2 restart

If the restart is successful, you can start worrying about the next step.

After a successful restart, you must check your sites to see if they are responding as they should. At first I got some 403 forbidden errors due to the ITK MPM wasn’t configured, and then I got a couple 500 Interal Server Errors.

Repair .htaccess files

The cause for the 500 Interal Server Errors was the Order directive being present in the .htaccess-files.

The Apache error_log was very helpful in locating the access files causing all sorts of trouble.

[Mon Apr 04 14:23:12.998370 2016] [core:alert] [pid 25663] [client aa.bb.cc.dd:63910] /var/www/live/htdocs/.htaccess: Invalid command 'order', perhaps misspelled or defined by a module not included in the server configuration, referer

Within a site there may be many hidden .htaccess files. Run this command to find all .htaccess-files with the word order in.

cd /var/www/live/htdocs/
find . -name .htaccess -exec grep -il order {} \;

There are quite a few hidden access files in a WordPress installation…

./webroot/htdocs/.htaccess
./webroot/htdocs/wp-content/plugins/bwp-google-xml-sitemaps/cache/.htaccess
./webroot/htdocs/wp-content/plugins/akismet/.htaccess
./webroot/htdocs/wp-content/plugins/wp-spamshield/.htaccess
./webroot/htdocs/wp-content/plugins/wp-spamshield/js/.htaccess
./webroot/htdocs/wp-content/plugins/wp-spamshield/data/.htaccess
./webroot/htdocs/wp-admin/.htaccess

Make sure all are caught and fixed. Viewing the front page is not enough to weed out all the quirks after an upgrade. Be smart, and find the errors before any visitors do so. It’s also wise to monitor the error logs for a while after an upgrade.