sysconftool - format of configuration files installed by sysconftool
This manual page describes the format of configuration files installed by
(1). This format is flexible enough to accomodate
any kind of application configuration file format. sysconftool
four assumptions about the configuration file:
1.It is a plain text file.
2.Lines that begin with a single '#' character are
comments that contain a description of the following configuration
3.Lines that do not begin with the '#' character contain
the configuration setting described by the previous comment lines.
4.Configuration settings are self contained, and
completely independent, changing one configuration setting never requires that
another, different, configuration setting must be changed too (perhaps any
logical conflicts are automatically resolved by the application in a safe,
The additional information used by sysconftool
is encoded as
specially-formatted comment lines that begin with two '#' characters.
An application installs a default configuration file as
"filename.dist", when the actual name of the configuration file is
really "filename". If there is no existing filename,
simply copies filename.dist to filename, and calls it a
day. Otherwise, sysconftool
copies the existing filename to
filename.bak and creates a new filename based on the contents of both files.
is designed to solve a common problem with application
configuration. New versions of applications often include additional
functionality that requires new configuration settings. Without the new
configuration settings the application will not work, so new configuration
files should be installed during the upgrade. However, when that happens, any
changes to the existing configuration settings are lost. sysconftool
designed to solve this dillemma, and merge old configuration settings with new
is designed in a fail-safe way. Whenever there's a
doubt as to what's The Right Thing To Do, sysconftool
will use the
configuration settings from the new file, that are supposedly known to be
good, and leave it up to a physical being to sort out any conflicts and make
any manual decisions.
The following line should appear at the beginning of filename.dist:
This doesn't have to be the very first line in filename.dist, but it should
appear somewhere within the first twenty lines, right before the first
configuration setting. "version" should be some kind of an
identifier for this particular version of the configuration files. All that
cares about is that any change to the default
configuration, in filename.dist, results in a different version
excellent way to do this is to simply use the $Id$ RCS/CVS version
identification strings, and have this little detail taken care of
New revisions of an application should not necessarily have a new configuration
. If the default application configuration settings have
not changed from the previous release, version
can remain the same.
is copied from filename.dist to filename.
If there's an existing filename, and it includes the same version
silently skips over this configuration file,
and doesn't do anything, assuming that this configuration file has already
been installed. Therefore, running sysconftool
more than once
(accidentally) will not break anything.
If there's an existing filename, but it's version
backs it up to filename.bak, then creates a new filename.
If there's an existing filename, but it doesn't contain a recognizable
" line, sysconftool
the previous version of the application did not use the sysconftool
tool. That's not a problem. filename is copied to filename.bak, and
filename.dist gets installed as the new filename, allowing sysconftool
to work with the next version of this configuration file.
Each configuration setting uses the following format in the configuration file:
looks for a line that begins with "##NAME". This
line gives the name and the revision of the following setting. name
must be unique within its configuration file (the same name
can be used
by different configuration files, sysconftool
works with one file at a
is used by sysconftool
to decide when the
configuration setting can be safely carried over from an older configuration
file, and when it is better to reinstall the default setting from the new
One or more comment lines - lines that begin with the '#' character - may follow
"##NAME". The first line that does not begin with '#' is considered
to be the first line that contains the value of the configuration setting,
which lasts. The value can be spread over multiple lines. The configuration
setting is considered to last until either the end of the file, or until the
first following line that begins with another "##NAME".
Aside from that, sysconftool
does not care how the configuration setting
is represented. It can be "NAME=VALUE", it can be "NAME:
VALUE", or "NAME<tab>VALUE", it can even be a
base64-encoded binary object, and it can always have leading or trailing blank
merely looks at which lines begin with the '#'
comment character. After the '##NAME:' line, sysconftool
until the first line that does not begin with '#', and that's the first line
of the configuration setting. Then, sysconftool
looks ahead until the
next line that starts with a "##NAME:", which marks the end of this
For this reason it is important that all commented description lines that follow
'##NAME:' must begin with the '#' character. If a blank line follows the line
with '##NAME:' it is assumed to be the start of the corresponding
configuration setting. For example, this is correct:
# This is the first configuration flag
This is not correct:
# This is the first configuration flag
A new configuration file, "filename", is created from its previous
version, "filename.bak" and the new default configuration file,
"filename.dist", using the following, simple, two-step process.
1.sysconftool begins with filename.dist in hand.
This makes sure that sysconftool begins with a good, known, default
2.sysconftool then takes each configuration
setting in filename.dist, then searches filename.bak. If it finds a
configuration setting that has an identical " name" and
" version", then the corresponding configuration setting
value is taken from filename.bak, replacing the default in filename.dist.
After all configuration settings in filename.dist are looked up (and
potentially replaced), what's left becomes the new filename.
The above process is a logical description. The actual technical implementation
is slightly different (for example, filename is not backed up to filename.bak
until the new configuration file has been already created), but is logically
equivalent to this process. This process carries a number of consequences that
must be considered.
If a new application revision needs a new configuration setting, it will get a
. Since filename.dist is used as a starting
point for the new configuration file, the new configuration file will include
the new configuration setting. When a configuration setting is removed, it
will disappear from the new configuration file for the same exact reason.
looks at both name
. A configuration
setting with the same name
but different version
s are seen by
as completely different settings. The existence of
allows a finer-grained control of configuration upgrades, as
copies setting values with the same name
from the old configuration file to the new configuration file.
However, the associated descriptive comments are not copied, and are taken
from the new filename.dist. Therefore, if a new version of the configuration
file contains an updated or an embellished description of a particular
setting, it will be included in the new configuration file, but the existing
configuration value will be preserved! Generally, if a configuration setting
does not change its meaning or function, its name
should remain the same. Its comments can be edited to fix a typo, or revised
in a more substantive fashion. Name
should only be
changed if there's a functional change in the configuration setting.
What to do with name
after a functional change depends
on the nature and the magnitude of the change. The nature and the magnitude of
the change must be considered not only with respect to the most recent
revision of the application, but to all the previous revisions as well. When
in doubt, go based upon the largest change in magnitude, in order to guarantee
a functional default setting, from filename.dist, and leave it up to a living
being to manually figure it out.
If only the default value of a setting should be changed for new application
installation, but the existing installations can continue to use the existing
value of the setting, both the name
should be left
alone. Existing configuration settings will be preserved, and new
installations will get the new default. The descriptive comment of this
setting can be updated too (see above).
This should be done only as long as ALL
previous values of this
configuration setting will ALWAYS be valid in the new application revision. If
some possible values of this configuration setting will no longer be valid,
should be changed. sysconftool
does not care how
are formatted. Both are opaque labels. The only
requirements is for the label to be different. The difference between changing
and changing both name
If there's an old configuration setting with the same name
will still use the new, safe, default value
from filename.dist, however sysconftool
will also append an additional
comment, on its own accord, reminding the reader that this configuration value
has been reset, and the reader should consider whether to manually restore the
configuration value from the old configuration.
decides to keep an existing setting, with the same
, it will also insert a short comment to that
effect, reminding the reader to check the default in filename.dist.
Double Precision, Inc.