DH_APACHE2(1)

📦
version 2.4.69 · 17 versions
, in debian trixie

💖 DH_APACHE2 💖

okay bestie, gather round, because we're talking about dh_apache2 — the dh_apache2 man page, user contributed Perl documentation edition, and it's literally the helper that registers configuration snippets to the Apache web server. no cap. 🎀

✨ NAME ✨

dh_apache2 — register configuration snippets to the Apache web server 🦋

🌸 SYNOPSIS 🌸

dh_apache2 [debhelper options] [--conditional=expression]
[--error-handler=function] [-n|--noscripts]
    [-e|--noenable] [-r|--restart]

💅 DESCRIPTION 💅

so. dh_apache2 is a debhelper program, and its whole job — its main character era, honestly — is correctly installing Apache2 configuration snippets and setting postinst, prerm and dependencies in Apache2 web server modules and web applications. it ate and left no crumbs 💖

it supports these configuration types, and yes we're listing all of them:

  • Apache2 modules 👑
  • Apache2 configuration snippets for web applications ✨
  • Apache2 sites 🌈

and here's the tea: dh_apache2 supports two modes. either a limited auto-configuration heuristic, or a configuration file driven approach. if a file named debian/package.apache2 exists, then the actual actions are determined by that file. periodt.

🦋 OPERATION MODES 🦋

dh_apache2 can be used in two modes: a configuration file driven approach and a heuristic approach. 🫶

the configuration driven mode is fully documented in the FILES section below (scroll down bestie, it's all there). this mode gets activated by supplying a debhelper(7) configuration file, like for example debian/package.apache2.

the alternative is a heuristic mode, in which no files are installed through dh_apache2. instead, the helper will scan the package installation directory for recognized files and guess their purpose depending on their installation path in the file system. and like… use with caution. fr fr. ⚠️

🌟 INVOCATION 🌟

dh_apache2 is not part of debhelper and might require information available in the apache2-dev package. packages making use of dh_apache2 should declare a build-dependency against the virtual dh-apache2 package. iykyk 💅

dh_apache2 supports both — being called directly from a debian/rules file, or as a dh(1) addon. in the former case, the helper should run after dh_install(1) or their respective counter parts in local implementations, at earliest. alternatively it can be used as a dh addon by invoking it with:

%:
   dh $@ --with apache2

🎀 FILES 🎀

  • debian/package.apache2
  • debian/apache2

these list files to be registered with the Apache 2 HTTP server. 🌸 the file is interpreted as a line separated list of installation stanzas, where each entry consists of whitespace separated values conforming to the file semantics below.

📝 FILE SEMANTICS 📝

each line consists of a triple:

type file [arguments]

where the values are interpreted like this:

  • type — denotes the type of file to be installed. recognized values are conf for Apache2 global configuration snippets, site for virtual host configurations, and mod for Apache2 modules. 👑
  • file — interpreted as an existing file name within the source package. no path expansion is effectuated. just like dh_install(1), dh_apache2 can not rename files. nope, not happening, that's not the vibe 🙈
  • arguments — interpreted as optional arguments, if any. currently used by conf stanzas only. ✨

🌈 GLOBAL CONFIGURATION FILES 🌈

global configuration files (determined by the conf type) must have a .conf suffix and are installed to /etc/apache2/conf-available. moreover, the configuration is activated in the maintainer script at installation time. 🫶

such global configuration snippets are supposed to be used by web applications. such stanzas accept an optional third argument which is interpreted as a dependency line of alternative web servers the package supports. see EXAMPLES below. 👀

dh_apache2 will set dependencies in ${misc:Recommends} accordingly when this type of configuration is found. alternatives from the optional argument are incorporated into this dependency line. 💖

🦋 SITE CONFIGURATION FILES 🦋

site configuration files (determined by the site type) must have a .conf suffix and are installed to /etc/apache2/sites-available. moreover, the configuration is activated in the maintainer script at installation time. ✨

such global configuration snippets are supposed to be used by web applications and third party packages which install virtual host configurations. this type of configuration sets the same dependencies as configuration files. periodt.

💀 MODULES 💀

modules are handled specially and are determined by the mod type.

modules can either have a .conf or .load suffix. in that case the file is interpreted as a module load file or a module configuration file respectively, and is installed to /etc/apache2/mods-available. 🔥

if the file is ending with a .so suffix, it is interpreted as an actual module shared object and is installed to the Apache module directory. moreover, if a .load file is installed, the configuration is activated in the maintainer script at installation time. 🌟

a typical module configuration has two lines — one for the .load file, and one for the .so file — albeit the latter could be installed by upstream's makefile, too.

dh_apache2 will set dependencies in ${misc:Depends} accordingly when this type of configuration is found. 💅

✨ OPTIONS ✨

  • --error-handler=function — call the named shell function if running the maintainer script fails. the function should be provided in the prerm and postinst scripts, before the #DEBHELPER# token. 😭
  • --conditional=function — only execute maintainer scripts if the named shell function evaluates to a true value at installation time. this is useful to web applications which want to install Apache configuration files depending on a user input, for example if they interface to the user through debconf(1). 🫶

the default is to always execute the scripts. the named function should be provided in the prerm, postrm and postinst scripts, before the #DEBHELPER# token.

  • --restart -r — in maintainer scripts, do not try to reload the web server, but restart it. otherwise the default action is used, which means global configuration and sites make the web server be reloaded on success, and modules are restarted. 🔄
  • -e, --noenable — install maintainer scripts accordingly, but do not enable the scripts or configuration by default. 🙈
  • -n, --noscripts — do not modify postinst/postrm/prerm maintainer scripts. 🚫

🎀 NOTES 🎀

note that this command is not idempotent. 💀 dh_prep(1) should be called between invocations of this command. otherwise, it may cause multiple instances of the same text to be added to maintainer scripts. and we do not want that bestie, that's giving chaos energy.

🌸 EXAMPLES 🌸

the examples below list valid entries for a debian/package.apache2 file. ✨

for example, the two lines below install a fictional mod_foo Apache module along a Debian specific .load file:

mod src/foo/mod_foo.so
mod debian/foo.load

the example below installs a fictional web application called phpmyfoo, supplied in a package which also supports Lighttpd and nginx:

conf debian/phpmyfoo.conf lighttpd (>= 1.4.30) | nginx-full

or, the same example again, this time without support for other web servers:

conf debian/phpmyfoo.conf

as a final example, install a module called mod_foo along with a site configuration for a fictional site configuration for the site example.com:

mod  src/foo/mod_foo.so
mod  debian/foo.load
mod  debian/foo.conf
site debian/example_com.conf

👑 SEE ALSO 👑

apache2ctl(8), a2query(8), debhelper(7), dh(1)

💜 AUTHOR 💜

this manual and dh_apache2 was written by Arno Toell <debian@toell.net>. iconic behavior honestly. 🎀

and that's the whole page bestie!! this one's perl v5.40.1, dated 2026-10-01 — mwah, slay, go install some Apache configs 💖✨🦋

📦 where this page comes from