Project:Apache/Upgrading
This document describes the procedure end-users should follow to safely upgrade their apache installation.
Upgrading from <2.2.6-r4
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_MPMSUSE_EXPANDvariable no-suexecis nowsuexecstatic-modulesis nowstatic
For a detailed description of old and corresponding new USE flags see below.
Upgrading from <2.0.52-r3
Introduction
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 .
Upgrading
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
The packages you have installed may be vastly different; make sure you run this command for yourself.
There are some modules and packages that depend on Apache that have not yet been updated. Please search bugzilla for any critical packages that you use with Apache.
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 below 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 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{ . 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{} 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.
Many modules that used to be enabled by default are now disabled. If they are apache built-in modules, then uncomment the appropriate line in httpd.conf. If they are external modules, check the module's .conf for
IfDefine and add the name to /etc/conf.d/apache{} to enable it.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 (webchat) for support.
Supported USE flags in <2.2.6-r4
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.
| USE flag | Description |
|---|---|
| apache2 | Should always be set if using the Apache-2.0 line, should not be set if using the Apache-1.3 line. The eclass uses this to determine what version of apache to depend on. |
| debug | Enables a hook that allows external modules to plug in and do something after a child crashed. There are already two modules, mod_whatkilledus and mod_backtrace that make use of this hook.
|
| doc | Install the Apache manual and configuration. |
| ldap | Install mod_ldap and mod_auth_ldap/ mod_authnz_ldap .
|
| ssl | Installs mod_ssl .
|
| mpm-itk | Builds the itk MPM |
| mpm-leader | Builds the leader MPM |
| mpm-peruser | Builds the peruser MPM |
| mpm-prefork | Builds the prefork MPM |
| mpm-threadpool | Builds the threadpool MPM |
| mpm-worker | Builds the worker MPM |
| static-modules | Statically links the modules into the apache binary, so that a LoadModule isn't required for loading the base modules into Apache. |
While there are many
mpm-* USE flags, they are mutually exclusive. You should enable one and only one of the mpm-* USE flags. (If you do not enable one, mpm-prefork or mpm-worker will be used, depending on if the threads USE flag is set.)Supported USE flags in 2.2.6-r4 and above
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.
| USE flag | Old USE flag | Description |
|---|---|---|
| debug | debug | Enables a hook that allows external modules to plug in and do something after a child crashed. There are already two modules, mod_whatkilledus and mod_backtrace , that make use of this hook.
|
| doc | doc | Install the Apache manual and configuration. |
| ldap | ldap | Install mod_ldap and mod_authnz_ldap
|
| ssl | ssl | Installs mod_ssl
|
| static | static-modules | Statically links the modules into the apache binary, so that a LoadModule isn't required for loading the base modules into Apache |
| suexec | no-suexec | Install mod_suexec and the suexec helper binary
|
| threads | threads | Selects the default MPM if none is set in APACHE2_MPMS |
The following table lists supported APACHE2_MPMS as of apache-2.2.6-r4 and their corresponding previous local USE flag.
| Flag | Old USE flag | Description |
|---|---|---|
| event | mpm-event | An experimental variant of the standard worker MPM |
| itk | mpm-itk | Allows to run each virtual host under a separate uid and gid |
| peruser | mpm-peruser | Peruser is a working implementation of the perchild MPM allowing to run each apache child process as its own user and group, each handling its own set of virtual hosts |
| prefork | mpm-prefork | Implements a non-threaded, pre-forking web server |
| worker | mpm-worker | Multi-Processing Module implementing a hybrid multi-threaded multi-process web server |
The following table lists supported APACHE2_MODULES as of apache-2.2.6-r4 .
| Flag | Description |
|---|---|
| actions | Provides for executing CGI scripts based on media type or request method |
| alias | Provides for mapping different parts of the host filesystem in the document tree and for URL redirection |
| asis | Sends files that contain their own HTTP headers |
| auth_basic | Basic authentication |
| auth_digest | User authentication using MD5 Digest Authentication |
| authn_alias | Provides the ability to create extended authentication providers based on actual providers |
| authn_anon | Allows "anonymous" user access to authenticated areas |
| authn_dbd | User authentication using an SQL database |
| authn_dbm | User authentication using DBM files |
| authn_default | Authentication fallback module |
| authn_file | User authentication using text files |
| authz_dbm | Group authorization using DBM files |
| authz_default | Authorization fallback module |
| authz_groupfile | Group authorization using plaintext files |
| authz_host | Group authorizations based on host (name or IP address) |
| authz_owner | Authorization based on file ownership |
| authz_user | User Authorization |
| autoindex | Generates directory indexes automatically, similar to the Unix ls command
|
| cache | Content cache keyed to URIs |
| cern_meta | CERN httpd metafile semantics |
| charset_lite | Specify character set translation or recoding |
| dav | Distributed Authoring and Versioning (WebDAV) functionality |
| dav_fs | filesystem provider for mod_dav |
| dav_lock | generic locking module for mod_dav |
| dbd | Manages SQL database connections |
| deflate | Compress content before it is delivered to the client |
| dir | Provides for "trailing slash" redirects and serving directory index files |
| disk_cache | Content cache storage manager keyed to URIs |
| dumpio | Dumps all I/O to error log as desired |
| env | Modifies the environment which is passed to CGI scripts and SSI pages |
| expires | Generation of Expires and Cache-Control HTTP headers according to user-specified criteria |
| ext_filter | Pass the response body through an external program before delivery to the client |
| file_cache | Caches a static list of files in memory |
| filter | Context-sensitive smart filter configuration module |
| headers | Customization of HTTP request and response headers |
| ident | RFC 1413 ident lookups |
| imagemap | Server-side imagemap processing |
| include | Server-parsed html documents (Server Side Includes) |
| info | Provides a comprehensive overview of the server configuration |
| log_config | Logging of the requests made to the server |
| log_forensic | Forensic Logging of the requests made to the server |
| logio | Logging of input and output bytes per request |
| mem_cache | Content cache keyed to URIs |
| mime | Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding) |
| mime_magic | Determines the MIME type of a file by looking at a few bytes of its contents |
| negotiation | Provides for content negotiation |
| proxy | HTTP/1.1 proxy/gateway server |
| proxy_ajp | AJP support module for mod_proxy |
| proxy_balancer | mod_proxy extension for load balancing |
| proxy_connect | mod_proxy extension for CONNECT request handling |
| proxy_ftp | FTP support module for mod_proxy |
| proxy_http | HTTP support module for mod_proxy |
| rewrite | Provides a rule-based rewriting engine to rewrite requested URLs on the fly |
| setenvif | Allows the setting of environment variables based on characteristics of the request |
| speling | Attempts to correct mistaken URLs that users might have entered by ignoring capitalization and by allowing up to one misspelling |
| status | Provides information on server activity and performance |
| unique_id | Provides an environment variable with a unique identifier for each request |
| userdir | User-specific directories |
| usertrack | Clickstream logging of user activity on a site |
| version | Version dependent configuration |
| vhost_alias | Provides for dynamically configured mass virtual hosting |
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Michael Stewart, hollow,
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.