PackagingDrafts/ApacheHTTPModules

This is a draft document

Guidelines for Packaging of Apache HTTP Server Modules

Introduction

The Apache HTTP Server (httpd) can be used with a wide variety of third-party modules, a large number of which are packaged in Fedora as loadable modules.

This document describes best practice for packages containing such modules.

Build Environment

Packages which build against httpd MUST depend on httpd-devel. The minimum version against which the package will build should be specified. For example:

BuildRequires: httpd-devel >= 2.0.42

Most modules will use the apxs script to determine the correct compiler invocation. The %{_httpd_apxs} macro MUST be used to determine the correct location of the apxs script supplied by httpd-devel. The following expansion can be used for backwards-compatibility with versions of httpd-devel which do not define this macro.

%{!?_httpd_apxs: %{expand: %%global _httpd_apxs %%{_sbindir}/apxs}}

Run-Time Dependencies

A binary httpd module file (mod_foo.so) can only be used with a version of httpd which has a particular binary module interface. This is enforced at run-time. If mod_foo.so was built against httpd 2.0.52, it cannot be loaded by httpd 2.2.1, for example. The binary module interface changes only over minor version number hikes; from 2.0 to 2.2, and from 2.2 to 2.4. The version number of the binary module interface is called the Module Magic Number (MMN).

Current versions of the httpd package export the MMN in two ways: through a file (/usr/include/httpd/.mmn) and through an RPM macro, %_httpd_mmn. Any package containing a binary httpd module MUST have a dependency on the httpd-mmn virtual provide, which will ensure it the module is only used with an httpd package providing the same binary module interface. Example:

%{!?_httpd_mmn: %{expand: %%global _httpd_mmn %%(cat %{_includedir}/httpd/.mmn || echo 0-0)}}

Name: mod_blah
Version: 1.0
...
Requires: httpd-mmn = %{_httpd_mmn}

If the module package depends on a binary interface introduced in a point release of httpd (say, 2.2.19), it can reflect that by conflicting with older packages. Example:

Requires: httpd-mmn = %{_httpd_mmn}
Conflicts: httpd < 2.2.19

New Configuration Directory Layout

With existing httpd 2.x packages, it is customary to place module configuration in a single file in /etc/httpd/conf.d. This leads to some problems with load-order dependencies, and of separating packaged configuration from configuration files created (or modified) by the administrator.

This proposal introduces a new separate directory which is used purely for LoadModule directives, /etc/httpd/conf.modules.d. A new minimal default httpd.conf is introduced, which processes configuration in this order:

1. all files in conf.modules.d
2. the body of httpd.conf
3. all files in conf.d

The conf.modules.d directory is intended to be used mainly by packaged modules, so these modules can ensure the correct load ordering without any concern about what user changes to httpd.conf or conf.d/*.conf have been made.

This new split-directory configuration will be introduced with httpd 2.4.x and not backported to httpd 2.2 in older Fedora releases.

Module Configuration

When a package containing an httpd module is installed, the module SHOULD be loaded by default when the httpd service is next restarted. The stub configuration file SHOULD only contain the LoadModule line necessary to load the module. Example:

LoadModule blah_module modules/mod_blah.so

This stub file should be placed in the directory %{_httpd_modconfdir} (/etc/httpd/conf.modules.d), and must have a .conf extension.

If specific configuration directives are required (or desired) to enable the module by default, these should be placed in a separate configuration file in the directory %{_httpd_confdir} (/etc/httpd/conf.d). For example, PHP might contain two configuration files; firstly, /etc/httpd/conf.modules.d/php.conf containing:

LoadModule php5_module modules/libphp5.so 

and a separate file /etc/httpd/conf.d/php.conf to associate the PHP handler with the .php extension:

AddHandler php5-script .php
AddType text/html .php

Filesystem Conventions

The following sections describe the appropriate locations for packaging of files used by httpd modules.

Binary Module

The binary module (mod_blah.so) SHOULD be placed in %{_httpd_moddir} (%{_libdir}/httpd/modules).

Unmutable Content

If the package contains some content intended to be served, but not modified by the administrator, it should be placed in the location specified by the %_httpd_contentdir macro. [Fedora 18+ only]