UCF-HELPER-FUNCTIONS(5)

NAME
ucf-helper-functions.sh - POSIX shell helper library for ucf-based configuration management

DESCRIPTION
The file ucf-helper-functions.sh is a shell library used by Debian maintainer scripts to manage configuration files via ucf and ucfr.

It provides higher-level abstractions for:

•   Installing and updating configuration files shipped by a package

•   Preserving local administrator modifications

•   Detecting ownership of configuration files across packages

•   Handling file removal and migration across package versions

•   Reconciling package state with system state

The library is intended to be sourced from maintainer scripts such as postinst and postrm.

ENVIRONMENT

PKGNAME
    Name of the owning Debian package. Required for correct registration with ucfr.

FUNCTIONS

  rename_ucf_file oldname newname
Renames a configuration file managed by ucf and updates registration state in ucfr.

Also updates internal /var/lib/ucf/hashfile entries to reflect the rename.

This function is used during package upgrades where configuration file paths change between versions. The actual file rename of the "New File" delivered with the package must already have happened.

  handle_single_ucf_file pkgfile locfile
Processes a single configuration file shipped by the package.

It invokes ucf for merge handling.

  handle_deleted_ucf_file locfile pkgdir locdir
Handles configuration files removed from the package in newer versions.

If the corresponding file in pkgdir no longer exists:

•   Runs ucf against /dev/null to trigger merge logic

•   Removes file if it becomes empty after processing

•   Removes known dpkg/ucf backup variants

•   Purges registrations from ucf and ucfr

Local modifications are preserved unless the file becomes empty.

  handle_all_ucf_files pkgdir locdir
Main entry point for configuration file/directory processing.

It performs:

•   Creation of target directory structure

•   Processing of all package-shipped file in the pkgdir.

•   Detection and handling of removed files

•   Synchronization of ucf state with filesystem state

IMPLEMENTATION NOTES

This library assumes a POSIX-compatible shell (Debian dash-compatible) and a reasonable GNU userland as usually present on a Debian system.

EXAMPLES

You ship all your package configuration files to be managed via ucf in /usr/share/examplepkg/config. Then you modify your maintainer scripts like this:

  Basic postinst integration

#!/bin/sh
set -e

PKGNAME="examplepkg"

. /usr/share/examplepkg/ucf-helper-functions.sh

SRCDIR="/usr/share/${PKGNAME}/config"
TRGDIR="/etc"

case "$1" in
    configure)
        handle_all_ucf_files "$SRCDIR" "$TRGDIR"
        ;;
esac

exit 0

  Renaming configuration files across versions

if dpkg --compare-versions "$2" le 0.16-1; then
    rename_ucf_file \
        /etc/example/conf.d/old \
        /etc/example/conf.d/new
fi

SEE ALSO
ucf(1), ucfr(1), ucfq(1), dpkg(1), dash(1)

AUTHOR
This manual page was written by Marc Haber <mh+debian-packages@zugschlus.de> for the Debian GNU/Linux system.