'\" t
.\"<!-- $Id: sysconftool7.sgml,v 1.3 2007/04/06 20:04:16 mrsam Exp $ -->
.\"<!-- Copyright 2000-2005 Double Precision, Inc.  See COPYING for -->
.\"<!-- distribution information. -->
.\"     Title: sysconftool
.\"    Author: Double Precision, Inc.
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 04/05/2011
.\"    Manual: sysconftool
.\"    Source: Courier Mail Server
.\"  Language: English
.\"
.TH "SYSCONFTOOL" "7" "04/05/2011" "Courier Mail Server" "sysconftool"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sysconftool \- format of configuration files installed by sysconftool
.SH "SYNOPSIS"
.sp
.nf
   #
   ##VERSION: $Id$

   ##NAME: configname1:configname1version
   #
   # Description

   SETTING1=VALUE1

   ##NAME: configname2:configname2version
   #
   # Description

   SETTING2=VALUE2

   \&.\&.\&.
.fi
.SH "DESCRIPTION"
.PP
This manual page describes the format of configuration files installed by
\m[blue]\fB\fBsysconftool\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&. This format is flexible enough to accommodate any kind of application configuration file format\&.
\fBsysconftool\fR
makes four assumptions about the configuration file:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
It is a plain text file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Lines that begin with a single \'#\' character are comments that contain a description of the following configuration setting\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Lines that do not begin with the \'#\' character contain the configuration setting described by the previous comment lines\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
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)
.RE
.PP
The additional information used by
\fBsysconftool\fR
is encoded as specially\-formatted comment lines that begin with two \'#\' characters\&.
.SH "FILENAMES"
.PP
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,
\fBsysconftool\fR
simply copies
filename\&.dist
to
filename, and calls it a day\&. Otherwise,
\fBsysconftool\fR
copies the existing
filename
to
filename\&.bak
and creates a new
filename
based on the contents of both files\&.
.PP

\fBsysconftool\fR
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\&.
\fBsysconftool\fR
is designed to solve this dillemma, and merge old configuration settings with new ones\&.
\fBsysconftool\fR
is designed in a fail\-safe way\&. Whenever there\'s a doubt as to what\'s The Right Thing To Do,
\fBsysconftool\fR
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\&.
.SH "FILE VERSIONING"
.PP
The following line should appear at the beginning of
filename\&.dist:
.sp
.if n \{\
.RS 4
.\}
.nf
   ##VERSION: \fIversion\fR
.fi
.if n \{\
.RE
.\}
.PP
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
\fBsysconftool\fR
cares about is that any change to the default configuration, in
filename\&.dist, results in a different
\fIversion\fR\&. 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\&.
.PP
New revisions of an application should not necessarily have a new configuration file
\fIversion\fR\&. If the default application configuration settings have not changed from the previous release,
\fIversion\fR
can remain the same\&.
\fIversion\fR
is copied from
filename\&.dist
to
filename\&.
.PP
If there\'s an existing
filename, and it includes the same
\fIversion\fR
identifier,
\fBsysconftool\fR
silently skips over this configuration file, and doesn\'t do anything, assuming that this configuration file has already been installed\&. Therefore, running
\fBsysconftool\fR
more than once (accidentally) will not break anything\&.
.PP
If there\'s an existing
filename, but it\'s
\fIversion\fR
is different,
\fBsysconftool\fR
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:
\fIversion\fR" line,
\fBsysconftool\fR
assumes that the previous version of the application did not use the
\fBsysconftool\fR
tool\&. That\'s not a problem\&.
filename
is copied to
filename\&.bak, and
filename\&.dist
gets installed as the new
filename, allowing
\fBsysconftool\fR
to work with the next version of this configuration file\&.
.SH "CONFIGURATION SETTING VERSIONING"
.PP
Each configuration setting uses the following format in the configuration file:
.sp
.if n \{\
.RS 4
.\}
.nf
   ##NAME: \fIname\fR:\fIrevision\fR
   #
   # \fIdescription\fR

   \fIsetting\fR
.fi
.if n \{\
.RE
.\}
.PP

