Differences between revisions 30 and 31
Revision 30 as of 2020-11-29 12:24:10
Size: 18785
Editor: nodiscc
Comment: add link to dpkg-divert manpage
Revision 31 as of 2020-11-30 02:57:26
Size: 18791
Editor: PaulWise
Comment: adjust
Deletions are marked like this. Additions are marked like this.
Line 305: Line 305:
 * [[DebianMan:dpkg-divert.1|man dpkg-divert]]  * [[DebianMan:dpkg-divert|dpkg-divert manual page]]

One way to manage local configuration of multiple systems is to put the configuration files and other mechanisms into the files and install scripts of a Debian package. Some advantages of doing this:

  • configuration data and methods are encapsulated in a single object
  • global configuration can be systematically removed and reversed by the more local administrators if desired
  • configuration can be tested before deployment with dpkg -i
  • configuration can be distributed securely along with the packages being developed
  • configuration can be staged out exactly like packages when using a system like http://code.google.com/p/debmarshal

The disadvantage of building configuration packages:

  • Basic package setup as described below takes about half an hour for each new package
  • Existing packages have to be signed and uploaded to the local repository, which may take some time if not already set up or keys need to be generated, found, or authorized.
  • The first time a particular file is taken over, significant research may need to go into how the other system that delivers it handles letting something else take over. See the examples table below.

Setup basic package

  1. mkdir _packagename_-1
  2. cd _packagename_-1
  3. dh_make --native
    1. s
  4. debian/changelog
    1. unstable -> company

    2. _username_@company.com

  5. debian/control
    1. Maintainer: _x_-team@company.com

    2. Section: _same as package it configures_
    3. Depend: on the package and versions appropriate
    4. Section and Priority to match upstream package
    5. Description: fill in both single line and longer description. List files being configured.
  6. Makefile
    1. debian/rules calls this without args to "build". Do nothing on the first target (eg. all:)
    2. calls clean. Do nothing here either.
    3. calls install. cp and mkdir relative to $(DESTDIR) to put files in the package.


Roughly 20% of the packages in Debian and Ubuntu ship default configuration files. If these are simply replaced, an upstream update later that modifies the same configuration file will throw dpkg into an interactive conflict resolution system. This is best avoided to make updates non-interactive. To avoid dpkg handling, the upstream package is diverted to a non-active file, and restored on removal of the config package. Placing this diversion and replacement package in its own config package allows the package to be installed by debian-installer before first boot.

