1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>sysconftool</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#sysconftool.7" title="sysconftool"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
information.
--></head><body><div class="refentry"><a id="sysconftool.7" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>sysconftool — format of configuration files installed by sysconftool</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="informalexample"><pre class="programlisting" xml:space="preserve">
#
##VERSION: $Id$
##NAME: configname1:configname1version
#
# Description
SETTING1=VALUE1
##NAME: configname2:configname2version
#
# Description
SETTING2=VALUE2
...</pre></div></div><div class="refsect1"><a id="idm247867528848" shape="rect"> </a><h2>DESCRIPTION</h2><p>
This manual page describes the format of configuration files installed by
<a class="ulink" href="sysconftool.1.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">sysconftool</span>(1)</span></a>.
This format is flexible enough to accomodate any
kind of application configuration file format.
<span class="command"><strong>sysconftool</strong></span> makes
four assumptions about the configuration file:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>It is a plain text file.</p></li><li class="listitem"><p>Lines that begin with a single '#' character are comments that
contain a description of the following configuration setting.</p></li><li class="listitem"><p>
Lines that do not begin with the '#' character contain the configuration
setting described by the previous comment lines.</p></li><li class="listitem"><p>
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)</p></li></ol></div><p>
The additional information used by <span class="command"><strong>sysconftool</strong></span> is encoded as
specially-formatted comment lines that begin with two '#' characters.</p></div><div class="refsect1"><a id="idm247870124096" shape="rect"> </a><h2>FILENAMES</h2><p>
An application installs a default configuration file as
"<code class="filename">filename.dist</code>", when the actual name of the
configuration file is
really "<code class="filename">filename</code>". If there is no existing
<code class="filename">filename</code>,
<span class="command"><strong>sysconftool</strong></span> simply copies
<code class="filename">filename.dist</code> to
<code class="filename">filename</code>, and calls it a day. Otherwise,
<span class="command"><strong>sysconftool</strong></span>
copies the existing <code class="filename">filename</code> to <code class="filename">filename.bak</code> and creates a new
<code class="filename">filename</code> based on the contents of both files.</p><p>
<span class="command"><strong>sysconftool</strong></span> 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.
<span class="command"><strong>sysconftool</strong></span> is designed to solve this dillemma, and
merge old
configuration settings with new ones. <span class="command"><strong>sysconftool</strong></span>
is designed in
a fail-safe way. Whenever there's a doubt as to what's The Right Thing To
Do, <span class="command"><strong>sysconftool</strong></span> 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.</p></div><div class="refsect1"><a id="idm247870001104" shape="rect"> </a><h2>FILE VERSIONING</h2><p>
The following line should appear at the beginning of
<code class="filename">filename.dist</code>:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
##VERSION: <em class="replaceable"><code>version</code></em>
</pre></div><p>
This doesn't have to be the very first line in
<code class="filename">filename.dist</code>, but it
should appear somewhere within the first twenty lines, right before the first
configuration setting. "<code class="filename">version</code>" should be some kind
of an identifier
for this particular version of the configuration files. All that
<span class="command"><strong>sysconftool</strong></span> cares about is that any change to the default
configuration, in <code class="filename">filename.dist</code>, results in a different
<em class="replaceable"><code>version</code></em>.
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.</p><p>
New revisions of an application should not necessarily have a new
configuration file <em class="replaceable"><code>version</code></em>. If the default
application configuration
settings have not changed from the previous release,
<em class="replaceable"><code>version</code></em> can remain
the same. <em class="replaceable"><code>version</code></em> is copied from
<code class="filename">filename.dist</code> to
<code class="filename">filename</code>.</p><p>
If there's an existing <code class="filename">filename</code>, and it
includes the same
<em class="replaceable"><code>version</code></em> identifier, <span class="command"><strong>sysconftool</strong></span>
silently skips over this
configuration file, and doesn't do anything, assuming that this configuration
file has already been installed. Therefore,
running <span class="command"><strong>sysconftool</strong></span>
more than once (accidentally) will not break anything.</p><p>
If there's an existing <code class="filename">filename</code>, but it's
<em class="replaceable"><code>version</code></em> is
different, <span class="command"><strong>sysconftool</strong></span> backs it up to
<code class="filename">filename.bak</code>, then
creates a new <code class="filename">filename</code>.
If there's
an existing <code class="filename">filename</code>, but it doesn't contain a
recognizable "##VERSION:
<em class="replaceable"><code>version</code></em>" line, <span class="command"><strong>sysconftool</strong></span>
assumes that the previous
version of the application did not use the <span class="command"><strong>sysconftool</strong></span> tool.
That's not a problem. <code class="filename">filename</code> is copied
to <code class="filename">filename.bak</code>, and
<code class="filename">filename.dist</code> gets installed as the new
<code class="filename">filename</code>, allowing
<span class="command"><strong>sysconftool</strong></span> to work with the next version
of this configuration file.</p></div><div class="refsect1"><a id="idm247870177472" shape="rect"> </a><h2>CONFIGURATION SETTING VERSIONING</h2><p>
Each configuration setting uses the following format in the configuration
file:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
##NAME: <em class="replaceable"><code>name</code></em>:<em class="replaceable"><code>revision</code></em>
#
# <em class="replaceable"><code>description</code></em>
<em class="replaceable"><code>setting</code></em>
</pre></div><p>
<span class="command"><strong>sysconftool</strong></span>
looks for a line that begins with "<code class="literal">##NAME</code>". This line
gives the name and the revision of the following setting.
<em class="replaceable"><code>name</code></em> must be
unique within its configuration file (the same
<em class="replaceable"><code>name</code></em> can be used by
different configuration files, <span class="command"><strong>sysconftool</strong></span> works with
one file at
a time). <em class="replaceable"><code>revision</code></em> is used by
<span class="command"><strong>sysconftool</strong></span> 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.</p><p>
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 "<code class="literal">##NAME</code>".</p><p>
Aside from that, <span class="command"><strong>sysconftool</strong></span> does not care how the
configuration setting is represented. It can be
"<code class="literal">NAME=VALUE</code>", it can be
"<code class="literal">NAME: VALUE</code>",
or "<code class="literal">NAME<tab>VALUE</code>", it can even be a base64-encoded
binary object, and it can always have leading or trailing blank lines.
<span class="command"><strong>sysconftool</strong></span> merely looks at which lines begin with the '#'
comment character. After the
'<code class="literal">##NAME:</code>' line, <span class="command"><strong>sysconftool</strong></span> looks
ahead until the first line that does not begin with '#', and that's the first
line of the configuration setting.
Then, <span class="command"><strong>sysconftool</strong></span> looks ahead
until the next line that starts with a
"<code class="literal">##NAME:</code>", which marks the end of this
configuration setting.</p><p>
For this reason it is important that all commented description lines that
follow '<code class="literal">##NAME:</code>' must begin with the '#' character.
If a blank line follows
the line with '<code class="literal">##NAME:</code>' it is assumed to be the start of
the corresponding
configuration setting. For example, this is correct:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
##NAME: flag1:0
#
#
# This is the first configuration flag
#
flag1=1
</pre></div><p>This is not correct:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
##NAME: flag1:0
#
# This is the first configuration flag
#
flag1=1
</pre></div></div><div class="refsect1"><a id="idm247870155440" shape="rect"> </a><h2>CONFIGURATION FILE CREATION</h2><p>
A new configuration file, "<code class="filename">filename</code>", is created
from its previous
version, "<code class="filename">filename.bak</code>" and the new default
configuration file,
"<code class="filename">filename.dist</code>", using the following, simple, two-step
process.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
<span class="command"><strong>sysconftool</strong></span> begins with <code class="filename">filename.dist</code>
in hand. This
makes sure that <span class="command"><strong>sysconftool</strong></span> begins with a good, known,
default configuration file.</p></li><li class="listitem"><p>
<span class="command"><strong>sysconftool</strong></span> then takes each configuration setting in
<code class="filename">filename.dist</code>, then searches
<code class="filename">filename.bak</code>. If it finds a
configuration setting that has an identical
"<em class="replaceable"><code>name</code></em>" and
"<em class="replaceable"><code>version</code></em>", then the corresponding configuration
setting value is taken
from <code class="filename">filename.bak</code>, replacing the default in
<code class="filename">filename.dist</code>. After
all configuration settings in <code class="filename">filename.dist</code> are
looked up (and
potentially replaced), what's left becomes the new
<code class="filename">filename</code>.</p></li></ol></div></div><div class="refsect1"><a id="idm247864805568" shape="rect"> </a><h2>THE END RESULT</h2><p>
The above process is a logical description. The actual technical
implementation is slightly different (for example,
<code class="filename">filename</code> is not
backed up to <code class="filename">filename.bak</code> 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.</p><p>
If a new application revision needs a new configuration setting, it will
get a new <em class="replaceable"><code>name</code></em> and <em class="replaceable"><code>version</code></em>. Since <code class="filename">filename.dist</code> 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.</p></div><div class="refsect1"><a id="idm247864800704" shape="rect"> </a><h2>CONFIGURATION SETTING VERSION</h2><p>
<span class="command"><strong>sysconftool</strong></span> looks at both <em class="replaceable"><code>name</code></em>
and <em class="replaceable"><code>version</code></em>. A
configuration setting with the same <em class="replaceable"><code>name</code></em> but
different <em class="replaceable"><code>version</code></em>s
are seen by <span class="command"><strong>sysconftool</strong></span> as completely different settings.
The
existence of <em class="replaceable"><code>version</code></em> allows a finer-grained control of configuration
upgrades, as described below.</p><p>
<span class="command"><strong>sysconftool</strong></span> copies setting values with the same
<em class="replaceable"><code>name</code></em>
and <em class="replaceable"><code>version</code></em> from the old configuration file to the
new configuration
file. However, the associated descriptive comments are not copied, and are
taken from the new <code class="filename">filename.dist</code>. 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
<em class="replaceable"><code>name</code></em> and
<em class="replaceable"><code>version</code></em> should remain the same. Its comments can
be edited to fix a
typo, or revised in a more substantive fashion.
<em class="replaceable"><code>Name</code></em> and <em class="replaceable"><code>version</code></em>
should only be changed if there's a functional change in the configuration
setting.</p><p>
What to do with <em class="replaceable"><code>name</code></em> and
<em class="replaceable"><code>version</code></em> 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
<code class="filename">filename.dist</code>, and leave
it up to a living being to manually figure it out.</p><p>
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 <em class="replaceable"><code>name</code></em> and <em class="replaceable"><code>version</code></em>
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).</p><p>
This should be done only as long as <span class="emphasis"><em>ALL</em></span>
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,
<em class="replaceable"><code>version</code></em> should be changed.
<span class="command"><strong>sysconftool</strong></span> does not care how
<em class="replaceable"><code>name</code></em> and <em class="replaceable"><code>version</code></em> are
formatted. Both are opaque labels. The
only requirements is for the label to be different. The difference between
changing <em class="replaceable"><code>version</code></em> and changing both
<em class="replaceable"><code>name</code></em> and <em class="replaceable"><code>version</code></em> is
this:</p><p>
If there's an old configuration setting with the same
<em class="replaceable"><code>name</code></em> but different
<em class="replaceable"><code>version</code></em>, <span class="command"><strong>sysconftool</strong></span> will
still use the new,
safe, default value from <code class="filename">filename.dist</code>, however
<span class="command"><strong>sysconftool</strong></span> 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.</p></div><div class="refsect1"><a id="idm247864780560" shape="rect"> </a><h2>MISCELLANEA</h2><p>
When <span class="command"><strong>sysconftool</strong></span> decides to keep an existing setting,
with the
same <em class="replaceable"><code>name</code></em> and <em class="replaceable"><code>value</code></em>,
it will also insert a short comment to that
effect, reminding the reader to check the default in
<code class="filename">filename.dist</code>.</p></div><div class="refsect1"><a id="idm247864777280" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="sysconftool.1.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">sysconftool</span>(1)</span></a>.</p></div></div></body></html>
|
