From Fedora Project Wiki
No edit summary
No edit summary
 
(14 intermediate revisions by 2 users not shown)
Line 10: Line 10:
This document describes best practice for packages containing such modules.
This document describes best practice for packages containing such modules.


== Build-Time Dependencies ==
== Build Environment ==


Packages which build against httpd '''MUST''' depend on <code>httpd-devel</code>.  The minimum version against which the package will build should be specified.
Packages which build against httpd '''MUST''' depend on <code>httpd-devel</code>.  The minimum version against which the package will build should be specified.
Line 32: Line 32:


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


Name: mod_blah
Name: mod_blah
Line 44: Line 44:
<pre>
<pre>
Requires: httpd-mmn = %{_httpd_mmn}
Requires: httpd-mmn = %{_httpd_mmn}
Conflicts: httpd < 2.2.18
Conflicts: httpd < 2.2.19
</pre>
</pre>


== Run-Time Configuration ==
== New Configuration Directory Layout ==


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 <code>LoadModule</code> line
With existing httpd 2.x packages, it is customary to place module configuration in a single file in <code>/etc/httpd/conf.d</code>.  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 <code>LoadModule</code> directives, <code>/etc/httpd/conf.modules.d</code>.  A new minimal default <code>httpd.conf</code> is introduced, which processes configuration in this order:
 
# all files in conf.modules.d
# the body of httpd.conf
# all files in conf.d
 
The <code>conf.modules.d</code> 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 <code>httpd.conf</code> or <code>conf.d/*.conf</code> 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 <code>LoadModule</code> line
necessary to load the module.  Example:
necessary to load the module.  Example:


Line 56: Line 70:
</pre>
</pre>


Most modules will not have any effect on the server behaviour in this configuration; further user configuration will be required to activate them in some way.
This stub file should be placed in the directory <code>%{_httpd_modconfdir}</code> (<code>/etc/httpd/conf.modules.d</code>), and must have a <code>.conf</code> 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 <code>%{_httpd_confdir}</code> (<code>/etc/httpd/conf.d</code>).  For example, PHP might contain two configuration files; firstly, <code>/etc/httpd/conf.modules.d/php.conf</code> containing:
 
<pre>
LoadModule php5_module modules/libphp5.so
</pre>
 
and a separate file <code>/etc/httpd/conf.d/php.conf</code> to associate the PHP handler with the .php extension:


As an exception, if the act of loading the module will change server behaviour without further configuration, the <code>LoadModule</code> line may be commented-out by default, as desired.
<pre>
AddHandler php5-script .php
AddType text/html .php
</pre>


== Filesystem Conventions ==
== Filesystem Conventions ==
Line 66: Line 91:
=== Binary Module ===
=== Binary Module ===


The binary module (<code>mod_blah.so</code>) '''SHOULD''' be placed in <code>%{_libdir}/httpd/modules</code>.
The binary module (<code>mod_blah.so</code>) '''SHOULD''' be placed in <code>%{_httpd_moddir}</code> (<code>%{_libdir}/httpd/modules</code>).
 
=== Configuration Files ===
 
The stub configuration file used only to load the httpd binary module should be placed in the location indicated by the <code>%_httpd_modconfdir</code> macro.  For compatibility with versions of httpd which don't define this macro, the following expansion can be used:
 
<pre>
%{!?_httpd_modconfdir: %{expand: %%global _httpd_modconfdir %%{_sysconfigdir}/httpd/conf.d}}
</pre>


=== Unmutable Content ===
=== 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 <code>%_httpd_contentdir</code> macro.
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 <code>%_httpd_contentdir</code> macro. [Fedora 18+ only]

Latest revision as of 10:53, 30 January 2014

Warning.png
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]