1SYSCONFTOOL(7)                    sysconftool                   SYSCONFTOOL(7)
2
3
4

NAME

6       sysconftool - format of configuration files installed by sysconftool
7

SYNOPSIS

9          #
10          ##VERSION: $Id$
11
12          ##NAME: configname1:configname1version
13          #
14          # Description
15
16          SETTING1=VALUE1
17
18          ##NAME: configname2:configname2version
19          #
20          # Description
21
22          SETTING2=VALUE2
23
24          ...
25

DESCRIPTION

27       This manual page describes the format of configuration files installed
28       by sysconftool(1)[1]. This format is flexible enough to accomodate any
29       kind of application configuration file format.  sysconftool makes four
30       assumptions about the configuration file:
31
32        1. It is a plain text file.
33
34        2. Lines that begin with a single '#' character are comments that
35           contain a description of the following configuration setting.
36
37        3. Lines that do not begin with the '#' character contain the
38           configuration setting described by the previous comment lines.
39
40        4. Configuration settings are self contained, and completely
41           independent, changing one configuration setting never requires that
42           another, different, configuration setting must be changed too
43           (perhaps any logical conflicts are automatically resolved by the
44           application in a safe, fallback, manner)
45
46       The additional information used by sysconftool is encoded as
47       specially-formatted comment lines that begin with two '#' characters.
48

FILENAMES

50       An application installs a default configuration file as
51       "filename.dist", when the actual name of the configuration file is
52       really "filename". If there is no existing filename, sysconftool simply
53       copies filename.dist to filename, and calls it a day. Otherwise,
54       sysconftool copies the existing filename to filename.bak and creates a
55       new filename based on the contents of both files.
56
57       sysconftool is designed to solve a common problem with application
58       configuration. New versions of applications often include additional
59       functionality that requires new configuration settings. Without the new
60       configuration settings the application will not work, so new
61       configuration files should be installed during the upgrade. However,
62       when that happens, any changes to the existing configuration settings
63       are lost.  sysconftool is designed to solve this dillemma, and merge
64       old configuration settings with new ones.  sysconftool is designed in a
65       fail-safe way. Whenever there's a doubt as to what's The Right Thing To
66       Do, sysconftool will use the configuration settings from the new file,
67       that are supposedly known to be good, and leave it up to a physical
68       being to sort out any conflicts and make any manual decisions.
69

FILE VERSIONING

71       The following line should appear at the beginning of filename.dist:
72
73              ##VERSION: version
74
75       This doesn't have to be the very first line in filename.dist, but it
76       should appear somewhere within the first twenty lines, right before the
77       first configuration setting. "version" should be some kind of an
78       identifier for this particular version of the configuration files. All
79       that sysconftool cares about is that any change to the default
80       configuration, in filename.dist, results in a different version. An
81       excellent way to do this is to simply use the $Id$ RCS/CVS version
82       identification strings, and have this little detail taken care of
83       automatically.
84
85       New revisions of an application should not necessarily have a new
86       configuration file version. If the default application configuration
87       settings have not changed from the previous release, version can remain
88       the same.  version is copied from filename.dist to filename.
89
90       If there's an existing filename, and it includes the same version
91       identifier, sysconftool silently skips over this configuration file,
92       and doesn't do anything, assuming that this configuration file has
93       already been installed. Therefore, running sysconftool more than once
94       (accidentally) will not break anything.
95
96       If there's an existing filename, but it's version is different,
97       sysconftool backs it up to filename.bak, then creates a new filename.
98       If there's an existing filename, but it doesn't contain a recognizable
99       "##VERSION: version" line, sysconftool assumes that the previous
100       version of the application did not use the sysconftool tool. That's not
101       a problem.  filename is copied to filename.bak, and filename.dist gets
102       installed as the new filename, allowing sysconftool to work with the
103       next version of this configuration file.
104

CONFIGURATION SETTING VERSIONING

106       Each configuration setting uses the following format in the
107       configuration file:
108
109              ##NAME: name:revision
110              #
111              # description
112
113              setting
114
115       sysconftool looks for a line that begins with "##NAME". This line gives
116       the name and the revision of the following setting.  name must be
117       unique within its configuration file (the same name can be used by
118       different configuration files, sysconftool works with one file at a
119       time).  revision is used by sysconftool to decide when the
120       configuration setting can be safely carried over from an older
121       configuration file, and when it is better to reinstall the default
122       setting from the new configuration file.
123
124       One or more comment lines - lines that begin with the '#' character -
125       may follow "##NAME". The first line that does not begin with '#' is
126       considered to be the first line that contains the value of the
127       configuration setting, which lasts. The value can be spread over
128       multiple lines. The configuration setting is considered to last until
129       either the end of the file, or until the first following line that
130       begins with another "##NAME".
131
132       Aside from that, sysconftool does not care how the configuration
133       setting is represented. It can be "NAME=VALUE", it can be "NAME:
134       VALUE", or "NAME<tab>VALUE", it can even be a base64-encoded binary
135       object, and it can always have leading or trailing blank lines.
136       sysconftool merely looks at which lines begin with the '#' comment
137       character. After the '##NAME:' line, sysconftool looks ahead until the
138       first line that does not begin with '#', and that's the first line of
139       the configuration setting. Then, sysconftool looks ahead until the next
140       line that starts with a "##NAME:", which marks the end of this
141       configuration setting.
142
143       For this reason it is important that all commented description lines
144       that follow '##NAME:' must begin with the '#' character. If a blank
145       line follows the line with '##NAME:' it is assumed to be the start of
146       the corresponding configuration setting. For example, this is correct:
147
148              ##NAME: flag1:0
149              #
150              #
151              # This is the first configuration flag
152              #
153
154              flag1=1
155
156       This is not correct:
157
158              ##NAME: flag1:0
159
160              #
161              # This is the first configuration flag
162              #
163
164              flag1=1
165

