1SYSCONFTOOL(7) SYSCONFTOOL(7)
2
6 sysconftool - format of configuration files installed by sysconftool
7
9 #
10 ##VERSION: $Id$
11 ##NAME: configname1:configname1version
13 #
14 # Description
15 SETTING1=VALUE1
17 ##NAME: configname2:configname2version
19 #
20 # Description
21 SETTING2=VALUE2
23 ...
25
27 This manual page describes the format of configuration files installed
28 by sysconftool(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 1. It is a plain text file.
33 2. Lines that begin with a single '#' character are comments that con‐
35 tain a description of the following configuration setting.
36 3. Lines that do not begin with the '#' character contain the configu‐
38 ration setting described by the previous comment lines.
39 4. Configuration settings are self contained, and completely indepen‐
41 dent, changing one configuration setting never requires that
42 another, different, configuration setting must be changed too (per‐
43 haps any logical conflicts are automatically resolved by the appli‐
44 cation in a safe, fallback, manner)
45 The additional information used by sysconftool is encoded as specially-
47 formatted comment lines that begin with two '#' characters.
48
50 An application installs a default configuration file as "file‐
51 name.dist", when the actual name of the configuration file is really
52 "filename". If there is no existing filename, sysconftool simply copies
53 filename.dist to filename, and calls it a day. Otherwise, sysconftool
54 copies the existing filename to filename.bak and creates a new filename
55 based on the contents of both files.
56 sysconftool is designed to solve a common problem with application con‐
58 figuration. 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 configura‐
61 tion files should be installed during the upgrade. However, when that
62 happens, any changes to the existing configuration settings are lost.
63 sysconftool is designed to solve this dillemma, and merge old configu‐
64 ration settings with new ones. sysconftool is designed in a fail-safe
65 way. Whenever there's a doubt as to what's The Right Thing To Do,
66 sysconftool will use the configuration settings from the new file, that
67 are supposedly known to be good, and leave it up to a physical being to
68 sort out any conflicts and make any manual decisions.
69
71 The following line should appear at the beginning of filename.dist:
72 ##VERSION: version
74 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 iden‐
78 tifier for this particular version of the configuration files. All that
79 sysconftool cares about is that any change to the default configura‐
80 tion, in filename.dist, results in a different version. An excellent
81 way to do this is to simply use the $Id$ RCS/CVS version identification
82 strings, and have this little detail taken care of automatically.
83 New revisions of an application should not necessarily have a new con‐
85 figuration file version. If the default application configuration set‐
86 tings have not changed from the previous release, version can remain
87 the same. version is copied from filename.dist to filename.
88 If there's an existing filename, and it includes the same version iden‐
90 tifier, sysconftool silently skips over this configuration file, and
91 doesn't do anything, assuming that this configuration file has already
92 been installed. Therefore, running sysconftool more than once (acci‐
93 dentally) will not break anything.
94 If there's an existing filename, but it's version is different, syscon‐
96 ftool backs it up to filename.bak, then creates a new filename. If
97 there's an existing filename, but it doesn't contain a recognizable
98 "##VERSION: version" line, sysconftool assumes that the previous ver‐
99 sion of the application did not use the sysconftool tool. That's not a
100 problem. filename is copied to filename.bak, and filename.dist gets
101 installed as the new filename, allowing sysconftool to work with the
102 next version of this configuration file.
103
105 Each configuration setting uses the following format in the configura‐
106 tion file:
107 ##NAME: name:revision
109 #
110 # description
111 setting
113 sysconftool looks for a line that begins with "##NAME". This line gives
115 the name and the revision of the following setting. name must be
116 unique within its configuration file (the same name can be used by dif‐
117 ferent configuration files, sysconftool works with one file at a time).
118 revision is used by sysconftool to decide when the configuration set‐
119 ting can be safely carried over from an older configuration file, and
120 when it is better to reinstall the default setting from the new config‐
121 uration file.
122 One or more comment lines - lines that begin with the '#' character -
124 may follow "##NAME". The first line that does not begin with '#' is
125 considered to be the first line that contains the value of the configu‐
126 ration setting, which lasts. The value can be spread over multiple
127 lines. The configuration setting is considered to last until either
128 the end of the file, or until the first following line that begins with
129 another "##NAME".
130 Aside from that, sysconftool does not care how the configuration set‐
132 ting is represented. It can be "NAME=VALUE", it can be "NAME: VALUE",
133 or "NAME<tab>VALUE", it can even be a base64-encoded binary object, and
134 it can always have leading or trailing blank lines. sysconftool merely
135 looks at which lines begin with the '#' comment character. After the
136 '##NAME:' line, sysconftool looks ahead until the first line that does
137 not begin with '#', and that's the first line of the configuration set‐
138 ting. Then, sysconftool looks ahead until the next line that starts
139 with a "##NAME:", which marks the end of this configuration setting.
140 For this reason it is important that all commented description lines
142 that follow '##NAME:' must begin with the '#' character. If a blank
143 line follows the line with '##NAME:' it is assumed to be the start of
144 the corresponding configuration setting. For example, this is correct:
145 ##NAME: flag1:0
147 #
148 #
149 # This is the first configuration flag
150 #
151 flag1=1
153 This is not correct:
155 ##NAME: flag1:0
157 #
159 # This is the first configuration flag
160 #
161 flag1=1
163
165 A new configuration file, "filename", is created from its previous ver‐
166 sion, "filename.bak" and the new default configuration file, "file‐
167 name.dist", using the following, simple, two-step process.
168 1. sysconftool begins with filename.dist in hand. This makes sure that
170 sysconftool begins with a good, known, default configuration file.
171 2. sysconftool then takes each configuration setting in filename.dist,
173 then searches filename.bak. If it finds a configuration setting
174 that has an identical "name" and "version", then the corresponding
175 configuration setting value is taken from filename.bak, replacing
176 the default in filename.dist. After all configuration settings in
177 filename.dist are looked up (and potentially replaced), what's left
178 becomes the new filename.
179
181 The above process is a logical description. The actual technical
182 implementation is slightly different (for example, filename is not
183 backed up to filename.bak until the new configuration file has been
184 already created), but is logically equivalent to this process. This
185 process carries a number of consequences that must be considered.
186 If a new application revision needs a new configuration setting, it
188 will get a new name and version. Since filename.dist is used as a
189 starting point for the new configuration file, the new configuration
190 file will include the new configuration setting. When a configuration
191 setting is removed, it will disappear from the new configuration file
192 for the same exact reason.
193
195 sysconftool looks at both name and version. A configuration setting
196 with the same name but different versions are seen by sysconftool as
197 completely different settings. The existence of version allows a
198 finer-grained control of configuration upgrades, as described below.
199 sysconftool copies setting values with the same name and version from
201 the old configuration file to the new configuration file. However, the
202 associated descriptive comments are not copied, and are taken from the
203 new filename.dist. Therefore, if a new version of the configuration
204 file contains an updated or an embellished description of a particular
205 setting, it will be included in the new configuration file, but the
206 existing configuration value will be preserved! Generally, if a con‐
207 figuration setting does not change its meaning or function, its name
208 and version should remain the same. Its comments can be edited to fix a
209 typo, or revised in a more substantive fashion. Name and version
210 should only be changed if there's a functional change in the configura‐
211 tion setting.
212 What to do with name and version after a functional change depends on
214 the nature and the magnitude of the change. The nature and the magni‐
215 tude of the change must be considered not only with respect to the most
216 recent revision of the application, but to all the previous revisions
217 as well. When in doubt, go based upon the largest change in magnitude,
218 in order to guarantee a functional default setting, from filename.dist,
219 and leave it up to a living being to manually figure it out.
220 If only the default value of a setting should be changed for new appli‐
222 cation installation, but the existing installations can continue to use
223 the existing value of the setting, both the name and version should be
224 left alone. Existing configuration settings will be preserved, and new
225 installations will get the new default. The descriptive comment of
226 this setting can be updated too (see above).
227 This should be done only as long as ALL previous values of this config‐
229 uration setting will ALWAYS be valid in the new application revision.
230 If some possible values of this configuration setting will no longer be
231 valid, version should be changed. sysconftool does not care how name
232 and version are formatted. Both are opaque labels. The only require‐
233 ments is for the label to be different. The difference between chang‐
234 ing version and changing both name and version is this:
235 If there's an old configuration setting with the same name but differ‐
237 ent version, sysconftool will still use the new, safe, default value
238 from filename.dist, however sysconftool will also append an additional
239 comment, on its own accord, reminding the reader that this configura‐
240 tion value has been reset, and the reader should consider whether to
241 manually restore the configuration value from the old configuration.
242
244 When sysconftool decides to keep an existing setting, with the same
245 name and value, it will also insert a short comment to that effect,
246 reminding the reader to check the default in filename.dist.
247
249 sysconftool(1).
250Double Precision, Inc. 16 July 2005 SYSCONFTOOL(7)