sysconftool — format of configuration files installed by sysconftool
# ##VERSION: $Id$ ##NAME: configname1:configname1version # # Description SETTING1=VALUE1 ##NAME: configname2:configname2version # # Description SETTING2=VALUE2 ...
This manual page describes the format of configuration files installed by sysconftool(1). This format is flexible enough to accomodate any kind of application configuration file format. sysconftool makes four assumptions about the configuration file:
It is a plain text file.
Lines that begin with a single '#' character are comments that contain a description of the following configuration setting.
Lines that do not begin with the '#' character contain the configuration setting described by the previous comment lines.
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.
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.
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.
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
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.
sysconftool begins with filename.dist
in hand. This
makes sure that sysconftool begins with a good, known,
default configuration file.
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 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.
sysconftool looks at both name
and version
. A
configuration setting with the same name
but
different version
s
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.