Provided by: sysconftool_0.15-1_i386 bug

NAME

       sysconftool - install configuration files

SYNOPSIS

       sysconftool [ options ] [ filename.dist ... ]

DESCRIPTION

       sysconftool  is a development utility that helps to install application
       configuration files. sysconftool allows an existing application  to  be
       upgraded without losing the older version’s configuration settings.

       A  new  version  of  an  application often introduces new configuration
       settings.  Sometimes  obsolete  configuration  settings  are   removed.
       Existing  configuration  settings may also now have additional options,
       or certain options are no longer valid any more.  Because of  this,  an
       application  upgrade  usually  installs  a  fresh  set of configuration
       files,  containing  a  default  configuration  that’s  known  to  work.
       Keeping  the existing files carries the risk of the application failing
       to function properly due to a configuration that is no longer valid.

       A typical application installation  script  copies  over  configuration
       files  with  default settings.  Existing configuration files are backed
       up or overwritten. With sysconftool,  an  application  will  install  a
       configuration file names filename.dist, instead of filename.  Then, the
       application’s installation script runs sysconftool.  sysconftool copies
       filename.dist  to  filename,  but also checks if filename from an older
       version  of  the  application  already  exist.  If  filename  an  older
       sysconftool-installed  configuration  file, it’s configuration settings
       replace the defaults  in  filename.dist,  which  is  then  subsequently
       installed as filename.  sysconftool is smart enough to:

       · Remove configuration settings that no longer exist.

       · Add new configuration settings.

       · Do   not  preserve  an  older  configuration  setting  if  there’s  a
         possibility that it is no longer valid in  the  new  version  of  the
         application.

       sysconftool  produces  a  short  report  when it runs. The report lists
       every configuration setting in  $filename.dist,  and  its  disposition.
       The possible dispositions are:

       new    This  a  new  configuration  setting  that  wasn’t  found in the
              existing $filename.

       unchanged
              This setting’s value was  taken  from  the  existing  $filename,
              replacing the default value provided by $filename.dist.

       UPDATED
              This  setting  has  been  previously  set  in $filename, but the
              setting’s value may no longer be valid in the new version of the
              application,  so its default value is taken from $filename.dist,
              and it may need to be manually adjusted.

       All this logic is based  on  some  additional  metadata  that  must  be
       included  in each configuration file, that sysconftool reads.  For this
       to work, both the old and the new version of the  application  must  be
       sysconftool-ized.   sysconftool  operates  in a fail-safe mode.  If the
       old version  did  not  use  sysconftool,  $filename  is  backed  up  to
       $filename.bak, and $filename is copied to $filename. This is what would
       essentially happen anyway without sysconftool.  The local configuration
       needs to be reentered into $filename, so nothing is lost.  However, the
       next upgrade will see sysconftool do its job.

ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION

       sysconftool requires the application to use autoconf and automake.  The
       first  step  is to run the sysconftoolize script from the application’s
       source directory.  sysconftoolize copies the sysconftool script to  the
       current  directory,  and  appends  a  default install-configure rule to
       Makefile.am. After running sysconftoolize the macro AC_PROG_SYSCONFTOOL
       must  be  manually  added  to  configure.in,  and  Makefile.am  must be
       modified as follows.

       Makefile.am  must  be  modified  to  install  configuration  files   as
       filename.dist  instead of filename.  The default install-configure rule
       assumes that sysconf_DATA lists all configuration files in  sysconfdir,
       and  runs  sysconftool on them.  This will usually have to be modified,
       according to the application’s individual needs.  Finally,  Makefile.am
       must   be   modified  to  distribute  the  sysconftool  script  in  the
       application’s source distribution.  Adding sysconftool to EXTRA_DIST is
       what’s needed in most cases.

       Finally,  certain  sysconftool  magic incantations must be added to the
       application’s  configuration  files,  see   sysconftool(7)   for   more
       information.  The last step involves updating the application’s INSTALL
       instructions, so that the application can be properly  installed.   The
       following instructions must be added to INSTALL:

       1. Run "make install-configure" after "make install".

       2. If  this  is  the first sysconftool-ized version, DO NOT simply copy
          over  the  old  configuration   files,   and   overwrite   the   new
          configuration  files.   Instead,  manually  edit  each configuration
          file, and  manually  reset  each  configuration  setting.   This  is
          because  the  new  configuration  files  include  the magic code for
          sysconftool, which would be lost  when  the  configuration  file  is
          overwritten.

       3. If  this  is  not  the first sysconftool-ized version, the output of
          make install-configure must be reviewed in order to manually  adjust
          or  tweak  what sysconftool did.  Many large configuration files can
          result in lots of output, so the output  of  make  install-configure
          should be saved into a file, and reviewed.

SEE ALSO

       sysconftoolcheck(1), sysconftool(7).