The Apache ebuilds have used /etc/apache2/apache2-builtin-mods for a very long time to select the built-in modules during compile time. However, this behavior has several disadvantages:

• Selecting built-in modules during the initial merge is not possible
• Portage does not know which modules have been installed. This is especially annoying for binary packages.
• Portage will try to overwrite apache2-builtin-mods on every upgrade

To rectify this situation /etc/apache2/apache2-builtin-mods has been deprecated and migrated to the new APACHE2_MODULES USE_EXPAND variable. To convert your custom module selection to the new format use the following command:

$ echo APACHE2_MODULES=\"$(sed '/^mod_/s/mod_\(.*\)\s\+\(shared\|static\)/\1/;t n;d;:n' /etc/apache2/apache2-builtin-mods)\" >> /etc/make.conf
# rm /etc/apache2/apache2-builtin-mods

(You can now safely upgrade apache:)
# emerge -uva '>=www-servers/apache-2.2.6-r4'

Additionally to the new APACHE2_MODULES the local USE flags have been cleaned up:

• All MPM USE flags have been moved to the APACHE2_MPMS USE_EXPAND variable
• no-suexec is now suexec
• static-modules is now static

For a detailed description of old and corresponding new USE flags see below.

The state of Apache and its modules in Gentoo was becoming dismal. There were a number of problems that caused support problems and made maintaining everything the Apache herd is responsible for difficult:

• The configuration that came with Gentoo was dramatically different from the upstream configuration that most users expect
• Many modules used similar code, but all did things their own way
• Most modules weren't maintained very well - mostly because of the large number of modules available
• Modules didn't have a configuration standard
• Some modules could support both versions of Apache, but the ebuilds didn't handle that
• Choices available in Apache were not available for Gentoo users (for example MPMs)
• Bugs for Apache were stacking up

This document details how to upgrade without breaking your system. If you are a developer or would like to know what we changed, or how ebuilds need to be modified to take advantage of our eclass, then check the Apache Developer Reference.

There have been many changes to how Apache works within Gentoo. Every package that is directly related to Apache needs to be updated and some things that worked previously will no longer work.

First you need to figure out what packages you need to upgrade. You can do this using the equery tool, which is part of the app-portage/gentoolkit package.

$ equery depends www-servers/apache
[ Searching for packages depending on www-servers/apache... ]
dev-db/phpmyadmin-2.5.6
dev-php/mod_php-4.3.10
dev-php/phpsysinfo-2.1-r2
net-www/mod_bandwidth-2.0.5
net-www/mod_layout-4.0.1a
net-www/mod_mp3-0.40
net-www/mod_random-2.0
net-www/mod_throttle-3.1.2-r1
www-apache/mod_ldap_userdir-1.1.4
www-apache/mod_loopback-1.04
www-apache/mod_watch-3.18
www-apps/viewcvs-0.9.2_p20030430

Many webapps aren't affected in any way as most use the webapp eclass which takes care of installing them correctly. You may want to check to see if there is a new revision.

As we have added some new USE flags, you may want to review them and add appropriate lines to /etc/portage/package.use. See Apache supported USE flags for more details.

(Check the USE flags and needed updates)
# emerge --pretend --verbose --update --newuse --deep apache subversion \
mod_php mod_bandwidth mod_layout mod_ldap_userdir mod_loopback mod_mp3 \ 
mod_random mod_throttle mod_watch

(Update the packages)
# emerge --verbose --update --newuse --deep apache subversion mod_php \
mod_bandwidth mod_layout mod_ldap_userdir mod_loopback mod_mp3 mod_random \
mod_throttle mod_watch

(It may be easier to just update world instead of the above)
# emerge --ask --verbose --update --newuse --deep world

Now you need to reconfigure Apache and its modules. Start by using etc-update or dispatch-conf to update the /etc/init.d and /etc/conf.d files. You will notice that your apache configuration files won't show up in the updates - this is because all the configuration files have moved.

If you have made changes to the previous default apache.conf and commonapache.conf you will need to migrate your changes to /etc/apache{|2}/httpd.conf. Also configuration locations for modules and virtual hosts have changed -- they are now located in /etc/apache2/modules.d and /etc/apache2/vhosts.d respectively.

When you have finished migrating your changes to the new configuration file, you will need to delete the old configuration files (or move them to a safe place). The new /etc/init.d/apache{|2} checks for these files and doesn't let you start apache unless you have removed them, indicating that you have reconfigured apache using the new paths.

Now you may restart apache.

# /etc/init.d/apache stop
# /etc/init.d/apache start

If you run into any problems check the Apache Troubleshooting Guide and if that doesn't solve the issue, please report it on Gentoo Bugzilla. Be sure to include the modules you have enabled and (if you are using Apache 2) what MPM USE flag you compiled with (if any). You may also join #gentoo-apache on irc.freenode.net for support.

There are USE flags that are local to apache and its modules. Apache supports several other more generic USE flags such as ssl, but the effect they have on apache doesn't differ much from the effect is has elsewhere, so it's not included in this list. Run a emerge --verbose --pretend apache to see the full listing of supported USE flags.

With the advent of APACHE2_MODULES a general cleanup of USE flags was necessary. The following table lists supported USE flags for apache-2.2.6-r4 and above as well as their equivalent in previous versions.

The following table lists supported APACHE2_MPMS as of apache-2.2.6-r4 and their corresponding previous local USE flag.

The following table lists supported APACHE2_MODULES as of apache-2.2.6-r4.