man > ucf(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 poten‐
       tially modified by the end user.  Since the files edited would be real files,  and  not  sym‐
       bolic  links,  ucf follows and resolves symbolic links before acting. 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  up‐
       grading that dpkg normally provides for “conffiles”

       Additionally, this script provides facilities for transitioning a file that had not been pro‐
       vided  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 cre‐
       ates 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 exten‐
       sions 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).  Please  note  there
              must  be no spaces before the optional digit n. This turns on copious debugging infor‐
              mation.

       -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 responsi‐
              bility of the calling package.

       -v, --verbose
              Make the script be very verbose about setting internal variables.

       -P foo, --package foo
              Don't follow dpkg-divert diversions by package foo when updating configuration files.

       -s foo, --src-dir  foo
              Set the source directory (historical md5sums are expected to live in files and sub di‐
              rectories  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 liv‐
              ing in the source directory.  Setting this option overrides settings in  the  environ‐
              ment   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 ver‐
              sion 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).

       --debconf-ok
              Indicate that it is ok for ucf to use an already running debconf instance for  prompt‐
              ing  (it  has always been ok to use ucf when debconf is not running -- it shall invoke
              debconf as needed).

       --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 tem‐
              plate  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.

       -Z     Set SELinux security context of destination file to default type.

USAGE
       The most common case usage is pretty simple: a single line invocation in the postinst on con‐
       figure,  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 re‐
       ducing 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 pre‐
       vious 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  cre‐
       ate  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 spe‐
       cially.   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  in‐
       stalled  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).
       Additionally, when ucf creates an inferior shell, it populates the variables UCF_CONFFILE_NEW
       and UCF_CONFFILE_OLD which are useful for inspecting the changes.

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 previ‐
       ous 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 Please note that purge can also be used to make ucf forget the pre‐
       vious 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.

       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 installa‐
       tion  configuration  phase by the script /usr/lib/emacsen-common/emacs-package-install $pack‐
       age_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 pack‐
       age emacsen-common.

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

Debian                                       May 30 2008                                      UCF(1)