Ubuntu Manpage: sysconftool - format of configuration files installed by sysconftool

NAME

       sysconftool - format of configuration files installed by sysconftool

SYNOPSIS

          #
          ##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 accommodate 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 VERSION

sysconftool 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.

AUTHORS

       Double Precision, Inc.

NOTES

        1. sysconftool(1)
           [set $man.base.url.for.relative.links]/sysconftool.1.html