Интерактивная система просмотра системных руководств (man-ов)
ucf (1)
>> ucf (1) ( Linux man: Команды и прикладные программы пользовательского уровня )
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 the times
interaction. 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).
--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.
BUGS
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
AUTHOR
This manual page was written Manoj Srivastava <[email protected]>,
for the Debian GNU/Linux system.
