(Created page with "{{admon/warning|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...") |
No edit summary |
||
| (15 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{admon/warning|This is a draft document}} | {{admon/warning|This is a draft document}} | ||
[[Category:Packaging guidelines drafts]] | |||
= Guidelines for Packaging of Apache HTTP Server Modules = | = Guidelines for Packaging of Apache HTTP Server Modules = | ||
| Line 9: | Line 10: | ||
This document describes best practice for packages containing such modules. | This document describes best practice for packages containing such modules. | ||
== Build | == 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 31: | Line 32: | ||
<pre> | <pre> | ||
%{!?_httpd_mmn: %{expand: %%global _httpd_mmn %%(cat %{_includedir}/httpd/.mmn || echo | %{!?_httpd_mmn: %{expand: %%global _httpd_mmn %%(cat %{_includedir}/httpd/.mmn || echo 0-0)}} | ||
Name: mod_blah | Name: mod_blah | ||
| Line 43: | Line 44: | ||
<pre> | <pre> | ||
Requires: httpd-mmn = %{_httpd_mmn} | Requires: httpd-mmn = %{_httpd_mmn} | ||
Conflicts: httpd < 2.2. | Conflicts: httpd < 2.2.19 | ||
</pre> | </pre> | ||
== | == 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 | 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 55: | Line 70: | ||
</pre> | </pre> | ||
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: | |||
<pre> | |||
AddHandler php5-script .php | |||
AddType text/html .php | |||
</pre> | |||
== Filesystem Conventions == | == Filesystem Conventions == | ||
| Line 65: | Line 91: | ||
=== Binary Module === | === Binary Module === | ||
The binary module (<code>mod_blah.so</code>) '''SHOULD''' be placed in <code>%{ | The binary module (<code>mod_blah.so</code>) '''SHOULD''' be placed in <code>%{_httpd_moddir}</code> (<code>%{_libdir}/httpd/modules</code>). | ||
%{ | |||
</ | |||
=== 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
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:
- all files in conf.modules.d
- the body of httpd.conf
- 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]