UCF(1) Debian GNU/Linux manual UCF(1)
NAME
ucf - Update Configuration File: preserve user changes in configuration
files
SYNOPSIS
ucf [options] <New File> <Destination>
ucf [options] --purge <Destination>
DESCRIPTION
This utility provides a means of asking the user whether or not to ac-
cept new versions of configuration files provided by the package main-
tainer, with various heuristics designed to minimize interaction time.
It uses debconf to interact with the user, as per Debian policy. In the
SYNOPSIS above, 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 modi-
fied by the end user. Since the files edited would be real files, and
not symbolic links, ucf follows and resolves symbolic links before act-
ing. As far as possible, ucf attempts to preserve the ownership and
permission of the New file as it is copied to the new location.
This script attempts to provide conffile like handling for files in-
stalled 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, pre-
serving 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. In-
deed, 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 al-
lowing smooth reinstallations.
During the course of operations, when working with configuration files,
ucf optionally creates copies of versions of the configuration file in
question. For example, a file with the suffix ucf-old holds the old
version of a configuration file replaced by ucf. Also, copies of the
configuration file with the suffixes ucf-new and ucf-dist may be cre-
ated; and the maintainer scripts should consider purging copies of the
configuration file with these extensions during purge.
OPTIONS
-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).
Please note there must be no spaces before the optional digit n.
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 hash-
file. 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.
-P foo, --package foo
Don't follow dpkg-divert diversions by package foo when updating
configuration files.
-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 de-
fault, 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_MD-
SUM_FILE, and in the configuration file variable conf_old_md-
sum_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 main-
tainer 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 modifi-
cations to the configuration file. This is accomplished by tak-
ing 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 configura-
tion file to avoid name space clashes).
--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 de-
bconf is not running – it shall invoke debconf as needed).
--debconf-template foo
Instruct ucf to use the named multiselect debconf template in-
stead of the normal ucf-provided debconf template. The caller is
responsible for ensuring that the named template exists and has a
list of choices matching those for the default ucf template, and
should set Choices-C: ${CHOICES} to ensure the returned values
match those from the default template. Note that the choices
must be different according to whether the --three-way option is
also set.
--state-dir /path/to/dir
Set the state directory to /path/to/dir instead of the default
/var/lib/ucf. Used mostly for testing.
-Z Set SELinux security context of destination file to default type.
USAGE
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).
It is recommended that you also register any file being managed by ucf
with the ucf registry; this associates the configuration file with the
package it belongs to. This is done with a simple call to ucfr. Users
may then query the association between a configuration file and the
package using the tool ucfq. Please see the appropriate manual pages
for details.
Packages which employ debhelper can simplify creating of the necessary
maintscript fragments by using the dh_ucf helper.
If a file maintained by maintainer scripts is being transitioned from an
unprotected status to the protection afforded by the script, the main-
tainer 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, ex-
cept for the entry named default), or create a directory, called <New
file>.md5sum.d, which should contain any number of files, each contain-
ing 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 com-
plete, or the user has changed the configuration file.
The default historical md5sum
The exception to the rule about names mentioned earlier is that if no
md5sums match, and if the file <New file>.md5sum.d/default exists, or if
there is a line corresponding to a default file in <New file>.md5sum, it
shall be used as the default md5sum of the previous version of the pack-
age assumed to have been installed on this machine. As you can see, un-
less there are limited number of previously released packages (like just
one), the maintainer is also making an informed guess, but the option is
provided to the maintainer.
If the file <New file>.md5sum, or the directory <New file>.md5sum.d does
not exist, or none of the md5sums match, we test the installed <Destina-
tion> file to see whether it is the same as the <New file>. If not, we
ask the user whether they want us to replace the file.
An additional facility is also offered: optionally, ucf can store one
old version of the maintainers copy of the configuration file, and, on
upgrade, calculate the changes made in the maintainers version of the
configuration file, and apply that patch to the local version of the
file (on user request, of course). There is also a preview facility
where the user can inspect the results of such a merge, before asking
the action to be taken.
ENVIRONMENT VARIABLES
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). Additionally, when
ucf creates an inferior shell, it populates the variables UCF_CONF-
FILE_NEW and UCF_CONFFILE_OLD which are useful for inspecting the
changes.
The confmiss, confnew, confold, confdef and confask flags of the
DPKG_FORCE variable are also supported. See dpkg(1) for further infor-
mation.
FILES
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
EXAMPLES
If the package foo wants to use ucf to handle user interaction for con-
figuration 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 ex-
amples in /usr/share/doc/ucf/examples):
ucf --purge /etc/foo.conf Please note that purge can also be used to
make ucf forget the previous state of the files, and when the package is
next installed or updated, ucf will ask the user to replace the current
configuration file. Do this if you want to change your decision to not
update to a maintainer provided version of the configuration file.
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-com-
mon/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.
SEE ALSO
ucf.conf(5), ucfr(1), ucfq(1), dpkg(1), dh_ucf(1), diff3(1).
The Debian Emacs policy, shipped with the package emacsen-common.
AUTHOR
This manual page was written Manoj Srivastava <srivasta@debian.org>, for
the Debian GNU/Linux system.
Debian May 30 2008 UCF(1)
Generated by dwww version 1.16 on Tue Dec 16 05:37:12 CET 2025.