Copyright (C) 2000-2012 |
Manpages UCFSection: Debian GNU/Linux manual (1)Updated: Feb 1 2002 Index Return to Main Contents NAMEucf - Update Configuration File: preserve user changes in config filesSYNOPSISucf [options] <New File> <Destination>ucf [options] --purge <Destination> DESCRIPTIONWhere 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.This script attempts to provide conffile like handling for files installed under not shipped in a Debian package, but handled by the postinst instead. Debian policy states that files under 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 ( is a good location), and maintain files in 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. OPTIONS
USAGEThe 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.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 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 md5sumThe 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 ofered: 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 configratrion 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 VARIABLESThe 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.FILESThis script creates the file and it may copy the file (presumably shipped with the package) <New file> to its destination, <Destination>.and where X is a small integer, where previous versions of the hashfile are stored. EXAMPLESIf the package wants to use ucf to handle user interaction for configuration file a version of which is provided in the package as a simple invocation of ucf in the post inst file is all that is needed:ucf On purge, on should tell ucf to forget about the file (se detailed examples in /usr/share/doc/examples): ucf --purge The motivation for this script was to provide conffile like handling for start files for emacs lisp packages (for example, ) These start files are not shipped with the package, instead, they are installed during the post installation configuration phase by the script This script is meant to be invoked by the packages install script at for each flavour of installed emacsen by calling it with the proper values of new file ( ), and dest file ( ), and it should do the rest. SEE ALSOucf.conf(5), diff3(1). The Debian Emacs policy, shipped with the package emacsen-common.BUGSThere are no bugs. Any resemblance thereof is delirium. Really.AUTHORThis manual page was written Manoj Srivastava <srivasta@debian.org>, for the Debian GNU/Linux system.
IndexThis document was created by man2html, using the manual pages. Time: 12:18:45 GMT, April 26, 2024 |