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
|
<?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 Vsnapshot"/><link rel="home" href="#sysconftool.1" 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 S. Varshavchik. See COPYING for distribution
information.
--></head><body><div class="refentry"><a id="sysconftool.1" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>sysconftool, sysconftoolize — install configuration files</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">sysconftool</code> [options] [filename.dist...]</p></div><div class="cmdsynopsis"><p><code class="command">sysconftoolize</code> </p></div></div><div class="refsect1"><a id="sysconftool_DESCRIPTION" shape="rect"> </a><h2>DESCRIPTION</h2><p>
<span class="command"><strong>sysconftool</strong></span> is a development utility that helps to install
application configuration files. <span class="command"><strong>sysconftool</strong></span> allows an
existing
application to be upgraded without losing the older version's configuration
settings.</p><p>
A new version of an application often introduces new configuration
settings. Sometimes obsolete configuration settings are removed. Existing
configuration settings may also now have additional options, or certain
options are no longer valid any more. Because of this, an application upgrade
usually installs a fresh set of configuration files, containing a default
configuration that's known to work. Keeping the existing files carries the
risk of the application failing to function properly due to a configuration
that is no longer valid.</p><p>
A typical application installation script copies over configuration files
with default settings. Existing configuration files are backed up or
overwritten. With <span class="command"><strong>sysconftool</strong></span>, an application will install a
configuration file names <code class="filename">filename.dist</code>, instead of
<code class="filename">filename</code>.
Then, the application's installation script runs
<span class="command"><strong>sysconftool</strong></span>.
<span class="command"><strong>sysconftool</strong></span> copies <code class="filename">filename.dist</code> to
<code class="filename">filename</code>, but
also checks if <code class="filename">filename</code> from an older version of the
application
already exist. If <code class="filename">filename</code> an older
<span class="command"><strong>sysconftool</strong></span>-installed
configuration file, its configuration settings replace the defaults in
<code class="filename">filename.dist</code>, which is then subsequently installed
as <code class="filename">filename</code>.
<span class="command"><strong>sysconftool</strong></span> is smart enough to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Remove configuration settings that no longer exist.</p></li><li class="listitem"><p>
Add new configuration settings.</p></li><li class="listitem"><p>
Do not preserve an
older configuration setting if there's a possibility that it is no longer
valid in the new version of the application.</p></li></ul></div><p>
</p><p>
<span class="command"><strong>sysconftool</strong></span> produces a short report when it runs. The report
lists every configuration setting in
<code class="filename">$filename.dist</code>, and its disposition.
The possible dispositions are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">new</code></span></dt><dd><p>
This a new configuration setting that wasn't
found in the existing <code class="filename">$filename</code>.</p></dd><dt><span class="term"><code class="literal">unchanged</code></span></dt><dd><p>
This setting's value was taken
from the existing <code class="filename">$filename</code>,
replacing the default value provided by
<code class="filename">$filename.dist</code>.</p></dd><dt><span class="term"><code class="literal">UPDATED</code></span></dt><dd><p>
This setting has been previously set in <code class="filename">$filename</code>,
but the setting's value may no longer be valid in the new version of the
application, so its default value is taken from
<code class="filename">$filename.dist</code>, and it may
need to be manually adjusted.</p></dd></dl></div><p>
All this logic is based on some additional metadata that must be included
in each configuration file, that <span class="command"><strong>sysconftool</strong></span> reads.
For this to work, both the old and the new version of the
application must be <span class="command"><strong>sysconftool</strong></span>-ized.
<span class="command"><strong>sysconftool</strong></span>
operates in a fail-safe mode. If the old version did not use
<span class="command"><strong>sysconftool</strong></span>, <code class="filename">$filename</code> is backed up to
<code class="filename">$filename.bak</code>, and <code class="filename">$filename</code> is
copied to <code class="filename">$filename</code>. This
is what would essentially happen anyway without <span class="command"><strong>sysconftool</strong></span>.
The local configuration needs to be reentered into
<code class="filename">$filename</code>, so
nothing is lost. However, the next upgrade will see
<span class="command"><strong>sysconftool</strong></span> do its job.</p></div><div class="refsect1"><a id="sysconftool_ADD" shape="rect"> </a><h2>ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION</h2><p>
<span class="command"><strong>sysconftool</strong></span> requires the application to use
<span class="command"><strong>autoconf</strong></span> and <span class="command"><strong>automake</strong></span>. The first step
is to run the
<span class="command"><strong>sysconftoolize</strong></span> script from the application's source
directory.
<span class="command"><strong>sysconftoolize</strong></span> creates a symbolic link to the
<span class="command"><strong>sysconftool</strong></span>
script from the
current directory, and appends a default <code class="literal">install-configure</code>
rule to
<code class="filename">Makefile.am</code>. <span class="command"><strong>sysconftoolize</strong></span> with the
<code class="option">--copy</code> option copies the script, instead of creating a
symbolic link.
</p><p>
After running
<span class="command"><strong>sysconftoolize</strong></span> the macro
<code class="literal">AC_PROG_SYSCONFTOOL</code> must be manually added to
<code class="filename">configure.ac</code>, and <code class="filename">Makefile.am</code> must be modified as
follows.</p><p>
<code class="filename">Makefile.am</code> must be modified to install configuration
files as
<code class="filename">filename.dist</code> instead of
<code class="filename">filename</code>. The default
<code class="literal">install-configure</code> rule assumes that
<code class="literal">sysconf_DATA</code> lists all
configuration files in
<code class="filename">sysconfdir</code>, and runs <span class="command"><strong>sysconftool</strong></span> on
them.
This will usually have to be modified, according to the application's
individual needs. Finally, <code class="filename">Makefile.am</code> must be modified to
distribute the <span class="command"><strong>sysconftool</strong></span> script in the application's
source
distribution. Adding <span class="command"><strong>sysconftool</strong></span> to
<code class="literal">EXTRA_DIST</code> is what's needed in most cases.</p><p>
Finally, certain <span class="command"><strong>sysconftool</strong></span> magic incantations must be
added to the application's configuration files, see <a class="ulink" href="sysconftool.7.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">sysconftool</span>(7)</span></a> for more information. The last
step involves updating the application's
<code class="filename">INSTALL</code> instructions, so that the
application can be properly installed. The following instructions must be
added to <code class="filename">INSTALL</code>:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Run "make install-configure" after "make install".</p></li><li class="listitem"><p>
If this is the first <span class="command"><strong>sysconftool</strong></span>-ized version, DO NOT
simply copy over the old configuration files, and overwrite the new
configuration files. Instead, manually edit each configuration file, and
manually reset each configuration setting. This is because the new
configuration files include the magic code for <span class="command"><strong>sysconftool</strong></span>, which
would be lost when the configuration file is overwritten.</p></li><li class="listitem"><p>
If this is not the first <span class="command"><strong>sysconftool</strong></span>-ized version, the
output of <span class="command"><strong>make install-configure</strong></span> must be reviewed in
order to
manually adjust or tweak what <span class="command"><strong>sysconftool</strong></span> did. Many large
configuration files can result in lots of output, so the output of
<span class="command"><strong>make
install-configure</strong></span> should be saved into a file, and reviewed.</p></li></ol></div></div><div class="refsect1"><a id="sysconftool_SEEALSO" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="sysconftoolcheck.1.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">sysconftoolcheck</span>(1)</span></a>,
<a class="ulink" href="sysconftool.7.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">sysconftool</span>(7)</span></a>.</p></div></div></body></html>
|