The replacement file is best provided as a regular package file (not a conffile) somewhere other than the original location, and symlinked from /etc. This avoids making the replacement file also a conffile. There are complex interaction cases where a package may be removed but its configuration files remain on the system. If the replacements are also configuration files, there are twice as many cases of package installation states to deal with, and no preinst or postrm scripts to execute any logic to handle the additional cases. conffiles are listed in /var/lib/dpkg/info/*.conffiles for each package.

The recommended method to assemble -config packages is to divert and symlink in the postinst, and remove symlinks and diversions in the prerm script. The symlinks are only created if the path is either not present or is already a symlink, and only removed if the path is a symlink. One suggested location is /etc/site/. This requires a purge of the conffiles in the package build, and will generate a linitian error.

The config-package-dev package provides CDBS rules files that help automate much of the work of creating Debian configuration packages using the divert-and-symlink technique with careful error checking and support for apply simple modifications to a Debian upstream configuration file in a way that is easy to maintain over time. It is available in Debian lenny or later. You can read the config-package-dev documentation at http://debathena.mit.edu/config-package-dev for details on how to use it.

Another option is to replace both the file and the checksum so dpkg is unaware of a change, though this would result in new upstream configuration files replacing the locally customized one.


set -e
if [ "$1" = configure ] ; then
        for f in auto.master gssapi_mech.conf
                dpkg-divert --add --package ${PKG} --rename \
                        --divert /etc/$f.distrib /etc/$f
                [ \! -e /etc/$f -o -L /etc/$f ] && ln -sf /etc/site/$f /etc/$f
exit 0


set -e
if [ "$1" = remove ] ; then
        for f in gssapi_mech.conf auto.master
                [ -L /etc/$f ] && rm /etc/$f
                dpkg-divert --remove --package ${PKG} --rename \
                        --divert /etc/$f.distrib /etc/$f
exit 0

To prevent files in /etc/site in the -config package from becoming conffiles themselves, in the -config debian/rules file, remove or purge the automatically generated DEBIAN/conffiles file after dh_installdeb runs.


binary-arch: build install
        rm debian/company-service-config/DEBIAN/conffiles

debconf-generated configuration files

Roughly 5% of Debian packages use the debconf database and custom scripts using that data to generate configuration files. These scripts are located in /var/lib/dpkg/info/*.config. While there aren't a large number of these packages, they tend to be the most critical and important packages, and each one is a custom script that must be understood before you take over control of its configuration file. If dlocate /etc/filename doesn't locate a package, there's a good chance the configuration file is a debconf-generated file.

In the ideal case, there are values you can put in the debconf system that will generate the correct file. These can be done using debconf-set-selections and dpkg-reconfigure in the -config postinst script or in the installer preseed. Many .config scripts are rudimentary and are incapable of generating the required configuration file.

Typically, you should start by diverting the existing file using the method described above for conffiles, but also take some action (read the package.config script) that prevents that script from regenerating a configuration file on the real path. Ideally the script would respect the diversion, but none of them do at present. Some typical methods that disable particular .config scripts are:

  1. Presence or absence of a comment or directive in the configuration file itself (eg. ##DEBCONF##)
  2. A debconf variable (eg. package/override)
  3. Test whether configuration file is really a symlink now

Diverting the /var/lib/dpkg/info/package.config script in advance of package installation doesn't work.


Debian/etch has 113 packages (about 1% of the source archive) using ucf for configuration file handling, up from just autofs in sarge and dapper. ucf attempts to provide conffile behavior for scripts that are autogenerated. It is not yet in wide use. A real file exists somewhere else on the system, and on first install this is copied to the /etc pathname. On upgrades, the checksum of the /etc configuration file is compared with the checksum of the original, and is upgraded if no end-user changes were made. Otherwise the /etc configuration file is left unchanged.

The ucf system should be turned off for files that are provided by a -config package, and turned back on if the -config package is removed. The -config package would need to have encoded inside it the same ucf command that took over management in the first place.


        ucf --purge /etc/auto.master


        ucf /usr/share/autofs/conffiles/auto.master /etc/auto.master

This doesn't work, as autofs re-ucf's its config files and then asks whether to overwrite. If you answer yes, ucf will follow your symlink back to the /etc/site config file and overwrite it.

Solution: divert the usr/share/autofs/conffiles/auto.master file as well, either leaving it empty or making it a symlink to /etc/site as well. Doing both seems to be sufficient to preserve the local changes.

cme and configuration upgrade

lcdproc configuration is managed by cme to setup a basic working configuration and to upgrade the configuration during package upgrade without requiring user assistance. See PackageConfigUpgrade for more details.

fully custom

There are also packages with scripts that fully automate the generation and long term maintenance of their configuration files. Each one of these is a special case, without even debconf's generalized input model.

bind mount

Some configuration files may need to be taken over at specific stages of bootup, but left unmodified until then. If there is no good mechanism otherwise to disable a package from rewriting a configuration file, or if it has to be returned to unmodified state before the next boot, a read-only bind mount in a bootup script may be the only way.




disabled by




dpkg-divert and bind-mount





































custom script

existence of file









echo searchline > /etc/resolvconf/run/interface/zzzinterface








~3-download without -d flag. Other options as necessary.












unmanaged after install


apt-setup base-installer


preseed file



custom script

/etc/profile.d/_fixprofile.sh /etc/profile.d/_fixprofile.csh

Alternatives to config packages

Any alternative configuration file handling method still has to inform the native Debian/Ubuntu configuration handling systems that the native system (dpkg) should leave the new files alone and ignore changes to them. Most documentation on the web does not mention this. The problems arise later when there are updates to the packaged systems.

  • slack - A simple packaging system published by Google to drop configuration files on systems. Unaware of native package configuration handling, no removal capability. slack roles need to divert or otherwise wedge native configuration methods as described above.
  • cfengine2 - Like slack, configuration rules must still use dpkg-divert to cleanly handle configuration files.
  • puppet - A configuration management tool that hides the details of implementation so that you can easily describe policy. Has no understanding of Debian's conffiles system.
  • FAI - An installer. Configurations are changed by reinstalling the system with the new configurations. Could avoid using its native configuration file system and use as a transport for configuration packages to install systems that don't require reinstall to reconfigure.
  • bcfg2 - A configuration management tool that can 'bundle' configuration files with their respective packages so that verification can succeed despite file changes from the default package installation. Uses debsums to verify installed package consistency.


Using patch files

Description of the Problem

Some changes to the configuration files are small and simple. So simple that can be represented by a patch. When the change isn't needed anymore the configuration file should return to the original state. It should respect the modifications made by the local administrator.


A patch management system to patch the configuration files. This is similar to the patch system used to manage source packages in Debian, like dpatch or quilt. The system should keep record of the patches installed or not installed, permit a easy way to install or remove the configuration and upgrading the configured packages without conflicts in the configuration files.


At the core of the implementation is the command dpatch. It's called by a wraparound script, so it can apply the patches to the root of the Linux system and the patches files are inside the configuration directory of the package. This wraparound script is called spatch, is placed in /usr/share/$packname and is customized to the configuration package. This script spatch is only called by the local administrator if the patch system is broken in anyway. The script gen-spatch inside the non-oficial package cal-scripts can generate spatch commands.

To configure the others packages the command update-package do one of the three things:

  • --update - install or updates the installed customizations and reload the
    • daemons,
    --clean - remove all customizations and reload the daemons, --revert - remove all customizations but not reload the daemons, to
    • permit upgrades without conflicts on the configurations packages.

It have the option --silent to allow the command to run unattended.

When update-package changes the configurations files it notifies the daemons to use the new configuration.


The command gen-spatch is:

cat > spatch <<EOF
pushd \${PATCHESDIR} > /dev/null
OPT="--workdir \${APPLYDIR}"
while [ \$# -gt 0 ]; do
        case \$1 in
                        dpatch \$*
                        exit 1
                        OPT="\${OPT} \$1"
        shift || true
case \$1 in
        dpatch \${OPT} \$*
        dpatch \${OPT} \$*
        dpatch \${OPT} \$*
        dpatch \${OPT} \$CMD --stampdir=\${PATCHESDIR}/debian/patched \$*
popd > /dev/null

As an example the update-package will have commands like:

source ${CONFIG}
function update-clean-patches () {
    deapply-patches $*
    if [ $CLEAN = no ] ; then
        ${SPATCH} apply $1
# Doing updates
update-clean-patches 10_bootlogd_v00
if [ -r /boot/grub/menu.lst ] ; then
    update-clean-patches 10_grub_menu.lst_v00 10_grub_menu.lst
# openssh-server on etch don't need patch
deapply-patches 10_sshd_config_v00 10_sshd_config
if egrep "[[:space:]]*X11Forwarding[[:space:]]+yes" /etc/ssh/sshd_config > /dev/null ; then
    echo "openssh-server on etch don't need patch"
    update-clean-patches 10_sshd_config_v00 10_sshd_config
    if [ ${RESTART} = "yes" ] ; then
        invoke-rc.d ssh reload
#Patching /etc/modules
ModulesAllPatches="20_modules_firewalls_v00 20_modules_routers_v00 \
20_modules_tagus_policy_v01 20_modules_tagus_policy_v00 \
deapply-patches $ModulesAllPatches
update-clean-patches 10_modules_prerequisites_v00
update-clean-patches 20_modules_tagus_policy_v01 20_modules_tagus_policy_v00
case $TpSrvConfNetOptionsRouter in
        update-clean-patches 20_modules_routers_v00
case $TpSrvConfNetOptionsFirewall in
        update-clean-patches 20_modules_firewalls_v00


Is responsibility of the local administrator to run:

  • update-package --revert before upgrades update-package --update after upgrades

It's possible to automate this tasks by using apt options, by dropping a file inside /etc/apt/apt.conf.d with something like the following example:

DPkg::Pre-Invoke  { "/usr/sbin/update-package --revert --silent;" };
//DPkg::Pre-Install-Pkgs { "/usr/bin/update-tp-conf-srv --apt"; };
DPkg::Post-Invoke { "/usr/sbin/update-package --silent;" };


deb http://debian.tagus.ist.utl.pt/debian etch/updates main contrib

deb http://debian.tagus.ist.utl.pt/debian etch/proposed-updates main contrib

dpsyco approach

The dpsyco package implements a system to define and apply a local policy. This policy define users, groups that automatically exists or are removed from the systems. Permits to auto-configure the users that can have access to mysql database or samba. Have a system to automatically apply this changes or using patches to changes configuration files. The packages already in Debian etch: dpsyco, dpsyco-*

On the reverside it lacks documentation on its design or capabilities. Help is needed to understand how it works.



External links

CategoryDeveloper | CategorySystemAdministration | CategoryPackaging