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
       creates a symbolic link to the sysconftool script from the current directory, and appends
       a default install-configure rule to Makefile.am.  sysconftoolize with the --copy option
       copies the script, instead of creating a symbolic link.

       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)[1] 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)[2], sysconftool(7)[1].

AUTHORS

       Double Precision, Inc.

NOTES

        1. sysconftool(7)
           [set $man.base.url.for.relative.links]/sysconftool.7.html

        2. sysconftoolcheck(1)
           [set $man.base.url.for.relative.links]/sysconftoolcheck.1.html