sysconftool - install configuration files
sysconftool [options] [filename.dist...]
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.
, an application will install a configuration file
names filename.dist, instead of filename. Then, the application's installation
script runs 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
file, it's configuration settings replace the defaults in filename.dist, which
is then subsequently installed as filename. sysconftool
is smart enough
•Remove configuration settings that no longer
•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
produces a short report when it runs. The report lists every
configuration setting in $filename.dist, and its disposition. The possible
This a new configuration setting that wasn't found in the
This setting's value was taken from the existing
$filename, replacing the default value provided by $filename.dist.
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
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.
requires the application to use autoconf
. The first step is to run the sysconftoolize
from the application's source directory. sysconftoolize
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
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
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
Finally, certain sysconftool
magic incantations must be added to the
application's configuration files, see sysconftool
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
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.
Double Precision, Inc.