👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for ucf (linux section 1)

UCF(1)				     Debian GNU/Linux manual				   UCF(1)

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  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 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  loca-
       tion.

       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  facili-
       ties 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  configu-
	      ration 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 configu-
	      ration 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 main-
	      tainer  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).

       --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 --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  configu-
       ration  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  reg-
       istry; 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  sta-
       tus  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 main-
       tainer 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 ver-
       sion 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 pre-
       vious 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-pack-
       age-install $package_name.

       This script is meant to be invoked by the packages install script at /usr/lib/emacsen-com-
       mon/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.

AUTHOR
       This  manual  page  was	written  Manoj	Srivastava  <srivasta@debian.org>, for the Debian
       GNU/Linux system.

Debian					   May 30 2008					   UCF(1)


All times are GMT -4. The time now is 12:00 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password