sysconftool [options] file1.dist file2.dist...
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: A) remove configuration settings
that no longer exist; B) add new configuration settings; C) 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
will list every configuration setting in $filename.dist, and its disposition.
The possible dispositions are: "new" - 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.
This logic is based on some additional information, that must be included
in each configure file, that is used by sysconftool to implement
this logic. 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,
requiring the local configuration to be reentered into $filename, so
nothing is lost. However, the next upgrade will see sysconftool
do its job.
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. Usually, it's simply a matter of adding
sysconftool to "EXTRA_DIST" is sufficient.
Finally, certain sysconftool magic words 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. 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.