Adding debian version 2.4.57-2.debian/2.4.57-2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 459 insertions, 0 deletions

diff --git a/debian/PACKAGING b/debian/PACKAGING
new file mode 100644
index 0000000..65a8452
--- /dev/null
+++ b/debian/PACKAGING
@@ -0,0 +1,459 @@
+Apache 2 Packaging Guidelines
+=============================
+
+This document describes handling and behavior of reverse dependencies which
+would like to interact with the Apache 2 HTTP server
+
+Contents
+========
+
+	1. Overview
+
+	2. Packaging Modules
+		2.1 '.load' and '.conf' files
+		2.2 Maintainer scripts
+
+	3. Packaging Sites and Configurations for Web Applications
+		3.1 Web application module dependencies
+		3.2 Package dependencies
+
+	4. Maintainer Scripts
+		4.1 Enabling Configurations
+		4.2 Switching MPMs
+
+	5. Tools
+		5.1 a2query
+		5.2 apache2-maintscript-helper
+		5.3 dh_apache2
+
+	6. Version
+		6.1 Changes
+
+
+1 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 for how to
+declare dependencies against Apache 2 web server packages depending on the type
+of package. Refer to the appropriate parts for extensive information.
+
+Furthermore, there are several helper tools available to assist with common
+tasks. These are outlined in their respective sub sections as well. You should
+use these tools to get maintainer scripts and dependencies right.
+
+This document adopts the normative wording of the Debian Policy Manual §1.1[1].
+The words "must", "should", and "may", and the adjectives "required",
+"recommended", and "optional", are used to distinguish the significance of the
+various guidelines in this policy document.
+
+[1] http://www.debian.org/doc/debian-policy/ch-scope.html#s1.1
+
+2 Packaging Modules
+===================
+
+Modules are packages which are installing third party extensions to the Apache 2
+web server which can be loaded at runtime to extend the functionality of the
+core server. Please be aware that such compiled modules make use of a stable
+Application Binary Interface (ABI) and therefore 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 these policies to make
+sure it can be upgraded without breakage of local sites. To achieve this, a
+package must build-depend on apache2-dev. That package provides the 'apxs'
+compile helper which makes sure the module to be compiled is compatible with the
+Apache 2 web server and the C headers the server is providing as a public
+interface. If an updated package is not buildable with Apache 2.2 anymore, the
+apache2-dev build-dependency should be versioned ">> 2.4~", because older
+versions of apache2-threaded-dev did provide apache2-dev.
+
+A module package that uses openssl specific interfaces in mod_ssl, either by
+using the mod_ssl_openssl.h header, or by using mod_ssl-internal private
+interfaces (don't do that!), must build-depend on apache2-ssl-dev to ensure
+that the correct version of the openssl headers are used. In this case,
+dh_apache2 will also create a dependency on a apache2-api-YYYYMMDD-opensslM.M
+virtual package.
+
+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 which denotes the ABI
+compatibility version number. The virtual package is called apache2-api-YYYYMMDD
+and is guaranteed to be stable through all binary updates of 2.4.x. The
+dh_apache2 helper assists in getting the dependencies right.
+
+2.1 '.load' and '.conf' files
+-----------------------------
+
+The module must install a 'module.load' file to /etc/apache2/modules-available,
+where 'module' is the name of the installed module minus the "mod_" prefix. The
+'.load' file must contain an appropriate "LoadModule" directive only.
+Additionally maintainers may use a magic line in '.load' files to declare
+module dependencies and conflicts which need to be resolved to load a module for
+a local site. This is useful if a module depends on 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 any "magic comment lines" with the format
+"# Depends: module [module [...]]" and "# Conflicts: module [module [...]]";
+for example to load mod_foo:
+
+In 'foo.load':
+
+	# Depends: bar
+	# Conflicts: baz
+	LoadModule foo_module /usr/lib/modules/mod_foo.so
+
+
+Additionally, if required, a 'foo.conf' configuration file to configure the
+module may be installed along with the 'load' file, following the same naming
+scheme. This is useful if the module in question requires some initial
+configuration to be useful. No magic comments are recognized in '.conf' files.
+Otherwise they have the same functionality and requirements as configuration
+files (see section 3 below). You should use only directives provided by default
+by our web server configuration or which are provided by your module itelf in a
+supplied '.conf' file.
+
+In some rare cases it can't be avoided that a module depends on an another
+module being loaded already before its own loading process can succeed. The
+module load order is guaranteed to be sorted alphabetically, which could lead to
+problems if the new module to be loaded sorts later. In most cases such
+pre-load dependencies can be avoided upstream - consider filing a bug. If there
+is no way out of this problem, you may want to add a conditional Include in your
+own module file.
+
+Suppose mod_foo relies on mod_bar to be loaded first. You may want to write a
+module 'load' file like this:
+
+	# Depends: bar
+	<IfModule !mod_bar.c>
+		Include mods-enabled/bar.load
+	</IfModule>
+
+	LoadModule foo_module /usr/lib/modules/mod_foo.so
+
+Please note that the bar.load file must also contain a matching "<IfModule
+!mod_bar.c>" guard as it would be loaded twice otherwise. Use this method
+extremely sparingly and in agreement with related package maintainers only.
+Note that such a module '.load' file must still contain a "Depends:" magic line
+to make sure that the a2enmod/a2dismod dependency resolver works correctly.
+
+2.2 Maintainer scripts
+----------------------
+
+Maintainer scripts should not invoke a2enmod directly. Instead, the
+apache2-maintscript-helper should be used. Please be aware that 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 unconditionally. 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.
+
+If maintainer scripts use a2enmod/a2dismod manually, they must invoke them with
+the "-m" (maintainer mode) switch.
+
+3 Packaging Sites and Configurations for Web Applications
+=========================================================
+
+Web applications are different from modules in that they do not have a hard
+dependency on the web server. Typically they require a running web server,
+but they do not need to worry about binary compatibility of modules. We accept
+that there are other web servers besides Apache; thus we discourage package
+maintainers of web applications from depending unconditionally on Apache. That
+said, we provide several helpers 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: sites and general configuration. Sites
+are installed to /etc/apache2/sites-available and configure a particular
+virtual host. Special care must be taken when installing a site configuration
+to make sure it does not interfere with site-local configuration used by the
+administrator. Typically there are only a few use cases where a Debian
+package should include a virtual host configuration.
+
+The general 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 configuration must be used when installing a global (i.e. virtual
+host independent) configuration. Usually these configuration snippets will be
+included in the global server context via the conf-enabled directory. However,
+it is planned to allow the administrator to only enable the configuration
+snippets in a selected set of virtual hosts.
+
+Typically a "packagename.conf" should enable a global alias pointing to your web
+application along with a script-dependendent per-script configuration; for
+example:
+
+	Alias /packagename /usr/share/packagename
+
+	<Directory /usr/share/packagename>
+	  ...
+	</Directory>
+
+Please be careful about the directives you are using. Some might be provided by
+modules which are not enabled by default. By default you can unconditionally use
+directives from these modules: mod_access_compat, mod_alias, mod_auth_basic,
+mod_authn_file, mod_authz_host, mod_authz_user, mod_autoindex, mod_deflate,
+mod_dir, mod_env, mod_filter, mod_logio, mod_mime, mod_negotiation,
+mod_setenvif, mod_unixd, mod_version, mod_watchdog. Check the module
+documentation for the modules providing directives you are using.
+
+Note that not all directives are really required. If your <Directory>
+configuration can be enhanced by mod_rewrite rules, but does not necessarily
+need to use them, you could do something like:
+
+	<Directory /usr/share/packagename>
+		...
+		<IfModule mod_rewrite.c>
+			 on
+			RewriteRule ...
+		</IfModule>
+	</Directory>
+
+(Note that some common uses of mod_rewrite for web applications can be replaced
+by the relatively new FallbackResource directive.)
+
+3.1 Web application module dependencies
+---------------------------------------
+
+There are use cases where a configuration really needs a certain module to be
+enabled. This is tricky to achieve for web applications as dependencies could
+lead to complex dependency chains which could break unrelated web applications
+installed alongside your package. Thus, we do not resolve module dependencies
+for web applications automatically, but they may be expressed (see 'load' files
+in section 2.1), and a2enconf will warn the site administrator about modules
+which need to enabled. Moreover, modules can be arbitrarily enabled and
+disabled by local administrators, so a web application must make sure not to
+break the web server's start-up if a required module is not available.
+
+The syntax for config snippets to express dependencies is identical to the
+syntax in modules' '.load' files.  Within your package.conf file you still need
+to protect non-default directives with <IfModule> clauses as there is no
+guarantee that the modules are actually enabled. It is acceptable if your
+configuration file turns into a no-op as long as it does not break the server
+start-up.
+
+For both types of configuration (configurations and sites), dh_apache2 can be
+used to assist packagers.
+
+3.2 Package dependencies
+------------------------
+
+Web applications must only depend on (or recommend) the apache2 package. Web
+applications must not depend on or recommend the packages apache2-bin or
+apache2-data. 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. While a consolidated and consistent behavior among web
+applications would be desirable, from Apache's point of view, both alternatives
+are acceptable. If your web application depends on a particular web server module
+you need to depend on that, 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
+
+A with modules, web applications may enable their configuration files in
+maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally,
+special care should 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 with
+<IfModule> clauses if you require non-standard modules.
+
+4 Maintainer Scripts
+====================
+
+Though already discussed briefly in previous sections, here follow some
+clarifications regarding the invocation of wrapper scripts in maintainer scripts
+of modules and web applications.
+
+4.1 Enabling Configurations
+---------------------------
+
+Both modules and web applications should use the apache2-maintscript-helper in
+general. The helper will obey local policies to decide when to enable a piece of
+configuration, to reload the web server, and so on. Moreover, it will remember
+whether a module was activated by the site administrator or a maintainer script.
+Thus, it is particularly important you do not use "a2enmod" and so on directly
+(though a2query is acceptable).
+
+This is a summary of how the apache2-maintscript-helper should be invoked in
+maintainer scripts:
+
+Modules:
+	Unless a maintainer or debconf script verified that no configuration was
+	to be installed at all, e.g. for scripts supporting several web servers,
+	modules should unconditionally call apache2_invoke in their "postinst
+	configure" sections. It will obey site-local policies in future and will
+	make sure that disabled modules are not enabled again during upgrades of
+	a module package.
+
+	Modules need to be disabled on removal (and purge anyway), as otherwise
+	their configuration will be broken (as LoadModule would fail because of
+	the missing shared object file). Thus, modules need to call
+	"apache2_invoke dismod" on both removal and purge. It's apache2_invoke's
+	job to deal with upgrades and it will remember modules it removed during
+	removal and will reenable them during re-install.
+
+Web Applications:
+	Web Applications derive the same behavior as modules if the web
+	application can be run with a sensible out-of-box configuration; don't
+	enable it otherwise. Likewise, web application should also be disabled
+	on removal (and on purge anyway), because important files may be missing
+	(and that's the point of package removal, anyway).
+
+4.2 Switching MPMs
+------------------
+
+Only modules are allowed to switch the enabled MPM. Web applications must not
+switch the enabled MPM in their maintainer scripts. To actually switch the MPM,
+packagers can use a2query to find out whether it is necessary, and if so, can
+switch it by using the corresponding helper function provided in
+apache2-maintscript-helper. Do not try to switch the MPM yourself - the helper
+function takes special care not to leave the site in a state without an enabled
+MPM, which is a fatal error.
+
+
+The helper call may fail. Your maintainer script must cope with this
+possibility. It is not recommended to make your maintainer script fail if the
+MPM could not be changed. Instead emit a warning. You can use the apache2_msg
+function from apache2-maintscript-helper which will also log to syslog. If you
+are using debconf anyway you may want to consider using that - but continue
+operation. However, make sure you only enable the module in question if the MPM
+was changed successfully.  See below for an example snippet:
+
+
+	if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
+		. /usr/share/apache2/apache2-maintscript-helper
+
+		# mod_foo requires the prefork MPM
+		if [ $(a2query -M) != 'prefork' ] ; then
+			if apache2_switch_mpm prefork ; then
+				apache2_invoke enmod foo
+			else
+				apache2_msg err "Could not switch to prefork, not enabling mod_foo"
+			fi
+		else
+			apache2_invoke enmod foo
+		fi
+
+	fi
+
+
+5. Tools
+========
+
+This is an overview of tools supplied with the Apache2 package which can assist
+in building web application and module packages.
+
+5.1 apache2-maintscript-helper
+------------------------------
+
+The apache2-maintscript-helper is a collection of functions which can be
+sourced in maintainer scripts to do required tasks in a simple and
+standardized way. It is NOT a script; it is a library (insofar as shell
+functions can be libraries). This is to avoid users calling these functions.
+They are not meant to be used by users. 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
+
+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 the appropriate helper. Later versions
+may be configurable to allow the administrator to influence which actions are
+performed.
+
+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
+
+5.2 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.
+
+5.2 a2enmod
+-----------
+
+a2enmod and its special invocations 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. These scripts must always be used with the -q (quiet) and -m
+(maintainer mode) switches in maintainer scripts. Preferably, you should not
+interface with this scripts directly; instead it is recommended to use
+apache2-maintscript-helper. For detailed usage refer to their respective man
+pages.
+
+5.3 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 on the local 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 that
+the apache2-maintscript-helper can be used to interface with this task as well.
+
+6 Version
+=========
+
+Document version: 1.0
+
+Starting with Apache2 2.4.2-2 this document is versioned. Any change which affects
+packaging is denoted by an increased major nummer; clarifications, spelling fixes
+and minor edits are denoted by minor numbers. In future, a changelog will appear
+here as well.
+
+6.1 Changes
+-----------
+
+1.0:
+	* first version of this document which is versioned.