502 lines
14 KiB
HTML
502 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of UCF</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>UCF</H1>
|
|
Section: Debian GNU/Linux manual (1)<BR>Updated: May 30 2008<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
ucf - Update Configuration File: preserve user changes in configuration files
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>ucf</B>
|
|
|
|
[<I>options</I>]
|
|
|
|
<I><New File></I>
|
|
|
|
<I><Destination></I>
|
|
|
|
<P>
|
|
|
|
<B>ucf</B>
|
|
|
|
[<I>options</I>]
|
|
|
|
<I>--purge</I>
|
|
|
|
<I><Destination></I>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
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,
|
|
<I>New file</I>
|
|
|
|
is the configuration file as provided by the package (either shipped
|
|
with the package, or generated by the maintainer scripts on the fly),
|
|
and
|
|
<I>Destination</I>
|
|
|
|
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,
|
|
<B>ucf</B>
|
|
|
|
follows and resolves symbolic links before acting. As far as
|
|
possible, ucf attempts to preserve the ownership and permission of
|
|
the
|
|
<I>New file</I>
|
|
|
|
as it is copied to the new location.
|
|
<P>
|
|
|
|
This script attempts to provide conffile like handling for files
|
|
installed under
|
|
<I>/etc</I>
|
|
|
|
not
|
|
shipped in a
|
|
<B>Debian</B>
|
|
|
|
package, but handled by the postinst instead.
|
|
<B>Debian</B>
|
|
|
|
policy states that files under
|
|
<I>/etc</I>
|
|
|
|
which are configuration files
|
|
<B>must</B>
|
|
|
|
preserve user changes, and this applies to files handled by maintainer
|
|
scripts as well. Using
|
|
<B>ucf,</B>
|
|
|
|
one may ship a bunch of default configuration files somewhere in
|
|
<I>/usr</I>
|
|
|
|
(
|
|
<I>/usr/share/<pkg></I>
|
|
|
|
is a good location), and maintain files in
|
|
<I>/etc,</I>
|
|
|
|
preserving user changes and in general offering the same facilities
|
|
while upgrading that
|
|
<B>dpkg</B>
|
|
|
|
normally provides for
|
|
<I>``conffiles''</I>
|
|
|
|
<P>
|
|
|
|
Additionally, this script provides facilities for transitioning a file
|
|
that had not been provided
|
|
<I>conffile</I>
|
|
|
|
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
|
|
<B>dpkg</B>
|
|
|
|
while transitioning a file from a
|
|
<I>non-conffile</I>
|
|
|
|
to
|
|
<I>conffile</I>
|
|
|
|
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.
|
|
<P>
|
|
|
|
During the course of operations, when working with configuration files,
|
|
<B>ucf</B>
|
|
|
|
optionally creates copies of versions of the configuration file in
|
|
question. For example, a file with the suffix
|
|
<I>ucf-old</I>
|
|
|
|
holds the old version of a configuration file replaced by
|
|
<B>ucf.</B>
|
|
|
|
Also, copies of the configuration file with the suffixes
|
|
<I>ucf-new</I>
|
|
|
|
and
|
|
<I>ucf-dist</I>
|
|
|
|
may be created; and the maintainer scripts should consider purging
|
|
copies of the configuration file with these extensions during purge.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-h, --help</B>
|
|
|
|
<DD>
|
|
Print a short usage message
|
|
<DT id="2"><B>-n, --no-action</B>
|
|
|
|
<DD>
|
|
Dry run. Print the actions that would be taken if the script is
|
|
invoked, but take no action.
|
|
<DT id="3"><B>-d[n], --debug=[n]</B>
|
|
|
|
<DD>
|
|
Set the debug level to the (optional) level
|
|
<I>n</I>
|
|
|
|
(n defaults to 1). Please note there must be no spaces before the
|
|
optional digit n. This turns on copious debugging information.
|
|
<DT id="4"><B>-p, --purge</B>
|
|
|
|
<DD>
|
|
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).
|
|
<I>Note:</I>
|
|
|
|
ucf does not actually touch the file on disk in this operation, so any
|
|
file removals are still the responsibility of the calling package.
|
|
<DT id="5"><B>-v, --verbose</B>
|
|
|
|
<DD>
|
|
Make the script be very verbose about setting internal variables.
|
|
<DT id="6"><B>-s foo, --src-dir foo</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>UCF_SOURCE_DIR,</B>
|
|
|
|
and in the configuration file variable
|
|
<B>conf_source_dir.</B>
|
|
|
|
<DT id="7"><B>--sum-file foo</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>UCF_OLD_MDSUM_FILE,</B>
|
|
|
|
and in the configuration file variable
|
|
<B>conf_old_mdsum_file.</B>
|
|
|
|
<DT id="8"><B>--three-way</B>
|
|
|
|
<DD>
|
|
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).
|
|
<DT id="9"><B>--debconf-ok</B>
|
|
|
|
<DD>
|
|
Indicate that it is ok for
|
|
<I>ucf</I>
|
|
|
|
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).
|
|
<DT id="10"><B>--debconf-template foo</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>--three-way</B>
|
|
|
|
option is also set.
|
|
<DT id="11"><B>--state-dir /path/to/dir</B>
|
|
|
|
<DD>
|
|
Set the state directory to /path/to/dir instead of the default
|
|
<I>/var/lib/ucf.</I>
|
|
|
|
Used mostly for testing.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>USAGE</H2>
|
|
|
|
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
|
|
<B>ucf</B>
|
|
|
|
to forget about the configuration file on purge
|
|
(using the --purge option) is all that is needed (assuming ucf is
|
|
still on the system).
|
|
<P>
|
|
|
|
It is recommended that you also register any file being managed by
|
|
<B>ucf</B>
|
|
|
|
with the ucf registry; this associates the configuration file with the
|
|
package it belongs to. This is done with a simple call to
|
|
<B>ucfr.</B>
|
|
|
|
Users may then query the association between a configuration file and
|
|
the package using the tool
|
|
<B>ucfq.</B>
|
|
|
|
Please see the appropriate manual pages for details.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
The way to do this is to either create a file called
|
|
<B><New file>.md5sum,</B>
|
|
|
|
with one md5sum on each line, (the file names you use are ignored, except
|
|
for the entry named default), or create a directory, called
|
|
<B><New file>.md5sum.d,</B>
|
|
|
|
which should contain any number of files, each containing a single
|
|
line, namely, the md5sum of a previous version of
|
|
<B><New file>.</B>
|
|
|
|
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
|
|
<I>7.6.3,</I>
|
|
|
|
or
|
|
<I>potato.</I>
|
|
|
|
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.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>The default historical md5sum</H3>
|
|
|
|
The exception to the rule about names mentioned earlier is that if no
|
|
md5sums match, and if the file
|
|
<B><New file>.md5sum.d/default</B>
|
|
|
|
exists, or if there is a line corresponding to a
|
|
<I>default</I>
|
|
|
|
file in
|
|
<B><New file>.md5sum,</B>
|
|
|
|
it shall be used as the default md5sum of the
|
|
<I>previous</I>
|
|
|
|
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.
|
|
<P>
|
|
|
|
If the file
|
|
<B><New file>.md5sum,</B>
|
|
|
|
or the directory
|
|
<B><New file>.md5sum.d</B>
|
|
|
|
does not exist, or none of the md5sums match, we test the installed
|
|
<I><Destination></I>
|
|
|
|
file to see whether it is the same as the
|
|
<I><New file>.</I>
|
|
|
|
If not, we ask the user whether they want us to replace the file.
|
|
<P>
|
|
|
|
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.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ENVIRONMENT VARIABLES</H2>
|
|
|
|
The variable
|
|
<B>UCF_FORCE_CONFFNEW,</B>
|
|
|
|
if set, forces the new file to always overwrite the installed
|
|
destination file, while the variable
|
|
<B>UCF_FORCE_CONFFOLD,</B>
|
|
|
|
if set silently retains the installed file.
|
|
<B>UCF_FORCE_CONFFMISS</B>
|
|
|
|
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).
|
|
<A NAME="lbAI"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
This script creates the file
|
|
<I>new_file.md5sum,</I>
|
|
|
|
and it may copy the file (presumably shipped with the package)
|
|
<I><New file></I>
|
|
|
|
to its destination,
|
|
<I><Destination>.</I>
|
|
|
|
<P>
|
|
|
|
<I>/var/lib/ucf/hashfile,</I>
|
|
|
|
and
|
|
<I>/var/lib/ucf/hashfile.X,</I>
|
|
|
|
where
|
|
<I>X</I>
|
|
|
|
is a small integer, where previous versions of the hashfile are
|
|
stored.
|
|
<P>
|
|
|
|
<I>/etc/ucf.conf</I>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
If the package
|
|
<I>foo</I>
|
|
|
|
wants to use ucf to handle user interaction for configuration file
|
|
<I>foo.conf,</I>
|
|
|
|
a version of which is provided in the package as
|
|
<I>/usr/share/foo/configuration,</I>
|
|
|
|
a simple invocation of ucf in the post inst file is all that is
|
|
needed:
|
|
<P>
|
|
|
|
<B>ucf</B>
|
|
|
|
<I>/usr/share/foo/configuration</I>
|
|
|
|
<I>/etc/foo.conf</I>
|
|
|
|
<P>
|
|
|
|
On purge, one should tell ucf to forget about the file (see detailed
|
|
examples in /usr/share/doc/ucf/examples):
|
|
<P>
|
|
|
|
<B>ucf</B>
|
|
|
|
<I>--purge</I>
|
|
|
|
<I>/etc/foo.conf</I>
|
|
|
|
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 cofiguration
|
|
file. Do this if you want to change your decision to not update to a
|
|
maintainer provided version of the configuration file.
|
|
<P>
|
|
|
|
The motivation for this script was to provide conffile like handling
|
|
for start files for emacs lisp packages (for example,
|
|
<I>/etc/emacs21/site-start.d/50psgml-init.el</I>
|
|
|
|
) These start files are not
|
|
shipped with the package, instead, they are installed during the
|
|
post installation configuration phase by the script
|
|
<I>/usr/lib/emacsen-common/emacs-package-install $package_name.</I>
|
|
|
|
<P>
|
|
|
|
This script is meant to be invoked by the packages install script at
|
|
<I>/usr/lib/emacsen-common/packages/install/$package_name</I>
|
|
|
|
for each
|
|
flavour of installed emacsen by calling it with the proper values of
|
|
new file (
|
|
<I>/usr/share/emacs/site-lisp/<pkg>/<pkg-init.el</I>
|
|
|
|
), and dest file
|
|
(
|
|
<I>/etc/emacs21/site-start.d/50<pkg-init.el</I>
|
|
|
|
), and it should do the rest.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<A HREF="/cgi-bin/man/man2html?5+ucf.conf">ucf.conf</A>(5), <A HREF="/cgi-bin/man/man2html?1+ucfr">ucfr</A>(1), <A HREF="/cgi-bin/man/man2html?1+ucfq">ucfq</A>(1), and <A HREF="/cgi-bin/man/man2html?1+diff3">diff3</A>(1).
|
|
The
|
|
<B>Debian</B>
|
|
|
|
Emacs policy, shipped with the package
|
|
<I>emacsen-common.</I>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
This manual page was written Manoj Srivastava <<A HREF="mailto:srivasta@debian.org">srivasta@debian.org</A>>,
|
|
for the Debian GNU/Linux system.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="12"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="13"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="14"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="15"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="16"><A HREF="#lbAF">USAGE</A><DD>
|
|
<DL>
|
|
<DT id="17"><A HREF="#lbAG">The default historical md5sum</A><DD>
|
|
</DL>
|
|
<DT id="18"><A HREF="#lbAH">ENVIRONMENT VARIABLES</A><DD>
|
|
<DT id="19"><A HREF="#lbAI">FILES</A><DD>
|
|
<DT id="20"><A HREF="#lbAJ">EXAMPLES</A><DD>
|
|
<DT id="21"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="22"><A HREF="#lbAL">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:28 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|