CONFIGURATION FILE CREATION

167       A new configuration file, "filename", is created from its previous
168       version, "filename.bak" and the new default configuration file,
169       "filename.dist", using the following, simple, two-step process.
170
171        1. sysconftool begins with filename.dist in hand. This makes sure that
172           sysconftool begins with a good, known, default configuration file.
173
174        2. sysconftool then takes each configuration setting in filename.dist,
175           then searches filename.bak. If it finds a configuration setting
176           that has an identical "name" and "version", then the corresponding
177           configuration setting value is taken from filename.bak, replacing
178           the default in filename.dist. After all configuration settings in
179           filename.dist are looked up (and potentially replaced), what's left
180           becomes the new filename.
181

THE END RESULT

183       The above process is a logical description. The actual technical
184       implementation is slightly different (for example, filename is not
185       backed up to filename.bak until the new configuration file has been
186       already created), but is logically equivalent to this process. This
187       process carries a number of consequences that must be considered.
188
189       If a new application revision needs a new configuration setting, it
190       will get a new name and version. Since filename.dist is used as a
191       starting point for the new configuration file, the new configuration
192       file will include the new configuration setting. When a configuration
193       setting is removed, it will disappear from the new configuration file
194       for the same exact reason.
195

CONFIGURATION SETTING VERSION

197       sysconftool looks at both name and version. A configuration setting
198       with the same name but different versions are seen by sysconftool as
199       completely different settings. The existence of version allows a
200       finer-grained control of configuration upgrades, as described below.
201
202       sysconftool copies setting values with the same name and version from
203       the old configuration file to the new configuration file. However, the
204       associated descriptive comments are not copied, and are taken from the
205       new filename.dist. Therefore, if a new version of the configuration
206       file contains an updated or an embellished description of a particular
207       setting, it will be included in the new configuration file, but the
208       existing configuration value will be preserved! Generally, if a
209       configuration setting does not change its meaning or function, its name
210       and version should remain the same. Its comments can be edited to fix a
211       typo, or revised in a more substantive fashion.  Name and version
212       should only be changed if there's a functional change in the
213       configuration setting.
214
215       What to do with name and version after a functional change depends on
216       the nature and the magnitude of the change. The nature and the
217       magnitude of the change must be considered not only with respect to the
218       most recent revision of the application, but to all the previous
219       revisions as well. When in doubt, go based upon the largest change in
220       magnitude, in order to guarantee a functional default setting, from
221       filename.dist, and leave it up to a living being to manually figure it
222       out.
223
224       If only the default value of a setting should be changed for new
225       application installation, but the existing installations can continue
226       to use the existing value of the setting, both the name and version
227       should be left alone. Existing configuration settings will be
228       preserved, and new installations will get the new default. The
229       descriptive comment of this setting can be updated too (see above).
230
231       This should be done only as long as ALL previous values of this
232       configuration setting will ALWAYS be valid in the new application
233       revision. If some possible values of this configuration setting will no
234       longer be valid, version should be changed.  sysconftool does not care
235       how name and version are formatted. Both are opaque labels. The only
236       requirements is for the label to be different. The difference between
237       changing version and changing both name and version is this:
238
239       If there's an old configuration setting with the same name but
240       different version, sysconftool will still use the new, safe, default
241       value from filename.dist, however sysconftool will also append an
242       additional comment, on its own accord, reminding the reader that this
243       configuration value has been reset, and the reader should consider
244       whether to manually restore the configuration value from the old
245       configuration.
246

MISCELLANEA

248       When sysconftool decides to keep an existing setting, with the same
249       name and value, it will also insert a short comment to that effect,
250       reminding the reader to check the default in filename.dist.
251

SEE ALSO

253       sysconftool(1)[1].
254

AUTHORS

256       Double Precision, Inc.
257

NOTES

259        1. sysconftool(1)
260           [set $man.base.url.for.relative.links]/sysconftool.1.html
261
262
263
264Courier Mail Server               08/25/2013                    SYSCONFTOOL(7)
Impressum