\fBsysconftool\fR
looks for a line that begins with "##NAME"\&. This line gives the name and the revision of the following setting\&.
\fIname\fR
must be unique within its configuration file (the same
\fIname\fR
can be used by different configuration files,
\fBsysconftool\fR
works with one file at a time)\&.
\fIrevision\fR
is used by
\fBsysconftool\fR
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\&.
.PP
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"\&.
.PP
Aside from that,
\fBsysconftool\fR
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\&.
\fBsysconftool\fR
merely looks at which lines begin with the \'#\' comment character\&. After the \'##NAME:\' line,
\fBsysconftool\fR
looks ahead until the first line that does not begin with \'#\', and that\'s the first line of the configuration setting\&. Then,
\fBsysconftool\fR
looks ahead until the next line that starts with a "##NAME:", which marks the end of this configuration setting\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
   ##NAME: flag1:0
   #
   #
   # This is the first configuration flag
   #

   flag1=1
.fi
.if n \{\
.RE
.\}
.PP
This is not correct:
.sp
.if n \{\
.RS 4
.\}
.nf
   ##NAME: flag1:0

   #
   # This is the first configuration flag
   #

   flag1=1
.fi
.if n \{\
.RE
.\}
.SH "CONFIGURATION FILE CREATION"
.PP
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\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}

\fBsysconftool\fR
begins with
filename\&.dist
in hand\&. This makes sure that
\fBsysconftool\fR
begins with a good, known, default configuration file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}

\fBsysconftool\fR
then takes each configuration setting in
filename\&.dist, then searches
filename\&.bak\&. If it finds a configuration setting that has an identical "\fIname\fR" and "\fIversion\fR", 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\&.
.RE
.SH "THE END RESULT"
.PP
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\&.
.PP
If a new application revision needs a new configuration setting, it will get a new
\fIname\fR
and
\fIversion\fR\&. 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\&.
.SH "CONFIGURATION SETTING VERSION"
.PP

\fBsysconftool\fR
looks at both
\fIname\fR
and
\fIversion\fR\&. A configuration setting with the same
\fIname\fR
but different
\fIversion\fRs are seen by
\fBsysconftool\fR
as completely different settings\&. The existence of
\fIversion\fR
allows a finer\-grained control of configuration upgrades, as described below\&.
.PP

\fBsysconftool\fR
copies setting values with the same
\fIname\fR
and
\fIversion\fR
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
\fIname\fR
and
\fIversion\fR
should remain the same\&. Its comments can be edited to fix a typo, or revised in a more substantive fashion\&.
\fIName\fR
and
\fIversion\fR
should only be changed if there\'s a functional change in the configuration setting\&.
.PP
What to do with
\fIname\fR
and
\fIversion\fR
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\&.
.PP
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
\fIname\fR
and
\fIversion\fR
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)\&.
.PP
This should be done only as long as
\fIALL\fR
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,
\fIversion\fR
should be changed\&.
\fBsysconftool\fR
does not care how
\fIname\fR
and
\fIversion\fR
are formatted\&. Both are opaque labels\&. The only requirements is for the label to be different\&. The difference between changing
\fIversion\fR
and changing both
\fIname\fR
and
\fIversion\fR
is this:
.PP
If there\'s an old configuration setting with the same
\fIname\fR
but different
\fIversion\fR,
\fBsysconftool\fR
will still use the new, safe, default value from
filename\&.dist, however
\fBsysconftool\fR
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\&.
.SH "MISCELLANEA"
.PP
When
\fBsysconftool\fR
decides to keep an existing setting, with the same
\fIname\fR
and
\fIvalue\fR, it will also insert a short comment to that effect, reminding the reader to check the default in
filename\&.dist\&.
.SH "SEE ALSO"
.PP

\m[blue]\fB\fBsysconftool\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "AUTHORS"
.PP
\fBDouble Precision, Inc\&.\fR
.SH "NOTES"
.IP " 1." 4
\fBsysconftool\fR(1)
.RS 4
\%[set $man.base.url.for.relative.links]/sysconftool.1.html
.RE
