ucf - Update Configuration File: preserve user changes in configuration files

ucf [options] <New File> <Destination>

ucf [options] --purge <Destination>

Where New file is the configuration file as provided by the package (either shipped with the package, or generated by the maintainer scripts on the fly), and Destination is the location (usually under /etc) where the real configuration file lives, and is potentially modified by the end user.

This script attempts to provide conffile like handling for files installed under /etc not shipped in a Debian package, but handled by the postinst instead. Debian policy states that files under /etc which are configuration files must preserve user changes, and this applies to files handled by maintainer scripts as well. Using ucf, one may ship a bunch of default configuration files somewhere in /usr ( /usr/share/<pkg> is a good location), and maintain files in /etc, preserving user changes and in general offering the same facilities while upgrading that dpkg normally provides for “conffiles”

Additionally, this script provides facilities for transitioning a file that had not been provided conffile like protection to come under this schema, and attempts to minimize questions asked at install time. Indeed, the transitioning facility is better than the one offered by dpkg while transitioning a file from a non-conffile to conffile status. The second form in the SYNOPSIS above is for purging information about the configuration file when the package is purged; and is critical for allowing smooth reinstallations.

-h, --help

Print a short usage message

-n, --no-action

Dry run. Print the actions that would be taken if the script is invoked, but take no action.

-d [n], --debug [n]

Set the debug level to the (optional) level n (n defaults to 1). This turns on copious debugging information.

-p, --purge

Removes all vestiges of the file from the state hashfile. This is required to allow a package to be reinstalled after it is purged; since otherwise, the real configuration file is removed, but it remains in the hash file; and on reinstall no action is taken, since the md5sum of the new file matches that in the hashfile. In short, remember to use this option in the postrm for every configuration file managed by ucf when the package is being purged (assuming ucf itself exists). Note: ucf does not actually touch the file on disk in this operation, so any file removals are still the responsibility of the calling package.

-v, --verbose

Make the script be very verbose about setting internal variables.

-s foo, --src-dir foo

Set the source directory (historical md5sums are expected to live in files and sub directories of this directory) to foo. By default, the directory the new_file lives in is assumed to be the source directory. Setting this option overrides settings in the environment variable UCF_SOURCE_DIR, and in the configuration file variable conf_source_dir.

--sum-file foo

Force the historical md5sums to be read from this file, rather than defaulting to living in the source directory. Setting this option overrides settings in the environment variable UCF_OLD_MDSUM_FILE, and in the configuration file variable conf_old_mdsum_file.

--three-way

This turns on the option, during installation, for the user to be offered a chance to see a merge of the changes between old maintainer version and the new maintainer version into the local copy of the configuration file. If the user likes what they see, they can ask to have these changes merged in. This allows one to get new upstream changes merged in even while retaining local modifications to the configuration file. This is accomplished by taking the configuration file and stashing it in a cache area during registration, and using diff3 during the install (the stashed file name is a munged version of the full path of the configuration file to avoid name space clashes). Note This option appeared in Version 0.8 of ucf, which was the first version released into unstable and ultimately Sarge. The version of ucf in woody does not contain this option.

--debconf-ok

Indicate that it is ok for ucf to use an already running debconf instance for prompting (it has always been ok to use ucf when debconf is not running -- it shall invoke debconf as needed). Since historically maintainer scripts that used debconf and also ucf had to disable/cripple debconf before running ucf (since ucf did not prompt with debconf, and needed stdio available), ucf must be cautious when called from a maintainer script that uses debconf. This option lets it know that the maintainer script has not told debconf to stop, or redirected its stdio from debconf, or anything of the sort -- and thus it is safe to use debconf even when the script discovers that debconf is running. Packages that call ucf with this option should take care to depend on version 0.28 or higher of ucf (the first to support use this option).

The most common case usage is pretty simple: a single line invocation in the postinst on configure, and another single line in the postrm to tell ucf to forget about the configuration file on purge (using the --purge option) is all that is needed (assuming ucf is still on the system).

If a file maintained by maintainer scripts is being transitioned from an unprotected status to the protection afforded by the script, the maintainer can help ease the transition by reducing the questions that may be asked at installation time. Specifically, questions should not be asked if the file in question is an unmodified version that was one shipped in a previous version of this package; and the maintainer can help by telling the script about the historical md5sums that published versions of this file contained.

The way to do this is to either create a file called <New file>.md5sum, with one md5sum on each line, (the file names you use are ignored, except for the entry named default), or create a directory, called <New file>.md5sum.d, which should contain any number of files, each containing a single line, namely, the md5sum of a previous version of <New file>. The names of these files are not important, with one exception: The file called default is treated specially. For example, the author personally uses either package version numbers or release code names, like 7.6.3, or potato. If none of the historical md5sums match, we are almost certain that either the historical record of md5sums is not complete, or the user has changed the configuration file.

The default historical md5sum

The variable UCF_FORCE_CONFFNEW, if set, forces the new file to always overwrite the installed destination file, while the variable UCF_FORCE_CONFFOLD, if set silently retains the installed file. UCF_FORCE_CONFFMISS is only applicable when the installed destination file does not exist (perhaps due to user removal),and forces ucf to recreate the missing file (the default behaviour is to honor the users wishes and not recreate the locally deleted file).

This script creates the file new_file.md5sum, and it may copy the file (presumably shipped with the package) <New file> to its destination, <Destination>.

/var/lib/ucf/hashfile, and /var/lib/ucf/hashfile.X, where X is a small integer, where previous versions of the hashfile are stored.

/etc/ucf.conf

If the package foo wants to use ucf to handle user interaction for configuration file foo.conf, a version of which is provided in the package as /usr/share/foo/configuration, a simple invocation of ucf in the post inst file is all that is needed:

ucf /usr/share/foo/configuration /etc/foo.conf

On purge, one should tell ucf to forget about the file (see detailed examples in /usr/share/doc/examples):

ucf --purge /etc/foo.conf

The motivation for this script was to provide conffile like handling for start files for emacs lisp packages (for example, /etc/emacs21/site-start.d/50psgml-init.el ) These start files are not shipped with the package, instead, they are installed during the post installation configuration phase by the script /usr/lib/emacsen-common/emacs-package-install $package_name.

This script is meant to be invoked by the packages install script at /usr/lib/emacsen-common/packages/install/$package_name for each flavour of installed emacsen by calling it with the proper values of new file ( /usr/share/emacs/site-lisp/<pkg>/<pkg-init.el ), and dest file ( /etc/emacs21/site-start.d/50<pkg-init.el ), and it should do the rest.

ucf.conf(5), diff3(1). The Debian Emacs policy, shipped with the package emacsen-common.

Well, shortcomings, really. If the debconf database has been removed, or corrupted, debconf does not automatically install ucf templates, since usually the calling pattern is such that ucf is called from the maintainer script of another package. If the other package has already invoked debconf, then ucf uses the existing front end, which has already loaded the debconf database, installing the templates of that calling package. The ucf templates are not loaded automatically, since the front-end script has no idea that they should be, it just heuristically loads the templates of the package whose maintainer scripts are being run. In this scenario, ucf cannot load its templates, since the front-end script shall override the database when it exits, and there is no way to tell the front-end script to now load ucf templates on the fly. In this case, since the DB was corrupt, debconf can not find ucf templates. In case no debconf front-end is running, though, ucf tries hard to load its own templates, as long as the package debconf-utils is installed. The only reliable way to reload ucf templates is to call dpkg-reconfigure ucf

This manual page was written Manoj Srivastava <srivasta@debian.org>, for the Debian GNU/Linux system.