Apache Developer Documentation

1.  Apache Module Howto

Overview

This chapter will guide a developer through creating an ebuild using one of our more complex packages, www-apache/mod_ldap_userdir as an example. All Apache modules need to use the apache-module.eclass in order to work with future changes to the apache core.

Apache Path Locations

In order to closely follow how upstream and other distributions install apache, the following paths must be used as specified by depend.apache.eclass:

Overview of apache-module ebuilds

• Generally all functions can be removed from the ebuild
• Check to see if the default src_compile in the eclass will work. If not, set APXS2_ARGS to compile other files as required.
• Replace any DEPEND on Apache with one of the need_apache* functions described in the depend.apache.eclass documentation.
• Create the module configuration file to use IfDefines to load and configure the module
• Add any documentation files to DOCFILES
• Specify the configuration file src_install should install: APACHE2_MOD_CONF
• Specify the IfDefine that the module uses in its configuration file so pkg_postinst can give user information on how to enable the module: APACHE2_MOD_DEFINE

Ebuild Globals

inherit apache-module

DESCRIPTION="Apache module that enables ~/public_html from an LDAP directory."
HOMEPAGE="http://horde.net/~jwm/software/mod_ldap_userdir/"
SRC_URI="http://horde.net/~jwm/software/mod_ldap_userdir/${P}.tar.gz"

LICENSE="GPL-1"
SLOT="0"
KEYWORDS="~ppc ~x86"
IUSE="ssl"

DEPEND="ssl? ( dev-libs/openssl )
    net-nds/openldap"
RDEPEND="${DEPEND}"

DOCFILES="DIRECTIVES README user-ldif posixAccount-objectclass"

APXS2_ARGS="-lldap -llber -c ${PN}.c"
APACHE2_MOD_CONF="47_mod_ldap_userdir"
APACHE2_MOD_DEFINE="LDAP_USERDIR"

need_apache2_2

We start off with inherit apache-module which also inherits depend.apache. depend.apache defines the locations Apache uses and more importantly, defines three DEPENDs: APACHE2_2_DEPEND for those packages that need Apache-2.2*, APACHE2_DEPEND for those packages that need Apache-2*, and APACHE_DEPEND for those packages that need either any version of Apache.

apache-module does the heavy lifting for the module packages by defining sane defaults for pkg_setup, src_compile, src_install and pkg_postinst.

depend.apache handles adding the correct Apache DEPEND to your DEPEND (if you call one of the need_apache* functions) so you can skip the apache DEPEND handling in your ebuild.

DOCFILES is used by the src_install in apache-modules to install all the documentation. src_install automatically detects html files and other files and uses either dodoc or dohtml to install them to their correct locations.

APACHE2_MOD_CONF define the configuration file to install for the module. This is used during src_install and needs to be relative to FILESDIR. See the apache-module.eclass documentation for details.

APACHE2_MOD_DEFINE tells the eclass which <IfDefine MODULENAME> the module uses. It is used for displaying instructions to the user on how to enable the module.

src_compile

src_compile may be needed if the module requires special steps that the eclass can't handle. This would be a rare case. In most cases, just reviewing the Makefile and adding items to APXS2_ARGS will be sufficient.

src_compile() {
    econf || die "econf failed"
    use ssl && APXS2_ARGS="${APXS2_ARGS} -DTLS=1"
    apache-module_src_compile
}

src_install

In most cases, src_install will not be needed. The exceptions are when there are other directories that need to be installed or when file permissions need to be changed.

src_install() {
    apache-module_src_install
    fperms 600 "${APACHE_MODULES_CONFDIR}"/47_mod_ldap_userdir.conf
}

As you can see, in mod_ldap_userdir we need to set the proper permissions on its configuration file. But we still let apache-module strut it's stuff by calling apache-module_src_install inside our src_install. In most cases, src_install will not be needed at all.

src_install completely handles installing the module, configuration files and documentation into the correct places.

Other functions

In most cases, there should not be any pkg_postinst or pkg_config as the eclass handles outputting instructions to the user about enabling a module and where the configuration file is. If additional setup instructions are needed, then a pkg_postinst can be added, but should also run apache-module_pkg_postinst inside it.

With the default configuration of Apache, we dont't need to have the user modify their httpd.conf to enable a module. All the *.conf files in the modules.d directory are included automatically. Every file there should be completely wrapped in an <IfDefine MODULENAME> block so that the directives in that file are only used if the user adds a "-D MODULENAME" to their /etc/conf.d/apache2 file.

Configuration file

Every module configuration file needs to be wrapped in <IfDefine MODULENAME> blocks. If you don't do this, then Apache will load the module by default, which we don't want - module loading is to be controlled by the user, using the /etc/conf.d/apache2 file.

<IfDefine LDAP_USERDIR>
LoadModule ldap_userdir_module modules/mod_ldap_userdir.so

# Put a good default configuration here:
LDAPUserDir             public_html
LDAPUserDirDNInfo       cn=root,dc=yourcompany,dc=com yourpassword
LDAPUserDirBaseDN       ou=People,dc=yourcompany,dc=com

</IfDefine>

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.