PackagingDrafts/ApacheHTTPModules

= 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. 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  script to determine the correct compiler invocation. The  macro MUST be used to determine the correct location of the   script supplied by. The following expansion can be used for backwards-compatibility with versions of  which do not define this macro.

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

Run-Time Dependencies
A binary httpd module file can only be used with a version of httpd which has a particular binary module interface. This is enforced at run-time. If  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 and through an RPM macro,. Any package containing a binary httpd module MUST have a dependency on the  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

New Configuration Directory Layout
With existing httpd 2.x packages, it is customary to place module configuration in a single file in. 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  directives,. A new minimal default  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  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   or   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  line necessary to load the module. Example:

LoadModule blah_module modules/mod_blah.so

This stub file should be placed in the directory , and must have a   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. For example, PHP might contain two configuration files; firstly,  containing:

LoadModule php5_module modules/libphp5.so

and a separate file  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 SHOULD be placed in.

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  macro. [Fedora 18+ only]