SYSCONFTOOL(7)sysconftoolSYSCONFTOOL(7)NAMEsysconftool - format of configuration files installed by sysconftoolSYNOPSIS
#
##VERSION: $Id$
##NAME: configname1:configname1version
#
# Description
SETTING1=VALUE1
##NAME: configname2:configname2version
#
# Description
SETTING2=VALUE2
...
DESCRIPTION
This manual page describes the format of configuration files installed
by sysconftool(1)[1]. This format is flexible enough to accomodate any
kind of application configuration file format. sysconftool makes 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 setting.
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, fallback, manner)
The additional information used by sysconftool is encoded as
specially-formatted comment lines that begin with two '#' characters.
FILENAMES
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, sysconftool 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.
sysconftool 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 is designed to solve this dillemma, and merge
old configuration settings with new ones. sysconftool 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.
FILE VERSIONING
The following line should appear at the beginning of filename.dist:
##VERSION: version
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 sysconftool cares about is that any change to the default
configuration, in filename.dist, results in a different version. An
excellent way to do this is to simply use the $Id$ RCS/CVS version
identification strings, and have this little detail taken care of
automatically.
New revisions of an application should not necessarily have a new
configuration file version. If the default application configuration
settings have not changed from the previous release, version can remain
the same. version is copied from filename.dist to filename.
If there's an existing filename, and it includes the same version
identifier, sysconftool 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 is different,
sysconftool backs it up to filename.bak, then creates a new filename.
If there's an existing filename, but it doesn't contain a recognizable
"##VERSION: version" line, sysconftool assumes that 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.
CONFIGURATION SETTING VERSIONING
Each configuration setting uses the following format in the
configuration file:
##NAME: name:revision
#
# description
setting
sysconftool 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
time). revision 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 configuration file.
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 lines.
sysconftool merely looks at which lines begin with the '#' comment
character. After the '##NAME:' line, sysconftool looks ahead 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
configuration setting.
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:
##NAME: flag1:0
#
#
# This is the first configuration flag
#
flag1=1
This is not correct:
##NAME: flag1:0
#
# This is the first configuration flag
#
flag1=1
CONFIGURATION FILE CREATION
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 configuration file.
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 END RESULT
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 new name and version. 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.
CONFIGURATION SETTING VERSIONsysconftool looks at both name and version. A configuration setting
with the same name but different versions are seen by sysconftool as
completely different settings. The existence of version allows a
finer-grained control of configuration upgrades, as described below.
sysconftool copies setting values with the same name and version 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
and version should remain the same. Its comments can be edited to fix a
typo, or revised in a more substantive fashion. Name and version
should only be changed if there's a functional change in the
configuration setting.
What to do with name and version 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 and version
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, version should be changed. sysconftool does not care
how name and version are formatted. Both are opaque labels. The only
requirements is for the label to be different. The difference between
changing version and changing both name and version is this:
If there's an old configuration setting with the same name but
different version, sysconftool 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.
MISCELLANEA
When sysconftool decides to keep an existing setting, with the same
name and value, it will also insert a short comment to that effect,
reminding the reader to check the default in filename.dist.
SEE ALSOsysconftool(1)[1].
AUTHORS
Double Precision, Inc.
NOTES
1. sysconftool(1)
[set $man.base.url.for.relative.links]/sysconftool.1.html
Courier Mail Server 08/25/2013 SYSCONFTOOL(7)
