Provided by: sysconftool_0.17-1_amd64 
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