Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
UCF(1)			    Debian GNU/Linux manual			UCF(1)



NAME
       ucf  -  Update Configuration File:  preserve user changes in configura
       tion files

SYNOPSIS
       ucf [options]  

       ucf [options] --purge 

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  (usu
       ally under /etc) where the real configuration file lives, and is poten
       tially 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/ is a good location), and maintain files in /etc,  pre
       serving	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 cre
       ated; 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  vari
	      ables.

       -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  configura
	      tion  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 ver
	      sion 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.  Pack
	      ages 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 tem
	      plate, 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 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 .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 .md5sum.d, which should contain any number of files, each contain
       ing a single line, namely, the md5sum of a  previous  version  of  .  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 com
       plete, 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 .md5sum.d/default exists, or
       if  there  is  a  line  corresponding  to  a  default  file   in   .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  .md5sum, or the directory .md5sum.d
       does not exist, or none of the md5sums match,  we  test	the  installed
        file to see whether it is the same as the .  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)  to its 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 con
       figuration 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-com
       mon/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//,
       for the Debian GNU/Linux system.



Debian				  May 30 2008				UCF(1)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:23 2009