Man Linux: Main Page and Category List


       sysconftool - format of configuration files installed by sysconftool


          ##VERSION: $Id$

          ##NAME: configname1:configname1version
          # Description


          ##NAME: configname2:configname2version
          # 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.


       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

       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


       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


       This is not correct:

          ##NAME: flag1:0

          # This is the first configuration flag



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

       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


       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.