mirror of https://gitee.com/openkylin/ucf.git
370 lines
13 KiB
Groff
370 lines
13 KiB
Groff
.\" -*- Mode: Nroff -*-
|
|
.\" updateConfFile.1 ---
|
|
.\" Author : Manoj Srivastava ( srivasta@green-gryphon.com )
|
|
.\" Created On : Fri Feb 1 11:17:32 2002
|
|
.\" Created On Node : glaurung.green-gryphon.com
|
|
.\" Last Modified By : Manoj Srivastava
|
|
.\" Last Modified On : Tue Apr 11 14:46:06 2006
|
|
.\" Last Machine Used: glaurung.internal.golden-gryphon.com
|
|
.\" Update Count : 53
|
|
.\" Status : Unknown, Use with caution!
|
|
.\" HISTORY :
|
|
.\" Description :
|
|
.\"
|
|
.\" Copyright (c) 2002 Manoj Srivastava <srivasta@debian.org>
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
|
|
.\" 02111-1307, USA.
|
|
.\"
|
|
.\" $Id: ucf.1,v 1.10 2003/09/28 23:29:21 srivasta Exp $
|
|
.TH UCF 1 "May 30 2008" "Debian" "Debian GNU/Linux manual"
|
|
.SH NAME
|
|
ucf \- Update Configuration File: preserve user changes in configuration files
|
|
.SH SYNOPSIS
|
|
.B ucf
|
|
.RI [ options "] "
|
|
.I <New File>
|
|
.I <Destination>
|
|
.PP
|
|
.B ucf
|
|
.RI [ options "] "
|
|
.I \-\-purge
|
|
.I <Destination>
|
|
.SH 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,
|
|
.I 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
|
|
.I 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,
|
|
.B ucf
|
|
follows and resolves symbolic links before acting. As far as
|
|
possible, ucf attempts to preserve the ownership and permission of
|
|
the
|
|
.I New file
|
|
as it is copied to the new location.
|
|
.PP
|
|
This script attempts to provide conffile like handling for files
|
|
installed under
|
|
.I /etc
|
|
not
|
|
shipped in a
|
|
.B Debian
|
|
package, but handled by the postinst instead.
|
|
.B Debian
|
|
policy states that files under
|
|
.I /etc
|
|
which are configuration files
|
|
.B must
|
|
preserve user changes, and this applies to files handled by maintainer
|
|
scripts as well. Using
|
|
.B ucf,
|
|
one may ship a bunch of default configuration files somewhere in
|
|
.I /usr
|
|
(
|
|
.I /usr/share/<pkg>
|
|
is a good location), and maintain files in
|
|
.I /etc,
|
|
preserving user changes and in general offering the same facilities
|
|
while upgrading that
|
|
.B dpkg
|
|
normally provides for
|
|
.I \*(lqconffiles\*(rq
|
|
.PP
|
|
Additionally, this script provides facilities for transitioning a file
|
|
that had not been provided
|
|
.I 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
|
|
.B dpkg
|
|
while transitioning a file from a
|
|
.I non\-conffile
|
|
to
|
|
.I 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.
|
|
.PP
|
|
During the course of operations, when working with configuration files,
|
|
.B ucf
|
|
optionally creates copies of versions of the configuration file in
|
|
question. For example, a file with the suffix
|
|
.I "ucf-old"
|
|
holds the old version of a configuration file replaced by
|
|
.B ucf.
|
|
Also, copies of the configuration file with the suffixes
|
|
.I "ucf-new"
|
|
and
|
|
.I "ucf-dist"
|
|
may be created; and the maintainer scripts should consider purging
|
|
copies of the configuration file with these extensions during purge.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B "\-h, \-\-help"
|
|
Print a short usage message
|
|
.TP
|
|
.B "\-n, \-\-no\-action"
|
|
Dry run. Print the actions that would be taken if the script is
|
|
invoked, but take no action.
|
|
.TP
|
|
.B "\-d[n], \-\-debug=[n]"
|
|
Set the debug level to the (optional) level
|
|
.I n
|
|
(n defaults to 1). Please note there must be no spaces before the
|
|
optional digit n. This turns on copious debugging information.
|
|
.TP
|
|
.B "\-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).
|
|
.I 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.
|
|
.TP
|
|
.B "\-v, \-\-verbose"
|
|
Make the script be very verbose about setting internal variables.
|
|
.TP
|
|
.B "\-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
|
|
.B UCF_SOURCE_DIR,
|
|
and in the configuration file variable
|
|
.B conf_source_dir.
|
|
.TP
|
|
.B "\-\-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
|
|
.B UCF_OLD_MDSUM_FILE,
|
|
and in the configuration file variable
|
|
.B conf_old_mdsum_file.
|
|
.TP
|
|
.B "\-\-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).
|
|
.TP
|
|
.B "\-\-debconf\-ok"
|
|
Indicate that it is ok for
|
|
.I 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).
|
|
.TP
|
|
.B "\-\-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
|
|
.B \-\-three\-way
|
|
option is also set.
|
|
.TP
|
|
.B "\-\-state\-dir /path/to/dir"
|
|
Set the state directory to /path/to/dir instead of the default
|
|
.I /var/lib/ucf.
|
|
Used mostly for testing.
|
|
.SH 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
|
|
.B 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).
|
|
.PP
|
|
It is recommended that you also register any file being managed by
|
|
.B ucf
|
|
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.
|
|
Users may then query the association between a configuration file and
|
|
the package using the tool
|
|
.B ucfq.
|
|
Please see the appropriate manual pages for details.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The way to do this is to either create a file called
|
|
.B <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
|
|
.B <New file>.md5sum.d,
|
|
which should contain any number of files, each containing a single
|
|
line, namely, the md5sum of a previous version of
|
|
.B <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
|
|
.I 7.6.3,
|
|
or
|
|
.I 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.
|
|
.SS "The default historical md5sum"
|
|
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
|
|
exists, or if there is a line corresponding to a
|
|
.I default
|
|
file in
|
|
.B <New file>.md5sum,
|
|
it shall be used as the default md5sum of the
|
|
.I 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.
|
|
.PP
|
|
If the file
|
|
.B <New file>.md5sum,
|
|
or the directory
|
|
.B <New file>.md5sum.d
|
|
does not exist, or none of the md5sums match, we test the installed
|
|
.I <Destination>
|
|
file to see whether it is the same as the
|
|
.I <New file>.
|
|
If not, we ask the user whether they want us to replace the file.
|
|
.PP
|
|
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.
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
The variable
|
|
.B UCF_FORCE_CONFFNEW,
|
|
if set, forces the new file to always overwrite the installed
|
|
destination file, while the variable
|
|
.B UCF_FORCE_CONFFOLD,
|
|
if set silently retains the installed file.
|
|
.B 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).
|
|
.SH FILES
|
|
This script creates the file
|
|
.I new_file.md5sum,
|
|
and it may copy the file (presumably shipped with the package)
|
|
.I <New file>
|
|
to its destination,
|
|
.I <Destination>.
|
|
.PP
|
|
.I /var/lib/ucf/hashfile,
|
|
and
|
|
.I /var/lib/ucf/hashfile.X,
|
|
where
|
|
.I X
|
|
is a small integer, where previous versions of the hashfile are
|
|
stored.
|
|
.PP
|
|
.I /etc/ucf.conf
|
|
.SH EXAMPLES
|
|
If the package
|
|
.I foo
|
|
wants to use ucf to handle user interaction for configuration file
|
|
.I foo.conf,
|
|
a version of which is provided in the package as
|
|
.I /usr/share/foo/configuration,
|
|
a simple invocation of ucf in the post inst file is all that is
|
|
needed:
|
|
.PP
|
|
.B ucf
|
|
.I /usr/share/foo/configuration
|
|
.I /etc/foo.conf
|
|
.PP
|
|
On purge, one should tell ucf to forget about the file (see detailed
|
|
examples in /usr/share/doc/ucf/examples):
|
|
.PP
|
|
.B ucf
|
|
.I \-\-purge
|
|
.I /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 cofiguration
|
|
file. Do this if you want to change your decision to not update to a
|
|
maintainer provided version of the configuration file.
|
|
.PP
|
|
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
|
|
) 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.
|
|
.PP
|
|
This script is meant to be invoked by the packages install script at
|
|
.I /usr/lib/emacsen\-common/packages/install/$package_name
|
|
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
|
|
), and dest file
|
|
(
|
|
.I /etc/emacs21/site\-start.d/50<pkg\-init.el
|
|
), and it should do the rest.
|
|
.SH "SEE ALSO"
|
|
ucf.conf(5), ucfr(1), ucfq(1), and diff3(1).
|
|
The
|
|
.B Debian
|
|
Emacs policy, shipped with the package
|
|
.I emacsen\-common.
|
|
.SH AUTHOR
|
|
This manual page was written Manoj Srivastava <srivasta@debian.org>,
|
|
for the Debian GNU/Linux system.
|