Provided by: sysconftool_0.15-1_i386 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).