Provided by: ucf_3.0027+nmu1_all 
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 accept new versions of
configuration files provided by the package maintainer, 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 modified by the end user. 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 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.
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 created;
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). 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).
--debconf-template foo
Instruct ucf to use the named multiselect debconf template instead 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.
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.
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 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 package assumed to have been installed on this machine. As you can see,
unless 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 <Destination> 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).
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 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/ucf/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.
SEE ALSO
ucf.conf(5), ucfr(1), ucfq(1), and 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.