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-Time Dependencies

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 missing-httpd-devel)}}

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

Run-Time Configuration

When a package containing an httpd module is installed, the module SHOULD be loaded by default when the httpd service is next restarted. This should be achieved by placing a stub configuration file in the location described below. The stub configuration file need normally 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 %{_libdir}/httpd/modules.

Configuration Files

The stub configuration file used only to load the httpd binary module should be placed in the location indicated by the %_httpd_modconfdir macro. For compatibility with versions of httpd which don't define this macro, the following expansion can be used:

%{!?_httpd_modconfdir: %{expand: %%global _httpd_modconfdir %%{_sysconfigdir}/httpd/conf.d}}

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.