DH_CONFIGPACKAGE(1)

📦
version 5.6 · 4 versions
, in ubuntu stonking

✨ DH_CONFIGPACKAGE 💖

okay bestie, welcome to dh_configpackage(1) — it's a config-package-dev thing, it lives in section 1 of the manual (you know, the "type this in your shell" section), and it is genuinely iconic. no cap.

🌸 NAME 🌸

dh_configpackage — adds maintainer script rules so you can displace, hide, or transform files. that's the whole vibe. 💅

🎀 SYNOPSIS 🎀

dh_configpackage [--displace path] [--hide path] [--undisplace path]
[--unhide file] [--transform transformation] [debhelper options] [-n]

🦋 DESCRIPTION 🦋

so dh_configpackage is a debhelper program that builds what we call "configuration packages". and babes, these are so useful — they're the whole ideal way to ship configs out to target systems while still letting the local sysadmin have a lil bit of control over their own workstations. the whole philosophy and motivation behind this packaging style is spelled out in detail on the config-package-dev website, if you want the deep lore.

under the hood, config packages use dpkg diversions plus maintainer script snippets to give you three primary operations: displacing, hiding, and transforming files. let's go one by one.

displace — this is replacing a file on the target system. the og file gets renamed out of the way and diverted in the dpkg database, then the replacement file gets installed by the package, and the config-package-dev maintainer script snippets create a symlink pointing from the original name. a super common use of this? installing a wrapper script for an executable. classic.

transform — this is a special case of displace, and honestly it's giving genius. at build time, a "transform script" gets applied to the original source, and the result becomes the replacement in the displace operation. the usual move is changing one value in a config file without having to re-type the entire config file — and therefore without risking bit-rot. 🙈

hide — yet another special case of displace, except this time there is no replacement and no symlink. instead the file is just diverted to a unique path on the target system, which preserves its contents. super common use: suppressing a snippet file in a config directory (like /etc/foo.d), which disables a specific operation or configuration. lowkey elegant.

and now, the displace extension — this is a suffix appended to the diverted versions of files, and this suffix plus the string "-orig" gets appended to the original versions of the files. the default value is the first word of the package name. for example, the extension for debathena-bin-example would be ".debathena". so if debathena-bin-example displaced /bin/true, dh_configpackage would create a diversion from /bin/true to /bin/true.debathena.orig, and create a symbolic link from /bin/true to /bin/true.debathena. then the package should install its modified version at /bin/true.debathena, using e.g. dh_install. (for the rest of this documentation, ".debathena" is gonna be our example displace extension, so watch for it.)

💖 FILES 💖

debian/package.displace

list the files to displace, one per line, and include both the full path and the displace extension. for example, to displace /usr/bin/true to /usr/bin/true.debathena, you'd list "/usr/bin/true.debathena" in the file. (and yeah, just like other Debhelper commands, you can omit the initial leading slash in pathnames in the package — but these examples keep it, because consistency slays.)

debian/package.hide

list the files to hide, one per line, including the full path and the displace extension. and like we said above: these files are not actually getting removed, they're merely diverted and renamed to a unique path below /usr/share/package.

debian/package.undisplace

list the files to undisplace, one per line, including full path and displace extension.

NOTE: you only need this when a new version of the package no longer needs to displace a file — for example, if an upstream bug got fixed. and no worries, packages automatically undo all operations upon removal or deconfiguration. 🫶

debian/package.unhide

list the files to unhide, one per line, including full path and displace extension.

NOTE: same energy as undisplace — you only need this when a new version of the package no longer needs to hide a file.

debian/package.transform

okay this one's the main character. each line in the file specifies a transformation. a transformation is made of two space-separated fields: the full path of the target file including the displace extension, and then the transformation command itself. the transformation can be either a single shell command, or an executable file in the debian directory. it takes the original source of the file on stdin and prints its transformation on stdout. transformations are typically done with perl, sed, or awk — but there's literally no limitation on what you can use as a transformation.

for example, to transform /etc/school.conf by replacing all occurrences of the word 'Harvard' with the word 'MIT', you might specify this line:

/etc/school.conf.debathena sed -e 's/Harvard/MIT/g'

or, if you're storing the command in a separate script:

/etc/school.conf.debathena debian/transform_school.conf.pl

if the transformation script fails, the package build fails. you can use that with e.g. perl's "or die" syntax to make sure the source file of the transformation hasn't changed from what you expected. 💀

transformation sources: under normal operation, the source (passed on stdin) for the transformation is the name of the target file without the displace extension. dh_configpackage will check to make sure that source file is owned by a Debian package and has not been modified locally — all of this so unwanted changes don't show up in the result of the transformation. (and if the file is already displaced or transformed by a config-package-dev package, it'll check the original version of the file and use that as the transformation source. which means a config-package-dev package can be built correctly on a running system where a previous version of the same package was already installed. obsessed.)

in some cases, you may wish to use a different source — e.g. a sample configuration file in /usr/share/doc. you can specify this source as an optional field between the diversion filename and the transformation. this field must begin with a '<' immediately followed by the full path to the source. taking the example above, we might alter it like so:

/etc/school.conf.debathena </usr/share/doc/school/conf.example sed -e 's/Harvard/MIT/g'

that full path should generally be an absolute path. however — in rare cases — it's useful to use a file in the current package's build directory as the transformation source. in that case the package's build directory is assumed to be clean, and no dpkg ownership check is performed.

NOTE: there is no "untransform" operation. because a transform operation is a special case of a displace operation, the "undisplace" operation is the correct way of removing a no-longer-needed transformation in future versions of the package. write that down bestie 📝

debian/package.displace-extension

this file is how you specify the displace extension for any files diverted by this package, in case you do not want to accept the default of the first word in the package name. it will not normally be present. (see "CAVEATS" below, iykyk.)

✨ OPTIONS ✨

  • -n, --noscripts — do not modify maintainer scripts. this is a standard debhelper option, but you are strongly discouraged from using it except for debugging, because these operations rely heavily on the maintainer scripts.
  • --displace path — run a displace straight from the command line.
  • --hide path — run a hide straight from the command line.
  • --undisplace path — run an undisplace straight from the command line.
  • --unhide path — run an unhide straight from the command line.
  • --transform transformation — run a transform straight from the command line.

all five of these options let you specify an operation on the command line, and the argument to the option is the same as a single line of the corresponding file, as described above. you may specify multiple occurrences of --displace, or you may invoke dh_configpackage repeatedly with different invocations. the most common use of this format is in a rules file when performing conditional operations, in an "override_dh_configpackage" target in the "rules" file. see the debathena-conffile-example-1.1 package in /usr/share/doc/config-package-dev/EXAMPLES for one such use. 🧚

💅 CAVEATS 💅

because the displace extension is automatically generated from the package name, renaming the package can have unintended consequences. so if you must rename a package such that the first component of the name changes, specify the old extension using the "displace-extension" file (see above). don't skip this step, fr fr.

🌈 SEE ALSO 🌈

this program is a part of config-package-dev. 💜

👑 AUTHOR 👑

config-package-dev was written by Anders Kaseorg <andersk@mit.edu> and Tim Abbott <tabbott@mit.edu>. the debhelper port is by Geoffrey Thomas <geofft@mit.edu>. documentation by Jonathan Reed <jdreed@mit.edu>.

and that's the whole page, bestie 🎀 — this was config-package-dev version 5.6, dated 2026-04-17, page DH_CONFIGPACKAGE(1). go forth and displace something. slay. ✨💖

📦 where this page comes from