[Pkg-apache-commits] [SCM] Debian packaging for apache2 (Apache HTTPD 2.x) branch, next, updated. fea3d476676d0e8ede7e98faf1dcffd0f865d715
Arno Töll
debian at toell.net
Fri Mar 9 00:09:00 UTC 2012
The following commit has been merged in the next branch:
commit a22255c136c8b396275a4bbc13b74b042275cc19
Author: Arno Töll <debian at toell.net>
Date: Fri Mar 9 00:26:22 2012 +0100
Update documentation
* Write PROGRAMMING hints to module and web application packagers
* Document functions in apache2-maintscript-helper
* Update README.Debian with changes introduced in 2.4
* Stylistic fixes in apache2.conf's embedded documentation
diff --git a/debian/PROGRAMMING b/debian/PROGRAMMING
new file mode 100644
index 0000000..3517743
--- /dev/null
+++ b/debian/PROGRAMMING
@@ -0,0 +1,225 @@
+Contents
+========
+
+ Overview
+
+ Packaging Modules
+
+ Packaging Sites and Configurations for Web Applications
+
+ Tools
+ a2query
+ apache2-maint-helper
+ dh_apache2
+
+
+Overview
+========
+
+The Apache 2 web server package in Debian supports two types of reverse
+dependencies: modules and web applications. They need to be treated differently
+as their requirements are different. We have special requirements how to declare
+dependencies against Apache 2 web server packages depending on the type of
+package. Refer to the respective parts for extensive information.
+
+Furthermore, there are several helper tools available to assist on common tasks.
+These are outlined in their respective sub sections as well. You should use
+these tools to get maintainer scripts and dependencies right.
+
+Packaging Modules
+=================
+
+Modules are packages which are installing third party extensions to the Apache 2
+web server which can be loaded at runtim to extend the functionality of the core
+server. Please realize such modules make us of a stable Application Binary
+Interface (ABI) once compiled which need a recompile if the web server changes.
+Hence be careful how you declare dependencies against the web server. You need
+to make sure it does not break upon upgrades.
+
+A module package providing an Apache module must obey our policies to make sure
+it can be upgraded without breakage at the installation site. To achieve this, a
+package must build-depend on apache2-dev. This package provides the 'apxs'
+compile helper which makes sure the module is compatible with the Apache 2 web
+server and required include header.
+
+The resulting binary package should be called libapache2-mod-<modulename> and
+MUST NOT depend on apache2 or apache2-bin. Instead a module package must depend
+on our virtual package providing the module magic number denoting the ABI
+compatibility version number. The virtual package is called apache2-api-YYYYMMDD
+and guaranteed to be stable among all binary updates. The dh_apache2 helper
+assists to get dependencies right.
+
+The module must install a 'module.load' file to /etc/apache2/modules-available
+where 'module' is the name of the installed module without "mod_" prefix. The
+'.load' file must contain an appropriate "LoadModule" directive only.
+Additionally maintainer can declare module dependencies and conflicts in a magic
+line in '.load' files which need to be resolved to load a module at the
+installation site. This is useful if a module depends that other modules to be
+loaded, or to conflict with other modules if they can't be loaded at the same
+time. a2enmod and a2dismod will parse "# Depends: module[, module]" and "#
+Conflicts: module[, module]" magic comments, for example to load mod_foo:
+
+foo.load:
+
+ # Depends: bar
+ # Conflicts: baz
+ LoadModule foo_module /usr/lib/modules/mod_foo.so
+
+
+Additionally, a 'foo.conf' configuration file can be installed along the 'load'
+file to configure the module if required. This is useful if the module in
+question requires some initial configuration to be useful. No magic comments are
+recognized in '.conf' files.
+
+Maintainer scripts should not invoke a2enmod directly. Instead, the
+apache2-maintscript-helper should be used. Please realize, the helper is not
+guaranteed to be installed on the target system. There are certain setups which
+do not require Debian specific configurations, so modules must not do anything
+in maintainer scripts which makes use of Debian specific enhancements like
+apache2-maintscript-helper, a2enmod or a2query unconditionall. It is recommended
+to invoke it like this:
+
+ if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
+ . /usr/share/apache2/apache2-maintscript-helper
+ apache2_invoke enmod foo
+ fi
+
+The dh_apache2 helper can be used to install module configuration and load
+files. Additionally it generates appropriate maintainer scripts. The
+apache2-maintscript-helper provides a few functions for common tasks. See their
+respective reference documentations below.
+
+Packaging Sites and Configurations for Web Applications
+=======================================================
+
+Web applications are different to modules in a way, that they do not have a hard
+dependency agains the web server. Typically they require a running web server,
+but they do not need to worry about binary compatibility of modules. We accept
+there are other web servers aside of Apache, thus we discourage package
+maintainer of web applications not to depend unconditionally on Apache. That
+said, we provide several helper to assist web application packagers to invoke
+configuration snippets to enable a web application in the Apache 2 web server.
+
+We differentiate between two sub types: Site configuration and global
+configuration. Sites are installed to /etc/apache2/sites-available and should
+configure particular virtual hosts. Special care must be taken when installing a
+site configuration to mak sure it does not interfere with site local
+configuration the administrator uses.
+The globale configuration snippets are installed to /etc/apache2/conf-available
+instead. Package maintainers are advised to avoid "local-" prefixes to installed
+conffiles, and ideally use "packagename.conf" to avoid name clashes. This type
+of configration shall be used when installing a global (i.e. virtual host
+independent) configuration. In both cases dh_apache2 can be used to assist
+packagers.
+
+Web applications must depend (or recommend) apache2 only. Web applications must
+not depend or recommend apache2-bin or apache2-data packages. Generally web
+server dependencies should be declared in the form:
+
+ Depends: apache2 | <alternative web servers you support> | httpd-cgi
+
+Using dh_apache2 assists you to do so, although dh_apache2 declares a weaker
+Recommends relation only. If your web application depends on a particular web
+server module you need to depend on it, too. For example, PHP applications might
+need to formulate dependency lines in the form:
+
+ Depends: libapache2-mod-php5 | php5-cgi | php5-fpm
+ Recommends: apache2 | <alternative web servers you support> | httpd-cgi
+
+Similar to modules, web applications can enable their configuration files in
+maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally
+special care must be taken not to use Apache2 Debian helper scripts like a2query
+and a2enmod unconditionally. You can use the apache2-maintscript-helper tools
+provided by the apache2 package for common tasks this way:
+
+ if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
+ . /usr/share/apache2/apache2-maintscript-helper
+ apache2_invoke enconf foo
+ fi
+
+Refer to the reference documentation below to learn how to use
+apache2-maintscript-helper. Do not enable or disable modules in web
+application maintainer scripts, instead protect your configuration by <IfModule>
+clauses if you require non-standard modules.
+
+Tools
+=====
+
+apache2-maint-helper
+--------------------
+
+The apache2-maint-helper is a collection of functions which can be sourced in
+maintainer scripts to do often required tasks in a simple and standardized way
+to package maintainers. It is NOT a script, it is a library (insofar shell
+functions can be called as such). The helper is installed within the apache2
+binary package. Thus you MUST NOT use any function of it unconditionally, as for
+both modules and web applications there are use cases when this package is not
+added as a dependency. Thus, use it in a protected conditional like this only:
+
+ if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
+ . /usr/share/apache2/apache2-maintscript-helper
+ <call apache2-maintscript-helper specific functions>
+ fi
+
+If you use various debhelper, chances are the apache2-maintscript-helper was
+already sourced. In such cases you can check the
+$EXPORT_APACHE2_MAINTSCRIPT_HELPER variable which is defined once the helper was
+loaded. For example in a clause like this:
+
+ if [ -z $EXPORT_APACHE2_MAINTSCRIPT_HELPER ] ; then
+ . /usr/share/apache2/apache2-maintscript-helper
+ fi
+
+The helper provides functions to enable and disable configuration files, restart
+the web server, switch the MPM in use and similar. Refer to the source code for
+detailed interface documentation. When available, please use the
+apache2-maintscript-helper instead of calling helper scripts directly, as these
+functions are careful to invoke and use particular helper. Always check the
+return code of the called function to find out whether something went wrong:
+
+ if ! apache2_invoke enmod modulename ; then
+ echo "Whoops! Something went wrong"
+ fi
+
+dh_apache2
+----------
+
+dh_apache2 is a debhelper which can be used to install modules, module
+configuration, site configuration and global configuration snippets. It assists
+you to set appropriate dependencies and maintainer scripts. Refer to
+dh_apache2(1) for full usage guidelines.
+
+a2enmod
+-------
+
+a2enmod and its special invokations a2enconf, a2ensite, a2dismod, a2dissite and
+a2disconf can be used to enable all types of Apache 2 configuration files. When
+invoking these helpers in maintainer scripts, you should carefully check their
+error return codes. Use these scripts with the -q (quiet) switch only in
+maintainer scripts. Ideally you should not interface with this scripts directly,
+instead it is recommended to use apache2-maint-helper. For detailed usage refer
+to their respective man pages.
+
+a2query
+------
+
+a2query is a query tool to retrieve runtime status information about the Apache
+2 web server instance. You can use this tool to get information about loaded
+modules, the MPM used on the installation site, the module magic number and
+other useful information. Use this script instead of accessing configuration
+files in /etc/apache2 directly as it tries its best to return useful information
+even on incomplete or broken configurations.
+
+For example you can use a2query to retrieve the MPM enabled at the installation
+site and make actions dependent on the result like this:
+
+ [ -x /usr/sbin/a2query ] || exit $?
+ CUR_MPM=$(a2query -M) || exit $?
+ case "$CUR_MPM" in
+ worker)
+ ;;
+ ...
+ esac
+
+Refer to the a2query(1) man page for the full documentation. Please note, the
+apache2-maint-helper can be used to inteface with this task as well.
diff --git a/debian/apache2.README.Debian b/debian/apache2.README.Debian
index c16c430..68075c4 100644
--- a/debian/apache2.README.Debian
+++ b/debian/apache2.README.Debian
@@ -13,13 +13,14 @@ Contents
SSL workaround for MSIE
Suexec
-
+
Documentation
Upgrades
Common Problems
+ For Developers
Apache2 Configuration under Debian GNU/Linux
============================================
@@ -31,7 +32,7 @@ administering the server as easy as possible.
Please be aware that this layout is quite different from the standard
Apache configuration. Due to the use of environment variables, apache2
-needs to be started/stopped with /etc/init.d/apache2 or apache2ctl.
+needs to be started/stopped with /etc/init.d/apache2 or apache2ctl.
Calling /usr/bin/apache2 directly will not work with the default
configuration. To call apache2 with specific command line arguments,
just call apache2ctl with the same arguments.
@@ -41,7 +42,27 @@ Files and Directories in /etc/apache2:
apache2.conf
- This is the main configuration file.
+ This is the main configuration file. It does not include any
+ actual configuration we expect to be adapted on your site. Thus,
+ please do not touch it when possible. This file is the building
+ block of the Apache configuration in Debian and should be up to
+ date after upgrades to make sure all configuration pieces are
+ properly included.
+
+ If you want to extend the global configuration you can customize
+ the Apache web server by including configuration files through the
+ conf-available mechanism. To change listening ports and socket
+ configuration use ports.conf (see below).
+
+ports.conf
+
+ Configuration directives for which ports and IP addresses to
+ listen to.
+
+magic
+
+ Patterns for mod_mime_magic. This is not compatible with the format
+ used by current versions of the file/libmagic packages.
envvars
@@ -53,32 +74,29 @@ envvars
Here is also the default LANG=C setting that can be changed
to a different language.
-conf.d/
+conf-available/
Files in this directory are included by this line in
apache2.conf:
# Include generic snippets of statements
- Include /etc/apache2/conf.d
+ IncludeOptional conf-enabled/*.conf
This is a good place to add additional configuration
- directives. Packages should not use configuration
- files that start with 'local-' or end with '.local'.
- The local administrator can use these filenames to make
- sure that there are no conflicts with files provided by
- packages.
-
- If the local administrator is not comfortable with packages
- activating their config files by default, it is possible
- to change the 'Include /etc/apache2/conf.d/' in apache2.conf
- into 'Include /etc/apache2/conf.d.enabled/' and create that
- directory. He can then put symlinks to the files in conf.d
- which he wants to enable into conf.d.enabled.
+ directives. All configuration snippets need a '.conf' suffix to be
+ included as actual configuration. The local administrator should
+ use file names starting with 'local-' to avoid name clashes with
+ files installed by packages.
-magic
+ Configuration snippets can be enabled and disabled by using the
+ a2enconf and a2disconf executables. This works similar to the
+ approach used for modules and sites below.
- Patterns for mod_mime_magic. This is not compatible with the format
- used by current versions of the file/libmagic packages.
+conf-enabled/
+
+ Like mods-enabled/ and sites-enabled/, a piece of configuration is
+ enabled by symlinking a file from conf-available/ into this
+ directory. The a2enconf helper is provided to assist this task.
mods-available/
@@ -97,17 +115,15 @@ mods-enabled/
cgi.load -> /etc/apache2/mods-available/cgi.load
-ports.conf
-
- Configuration directives for which ports and IP addresses to
- listen to.
+ The a2enmod helper can be used to enable a module.
sites-available/
Like mods-available/, except it contains configuration
directives for different virtual hosts that might be used with
apache2. Note that the hostname doesn't have to correspond
- exactly with the filename. 'default' is the default host.
+ exactly with the filename. '000-default' is the default host
+ which is provided by Debian.
sites-enabled/
@@ -117,16 +133,16 @@ sites-enabled/
Apache uses the first VirtualHost that matches the IP/Port
as default for named virtual hosts. Therefore the 'default'
- site is linked to '000-default' so that it will be read first.
+ site should be called '000-default' to make sure it sorts before
+ other sites.
Example:
dedasys -> /etc/apache2/sites-available/dedasys
-The Include directive ignores files with names that
+ The a2ensite helper can be used to enable a site.
-- do not begin with a letter or number
-- contain a character that is neither letter nor number nor _-.
-- contain .dpkg
+The Include directives ignore files with names that do not end with a
+.conf suffix. This behavior changed to previous releases!
Other files
-----------
@@ -141,7 +157,15 @@ a2enmod and a2dismod are available for enabling and disabling modules utilizing
the above configuration system.
a2ensite and a2dissite do essentially the same thing as the above tools, but
-for sites rather than modules.
+for sites rather than modules. Finally a2enconf and a2disconf are the
+respective tools for configuration snippets.
+
+a2query is a helper script providing runtime information about the running
+server instance. For example it can be used to query enabled modules, the
+picked MPM and other information. This tool is primarily meant to package
+maintainers who need to interact with the Apache packages to activate
+their configurations upon package installations, but can be used by users
+as well.
apxs2 -a/-A is modified to use a2enmod to activate newly installed modules.
@@ -224,19 +248,23 @@ already contains this workaround.
Suexec
======
-Debian ships two version of the suexec helper program required by mod_suexec.
-It is not installed by default, to avoid possible security issues. The package
-apache2-suexec contains the standard version that works only with document root
-/var/www, userdir suffix public_html, and Apache run user www-data. The package
-apache2-suexec-custom contains a customizable version, that can be configured
-with a config file to use different settings (like /srv/www as document root).
-For more information see the suexec(8) man page in the apache2-suexec-custom
-package.
+Debian ships two version of the suexec helper program required by
+mod_suexec. It is not installed by default, to avoid possible security
+issues. The package apache2-suexec-pristine contains the standard version
+that works only with document root /var/www, userdir suffix public_html,
+and Apache run user www-data. The package apache2-suexec-custom contains a
+customizable version, that can be configured with a config file to use
+different settings (like /srv/www as document root). For more information
+see the suexec(8) man page in the apache2-suexec-custom package.
Since apache2-suexec-custom has received less testing and might be slightly
slower, apache2-suexec is the recommended version unless you need the features
from apache2-suexec-custom.
+Starting with Apache 2.4 both alternatives can be installed at the same
+time and the default suexec mechanism can be picked by using the
+update-alternatives(8) system.
+
Documentation
=============
@@ -388,3 +416,11 @@ later use.
Apache also needs write permission to the directory containing the file, in
order to replace it atomically.
+
+For Developers
+==============
+
+The Apache 2 web server package provides several helpers to assist
+packagers to interact with the web server for both, build and installation
+time. Please refer to the PROGRAMMING file in the apache2-dev package for
+detailed information.
diff --git a/debian/apache2.docs b/debian/apache2.docs
index abf45ce..0a89e29 100644
--- a/debian/apache2.docs
+++ b/debian/apache2.docs
@@ -1,2 +1,3 @@
debian/README.backtrace
debian/README.multiple-instances
+debian/PROGRAMMING
diff --git a/debian/changelog b/debian/changelog
index 2ccd2c6..c87f318 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -126,6 +126,11 @@ apache2 (2.4.1-1) experimental; urgency=low
server.
Thus, dh_apache2 can be used for Apache web server modules and web
applications providing configuration files for Apache.
+ * Write apache2-maintscript-helper which packagers can use to interface in a
+ reliable way with the Apache 2 web server in maintainer scripts
+ * Document programming hints how to interface with the Apache 2 web server for
+ * packagers of web applications and module maintainer in
+ /usr/share/doc/apache2/PROGRAMMING
[ Stefan Fritsch ]
@@ -144,7 +149,7 @@ apache2 (2.4.1-1) experimental; urgency=low
* Migrate patches to DEP-3 format. For particular changes see the summary
above.
- -- Arno Töll <debian at toell.net> Mon, 05 Mar 2012 17:54:39 +0100
+ -- Arno Töll <debian at toell.net> Fri, 09 Mar 2012 00:24:02 +0100
apache2 (2.2.22-1) unstable; urgency=low
diff --git a/debian/config-dir/apache2.conf b/debian/config-dir/apache2.conf
index ac5d95c..b6d9762 100644
--- a/debian/config-dir/apache2.conf
+++ b/debian/config-dir/apache2.conf
@@ -1,12 +1,20 @@
# This is the main Apache server configuration file. It contains the
# configuration directives that give the server its instructions.
# See http://httpd.apache.org/docs/2.4/ for detailed information about
-# the directives.
+# the directives and /usr/share/doc/apache2/README.Debian about Debian specific
+# hints.
#
#
-# Summary how Apache configuration works in Debian:
-# The Apache web server configuration is splitted into several files which are
-# read by the web server upon startup. The hierarchical overview is as follows:
+# Summary how the Apache 2 configuration works in Debian:
+# The Apache 2 web server configuration in Debian is quite different to
+# upstream's suggested way to configure the web server. This is because Debian's
+# default Apache2 installation attempts to make adding and removing modules,
+# virtual hosts, and extra configuration directives as flexible as possible, in
+# order to make automating the changes and administering the server as easy as
+# possible.
+
+# It is splitted into several files forming the configuration hierarchy outlined
+# below, all located in the /etc/apache2/ directory:
#
# /etc/apache2/
# |-- apache2.conf
@@ -20,26 +28,28 @@
# | |-- *.conf
#
#
-# All configuration files are located in the /etc/apache2/ directory.
-#
-# * apache2.conf is the main configuration file. It will include all enabled
-# configuration files on startup
+# * apache2.conf is the main configuration file (this file). It puts all pieces
+# together by including all remaining configuration files when starting up the
+# web server.
#
-# * ports.conf is included from the main configuration file unconditionally. It
-# is supposed to configure listening ports for incoming connections.
+# * ports.conf is always included from the main configuration file. It is
+# supposed to determine listening ports for incoming connections which can be
+# customized anytime.
#
-# * File in various *-enabled directories outlined above are configuration
-# snippets which manage modules, global configuration fragments or site
-# specific configuration respectively. They are activated by symlinking
-# available configuration files from their respective *-available
-# counterparts. Please do not (un-)set links manually, instead use our
-# helpers a2enmod/a2dismod, a2ensite/a2dissite and a2enconf/a2disconf.
+# * Configuration files in the sites-enabled/, mods-enabled/ and conf-enabled/
+# directories contain particular configuration snippets which manage modules,
+# global configuration fragments or site specific configuration respectively.
#
-# * The binary is called apache2, However, instead of using it directly you
-# should use apache2ctl to control the server instead as we are using
-# expansion variables by default.
+# They are activated by symlinking available configuration files from their
+# respective *-available/ counterparts. These should be managed by using our
+# helpers a2enmod/a2dismod, a2ensite/a2dissite and a2enconf/a2disconf. See
+# their respective man pages for detailed information.
#
-# See the full documentation in /usr/share/doc/apache2/README.Debian
+# * The binary is called apache2, Due to the use of environment variables, in
+# the default configuration, apache2 needs to be started/stopped with
+# /etc/init.d/apache2 or apache2ctl. Calling /usr/bin/apache2 directly will not
+# work with the default configuration.
+
#
# Global configuration
diff --git a/debian/debhelper/apache2-maintscript-helper b/debian/debhelper/apache2-maintscript-helper
index bdf491a..002f0a3 100644
--- a/debian/debhelper/apache2-maintscript-helper
+++ b/debian/debhelper/apache2-maintscript-helper
@@ -1,5 +1,16 @@
EXPORT_APACHE2_MAINTSCRIPT_HELPER=1
+#
+# Function apache2_has_module
+# checks whether a supplied module is enabled in the current Apache server
+# configuration
+# Parameters:
+# module - the module name which should be checked. Can be a regular
+# string or a Perl compatible regular expression e.g. cgi(d|)
+# Returns:
+# 0 if the module(s) was/were found
+# 1 otherwise
+# Since: 2.4.1-1
apache2_has_module()
{
[ -x /usr/sbin/a2query ] || return 1
@@ -11,6 +22,19 @@ apache2_has_module()
return 1
}
+#
+# Function apache2_switch_mpm
+# switches the MPM enabled on the web server. This function switches the
+# MPM unconditionally but does careful checks to make sure the web server
+# is left back with a working MPM.
+# It checks whether the supplied MPM exists and enables it on purpose.
+# Parameters:
+# mpm - change the MPM to the supplied argument. It should be given
+# without "mpm_" prefix, e.g. "worker", "prefork", and so on.
+# Returns:
+# 0 if the MPM could be changed
+# 1 otherwise
+# Since: 2.4.1-1
apache2_switch_mpm()
{
[ -x /usr/sbin/a2query ] || return 1
@@ -39,6 +63,24 @@ apache2_switch_mpm()
}
+#
+# Function apache2_invoke
+# invokes an Apache 2 configuration helper to enable or disable a
+# particular piece of configuration, a site or a module. It carefully
+# checks whether the supplied configuration snippet exists and reloads the
+# web server if the site administrator desires that by calling the
+# apache2_reload function.
+# Parameters:
+# command - The command to invoke. Recognized commands are "enconf",
+# "enmod", "ensite", "disconf", "dismod", "dissite"
+# arguments - A variable number or arguments (e.g. modules) which shall be
+# enabled or disabled respectively. Do not enable module
+# dependencies that way, instead use module dependencies as
+# documented in </usr/share/doc/apache2/PROGRAMMING>.
+# Returns:
+# 0 if the changes could be activated
+# 1 otherwise
+# Since: 2.4.1-1
apache2_invoke()
{
local CMD=$1
@@ -91,7 +133,17 @@ apache2_invoke()
}
-
+#
+# Function apache2_reload
+# reloads the web server to activate a changed configuration. It does not
+# actually reload the web server if the current configuration fails to
+# parse.
+# Parameters:
+# This function does not take any arguments
+# Returns:
+# 0 if the changes could be activated
+# 1 otherwise
+# Since: 2.4.1-1
apache2_reload()
{
if apache2ctl configtest 2>/dev/null; then
--
Debian packaging for apache2 (Apache HTTPD 2.x)
More information about the Pkg-apache-commits
mailing list