Provided by: sysconftool_0.15-1_amd64 bug

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

SEE ALSO

       sysconftool(1).