ucf
Update Configuration File: preserve user changes in configura‐ tion files
SYNOPSIS
ucf [options]
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 main‐
tainer 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. Since the files edited would be real files,
and not symbolic links, ucf follows and resolves symbolic links before
acting. 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/
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 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 vari‐ ables. -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 configura‐ tion 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). --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). --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 tem‐ plate, and should set Choices-C: ${CHOICES} to ensure the re‐ turned 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
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)
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
examples 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 cur‐
rent cofiguration 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/
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