release 2.4.9-1
[pkg-apache/apache2.git] / debian / PACKAGING
1 Apache 2 Packaging Guidelines
2 =============================
3
4 This document describes handling and behavior of reverse dependencies which
5 would like to interact with the Apache 2 HTTP server
6
7 Contents
8 ========
9
10         1. Overview
11
12         2. Packaging Modules
13                 2.1 '.load' and '.conf' files
14                 2.2 Maintainer scripts
15
16         3. Packaging Sites and Configurations for Web Applications
17                 3.1 Web application module dependencies
18                 3.2 Package dependencies
19
20         4. Maintainer Scripts
21                 4.1 Enabling Configurations
22                 4.2 Switching MPMs
23
24         5. Tools
25                 5.1 a2query
26                 5.2 apache2-maintscript-helper
27                 5.3 dh_apache2
28
29         6. Version
30                 6.1 Changes
31
32
33 1 Overview
34 ==========
35
36 The Apache 2 web server package in Debian supports two types of reverse
37 dependencies: modules and web applications. They need to be treated differently
38 as their requirements are different. We have special requirements for how to
39 declare dependencies against Apache 2 web server packages depending on the type
40 of package. Refer to the appropriate parts for extensive information.
41
42 Furthermore, there are several helper tools available to assist with common
43 tasks. These are outlined in their respective sub sections as well. You should
44 use these tools to get maintainer scripts and dependencies right.
45
46 This document adopts the normative wording of the Debian Policy Manual ยง1.1[1].
47 The words "must", "should", and "may", and the adjectives "required",
48 "recommended", and "optional", are used to distinguish the significance of the
49 various guidelines in this policy document.
50
51 [1] http://www.debian.org/doc/debian-policy/ch-scope.html#s1.1
52
53 2 Packaging Modules
54 ===================
55
56 Modules are packages which are installing third party extensions to the Apache 2
57 web server which can be loaded at runtime to extend the functionality of the
58 core server. Please be aware that such compiled modules make use of a stable
59 Application Binary Interface (ABI) and therefore need a recompile if the web
60 server changes. Hence be careful how you declare dependencies against the web
61 server. You need to make sure it does not break upon upgrades.
62
63 A module package providing an Apache module must obey these policies to make
64 sure it can be upgraded without breakage of local sites. To achieve this, a
65 package must build-depend on apache2-dev. That package provides the 'apxs'
66 compile helper which makes sure the module to be compiled is compatible with the
67 Apache 2 web server and the C headers the server is providing as a public
68 interface. If an updated package is not buildable with Apache 2.2 anymore, the
69 apache2-dev build-dependency should be versioned ">> 2.4~", because older
70 versions of apache2-threaded-dev did provide apache2-dev.
71
72 The resulting binary package should be called libapache2-mod-<modulename> and
73 MUST NOT depend on apache2 or apache2-bin. Instead a module package must depend
74 on our virtual package providing the module magic number which denotes the ABI
75 compatibility version number. The virtual package is called apache2-api-YYYYMMDD
76 and is guaranteed to be stable through all binary updates of 2.4.x. The
77 dh_apache2 helper assists in getting the dependencies right.
78
79 2.1 '.load' and '.conf' files
80 -----------------------------
81
82 The module must install a 'module.load' file to /etc/apache2/modules-available,
83 where 'module' is the name of the installed module minus the "mod_" prefix. The
84 '.load' file must contain an appropriate "LoadModule" directive only.
85 Additionally maintainers may use a magic line in '.load' files to declare
86 module dependencies and conflicts which need to be resolved to load a module for
87 a local site. This is useful if a module depends on other modules to be
88 loaded, or to conflict with other modules if they can't be loaded at the same
89 time. a2enmod and a2dismod will parse any "magic comment lines" with the format
90 "# Depends: module [module [...]]" and "# Conflicts: module [module [...]]";
91 for example to load mod_foo:
92
93 In 'foo.load':
94
95         # Depends: bar
96         # Conflicts: baz
97         LoadModule foo_module /usr/lib/modules/mod_foo.so
98
99
100 Additionally, if required, a 'foo.conf' configuration file to configure the
101 module may be installed along with the 'load' file, following the same naming
102 scheme. This is useful if the module in question requires some initial
103 configuration to be useful. No magic comments are recognized in '.conf' files.
104 Otherwise they have the same functionality and requirements as configuration
105 files (see section 3 below). You should use only directives provided by default
106 by our web server configuration or which are provided by your module itelf in a
107 supplied '.conf' file.
108
109 In some rare cases it can't be avoided that a module depends on an another
110 module being loaded already before its own loading process can succeed. The
111 module load order is guaranteed to be sorted alphabetically, which could lead to
112 problems if the new module to be loaded sorts later. In most cases such
113 pre-load dependencies can be avoided upstream - consider filing a bug. If there
114 is no way out of this problem, you may want to add a conditional Include in your
115 own module file.
116
117 Suppose mod_foo relies on mod_bar to be loaded first. You may want to write a
118 module 'load' file like this:
119
120         # Depends: bar
121         <IfModule !mod_bar.c>
122                 Include mods-enabled/bar.load
123         </IfModule>
124
125         LoadModule foo_module /usr/lib/modules/mod_foo.so
126
127 Please note that the bar.load file must also contain a matching "<IfModule
128 !mod_bar.c>" guard as it would be loaded twice otherwise. Use this method
129 extremely sparingly and in agreement with related package maintainers only.
130 Note that such a module '.load' file must still contain a "Depends:" magic line
131 to make sure that the a2enmod/a2dismod dependency resolver works correctly.
132
133 2.2 Maintainer scripts
134 ----------------------
135
136 Maintainer scripts should not invoke a2enmod directly. Instead, the
137 apache2-maintscript-helper should be used. Please be aware that the helper is
138 not guaranteed to be installed on the target system. There are certain setups
139 which do not require Debian specific configurations, so modules must not do
140 anything in maintainer scripts which makes use of Debian-specific enhancements
141 like apache2-maintscript-helper, a2enmod, or a2query unconditionally. It is
142 recommended to invoke it like this:
143
144         if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
145                 . /usr/share/apache2/apache2-maintscript-helper
146                 apache2_invoke enmod foo
147         fi
148
149 The dh_apache2 helper can be used to install module configuration and load
150 files. Additionally it generates appropriate maintainer scripts. The
151 apache2-maintscript-helper provides a few functions for common tasks. See their
152 respective reference documentations below.
153
154 If maintainer scripts use a2enmod/a2dismod manually, they must invoke them with
155 the "-m" (maintainer mode) switch.
156
157 3 Packaging Sites and Configurations for Web Applications
158 =========================================================
159
160 Web applications are different from modules in that they do not have a hard
161 dependency on the web server. Typically they require a running web server,
162 but they do not need to worry about binary compatibility of modules. We accept
163 that there are other web servers besides Apache; thus we discourage package
164 maintainers of web applications from depending unconditionally on Apache. That
165 said, we provide several helpers to assist web application packagers to invoke
166 configuration snippets to enable a web application in the Apache 2 web server.
167
168 We differentiate between two sub-types: sites and general configuration. Sites
169 are installed to /etc/apache2/sites-available and configure a particular
170 virtual host. Special care must be taken when installing a site configuration
171 to make sure it does not interfere with site-local configuration used by the
172 administrator. Typically there are only a few use cases where a Debian
173 package should include a virtual host configuration.
174
175 The general configuration snippets are installed to /etc/apache2/conf-available
176 instead. Package maintainers are advised to avoid "local-" prefixes to
177 installed conffiles, and ideally use "packagename.conf" to avoid name clashes.
178 This type of configuration must be used when installing a global (i.e. virtual
179 host independent) configuration. Usually these configuration snippets will be
180 included in the global server context via the conf-enabled directory. However,
181 it is planned to allow the administrator to only enable the configuration
182 snippets in a selected set of virtual hosts.
183
184 Typically a "packagename.conf" should enable a global alias pointing to your web
185 application along with a script-dependendent per-script configuration; for
186 example:
187
188         Alias /packagename /usr/share/packagename
189
190         <Directory /usr/share/packagename>
191           ...
192         </Directory>
193
194 Please be careful about the directives you are using. Some might be provided by
195 modules which are not enabled by default. By default you can unconditionally use
196 directives from these modules: mod_access_compat, mod_alias, mod_auth_basic,
197 mod_authn_file, mod_authz_host, mod_authz_user, mod_autoindex, mod_deflate,
198 mod_dir, mod_env, mod_filter, mod_logio, mod_mime, mod_negotiation,
199 mod_setenvif, mod_unixd, mod_version, mod_watchdog. Check the module
200 documentation for the modules providing directives you are using.
201
202 Note that not all directives are really required. If your <Directory>
203 configuration can be enhanced by mod_rewrite rules, but does not necessarily
204 need to use them, you could do something like:
205
206         <Directory /usr/share/packagename>
207           ...
208           <IfModule mod_rewrite.c>
209            RewriteEngine on
210            RewriteRule ...
211           </IfModule>
212         </Directory>
213
214 (Note that some common uses of mod_rewrite for web applications can be replaced
215 by the relatively new FallbackResource directive.)
216
217 3.1 Web application module dependencies
218 ---------------------------------------
219
220 There are use cases where a configuration really needs a certain module to be
221 enabled. This is tricky to achieve for web applications as dependencies could
222 lead to complex dependency chains which could break unrelated web applications
223 installed alongside your package. Thus, we do not resolve module dependencies
224 for web applications automatically, but they may be expressed (see 'load' files
225 in section 2.1), and a2enconf will warn the site administrator about modules
226 which need to enabled. Moreover, modules can be arbitrarily enabled and
227 disabled by local administrators, so a web application must make sure not to
228 break the web server's start-up if a required module is not available.
229
230 The syntax for config snippets to express dependencies is identical to the
231 syntax in modules' '.load' files.  Within your package.conf file you still need
232 to protect non-default directives with <IfModule> clauses as there is no
233 guarantee that the modules are actually enabled. It is acceptable if your
234 configuration file turns into a no-op as long as it does not break the server
235 start-up.
236
237 For both types of configuration (configurations and sites), dh_apache2 can be
238 used to assist packagers.
239
240 3.2 Package dependencies
241 ------------------------
242
243 Web applications must only depend on (or recommend) the apache2 package. Web
244 applications must not depend on or recommend the packages apache2-bin or
245 apache2-data. Generally, web server dependencies should be declared in the form:
246
247         Depends: apache2 | <alternative web servers you support> | httpd-cgi
248
249 Using dh_apache2 assists you to do so, although dh_apache2 declares a weaker
250 Recommends relation only. While a consolidated and consistent behavior among web
251 applications would be desirable, from Apache's point of view, both alternatives
252 are acceptable. If your web application depends on a particular web server module
253 you need to depend on that, too. For example, PHP applications might need to
254 formulate dependency lines in the form:
255
256         Depends: libapache2-mod-php5 | php5-cgi | php5-fpm
257         Recommends: apache2 | <alternative web servers you support> | httpd-cgi
258
259 A with modules, web applications may enable their configuration files in
260 maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally,
261 special care should be taken not to use Apache2 Debian helper scripts like
262 a2query and a2enmod unconditionally. You can use the apache2-maintscript-helper
263 tools provided by the apache2 package for common tasks this way:
264
265         if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
266                 . /usr/share/apache2/apache2-maintscript-helper
267                 apache2_invoke enconf foo
268         fi
269
270 Refer to the reference documentation below to learn how to use
271 apache2-maintscript-helper. Do not enable or disable modules in web
272 application maintainer scripts; instead protect your configuration with
273 <IfModule> clauses if you require non-standard modules.
274
275 4 Maintainer Scripts
276 ====================
277
278 Though already discussed briefly in previous sections, here follow some
279 clarifications regarding the invocation of wrapper scripts in maintainer scripts
280 of modules and web applications.
281
282 4.1 Enabling Configurations
283 ---------------------------
284
285 Both modules and web applications should use the apache2-maintscript-helper in
286 general. The helper will obey local policies to decide when to enable a piece of
287 configuration, to reload the web server, and so on. Moreover, it will remember
288 whether a module was activated by the site administrator or a maintainer script.
289 Thus, it is particularly important you do not use "a2enmod" and so on directly
290 (though a2query is acceptable).
291
292 This is a summary of how the apache2-maintscript-helper should be invoked in
293 maintainer scripts:
294
295 Modules:
296         Unless a maintainer or debconf script verified that no configuration was
297         to be installed at all, e.g. for scripts supporting several web servers,
298         modules should unconditionally call apache2_invoke in their "postinst
299         configure" sections. It will obey site-local policies in future and will
300         make sure that disabled modules are not enabled again during upgrades of
301         a module package.
302
303         Modules need to be disabled on removal (and purge anyway), as otherwise
304         their configuration will be broken (as LoadModule would fail because of
305         the missing shared object file). Thus, modules need to call
306         "apache2_invoke dismod" on both removal and purge. It's apache2_invoke's
307         job to deal with upgrades and it will remember modules it removed during
308         removal and will reenable them during re-install.
309
310 Web Applications:
311         Web Applications derive the same behavior as modules if the web
312         application can be run with a sensible out-of-box configuration; don't
313         enable it otherwise. Likewise, web application should also be disabled
314         on removal (and on purge anyway), because important files may be missing
315         (and that's the point of package removal, anyway).
316
317 4.2 Switching MPMs
318 ------------------
319
320 Only modules are allowed to switch the enabled MPM. Web applications must not
321 switch the enabled MPM in their maintainer scripts. To actually switch the MPM,
322 packagers can use a2query to find out whether it is necessary, and if so, can
323 switch it by using the corresponding helper function provided in
324 apache2-maintscript-helper. Do not try to switch the MPM yourself - the helper
325 function takes special care not to leave the site in a state without an enabled
326 MPM, which is a fatal error.
327
328
329 The helper call may fail. Your maintainer script must cope with this
330 possibility. It is not recommended to make your maintainer script fail if the
331 MPM could not be changed. Instead emit a warning. You can use the apache2_msg
332 function from apache2-maintscript-helper which will also log to syslog. If you
333 are using debconf anyway you may want to consider using that - but continue
334 operation. However, make sure you only enable the module in question if the MPM
335 was changed successfully.  See below for an example snippet:
336
337
338         if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
339                 . /usr/share/apache2/apache2-maintscript-helper
340
341                 # mod_foo requires the prefork MPM
342                 if [ $(a2query -M) != 'prefork' ] ; then
343                         if apache2_switch_mpm prefork ; then
344                                 apache2_invoke enmod foo
345                         else
346                                 apache2_msg err "Could not switch to prefork, not enabling mod_foo"
347                         fi
348                 else
349                         apache2_invoke enmod foo
350                 fi
351
352         fi
353
354
355 5. Tools
356 ========
357
358 This is an overview of tools supplied with the Apache2 package which can assist
359 in building web application and module packages.
360
361 5.1 apache2-maintscript-helper
362 ------------------------------
363
364 The apache2-maintscript-helper is a collection of functions which can be
365 sourced in maintainer scripts to do required tasks in a simple and
366 standardized way. It is NOT a script; it is a library (insofar as shell
367 functions can be libraries). This is to avoid users calling these functions.
368 They are not meant to be used by users. The helper is installed within the
369 apache2 binary package. Thus you MUST NOT use any function of it
370 unconditionally, as for both modules and web applications there are use cases
371 when this package is not added as a dependency. Thus, use it in a protected
372 conditional like this only:
373
374         if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
375                 . /usr/share/apache2/apache2-maintscript-helper
376                 <call apache2-maintscript-helper specific functions>
377         fi
378
379 The helper provides functions to enable and disable configuration files,
380 restart the web server, switch the MPM in use and similar. Refer to the source
381 code for detailed interface documentation. When available, please use the
382 apache2-maintscript-helper instead of calling helper scripts directly, as these
383 functions are careful to invoke and use the appropriate helper. Later versions
384 may be configurable to allow the administrator to influence which actions are
385 performed.
386
387 Always check the return code of the called function to find out whether
388 something went wrong:
389
390         if ! apache2_invoke enmod modulename ; then
391                 echo "Whoops! Something went wrong"
392         fi
393
394 5.2 dh_apache2
395 --------------
396
397 dh_apache2 is a debhelper which can be used to install modules, module
398 configuration, site configuration, and global configuration snippets. It assists
399 you to set appropriate dependencies and maintainer scripts. Refer to
400 dh_apache2(1) for full usage guidelines.
401
402 5.2 a2enmod
403 -----------
404
405 a2enmod and its special invocations a2enconf, a2ensite, a2dismod, a2dissite and
406 a2disconf can be used to enable all types of Apache 2 configuration files. When
407 invoking these helpers in maintainer scripts, you should carefully check their
408 error return codes. These scripts must always be used with the -q (quiet) and -m
409 (maintainer mode) switches in maintainer scripts. Preferably, you should not
410 interface with this scripts directly; instead it is recommended to use
411 apache2-maintscript-helper. For detailed usage refer to their respective man
412 pages.
413
414 5.3 a2query
415 ----------
416
417 a2query is a query tool to retrieve runtime status information about the Apache
418 2 web server instance. You can use this tool to get information about loaded
419 modules, the MPM used on the installation site, the module magic number and
420 other useful information. Use this script instead of accessing configuration
421 files in /etc/apache2 directly as it tries its best to return useful information
422 even on incomplete or broken configurations.
423
424 For example, you can use a2query to retrieve the MPM enabled on the local site
425 and make actions dependent on the result like this:
426
427         [ -x /usr/sbin/a2query ] || exit $?
428         CUR_MPM=$(a2query -M) || exit $?
429         case "$CUR_MPM" in
430                 worker)
431                 ;;
432         ...
433         esac
434
435 Refer to the a2query(1) man page for the full documentation. Please note that
436 the apache2-maintscript-helper can be used to interface with this task as well.
437
438 6 Version
439 =========
440
441 Document version: 1.0
442
443 Starting with Apache2 2.4.2-2 this document is versioned. Any change which affects
444 packaging is denoted by an increased major nummer; clarifications, spelling fixes
445 and minor edits are denoted by minor numbers. In future, a changelog will appear
446 here as well.
447
448 6.1 Changes
449 -----------
450
451 1.0:
452         * first version of this document which is versioned.