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

NAME

6       sysconftool - install configuration files
7

SYNOPSIS

9       sysconftool [options] [filename.dist...]
10

DESCRIPTION

12       sysconftool is a development utility that helps to install application
13       configuration files.  sysconftool allows an existing application to be
14       upgraded without losing the older version's configuration settings.
15
16       A new version of an application often introduces new configuration
17       settings. Sometimes obsolete configuration settings are removed.
18       Existing configuration settings may also now have additional options,
19       or certain options are no longer valid any more. Because of this, an
20       application upgrade usually installs a fresh set of configuration
21       files, containing a default configuration that's known to work. Keeping
22       the existing files carries the risk of the application failing to
23       function properly due to a configuration that is no longer valid.
24
25       A typical application installation script copies over configuration
26       files with default settings. Existing configuration files are backed up
27       or overwritten. With sysconftool, an application will install a
28       configuration file names filename.dist, instead of filename. Then, the
29       application's installation script runs sysconftool.  sysconftool copies
30       filename.dist to filename, but also checks if filename from an older
31       version of the application already exist. If filename an older
32       sysconftool-installed configuration file, it's configuration settings
33       replace the defaults in filename.dist, which is then subsequently
34       installed as filename.  sysconftool is smart enough to:
35
36       •   Remove configuration settings that no longer exist.
37
38       •   Add new configuration settings.
39
40       •   Do not preserve an older configuration setting if there's a
41           possibility that it is no longer valid in the new version of the
42           application.
43
44       sysconftool produces a short report when it runs. The report lists
45       every configuration setting in $filename.dist, and its disposition. The
46       possible dispositions are:
47
48       new
49           This a new configuration setting that wasn't found in the existing
50           $filename.
51
52       unchanged
53           This setting's value was taken from the existing $filename,
54           replacing the default value provided by $filename.dist.
55
56       UPDATED
57           This setting has been previously set in $filename, but the
58           setting's value may no longer be valid in the new version of the
59           application, so its default value is taken from $filename.dist, and
60           it may need to be manually adjusted.
61
62       All this logic is based on some additional metadata that must be
63       included in each configuration file, that sysconftool reads. For this
64       to work, both the old and the new version of the application must be
65       sysconftool-ized.  sysconftool operates in a fail-safe mode. If the old
66       version did not use sysconftool, $filename is backed up to
67       $filename.bak, and $filename is copied to $filename. This is what would
68       essentially happen anyway without sysconftool. The local configuration
69       needs to be reentered into $filename, so nothing is lost. However, the
70       next upgrade will see sysconftool do its job.
71

ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION

73       sysconftool requires the application to use autoconf and automake. The
74       first step is to run the sysconftoolize script from the application's
75       source directory.  sysconftoolize creates a symbolic link to the
76       sysconftool script from the current directory, and appends a default
77       install-configure rule to Makefile.am.  sysconftoolize with the --copy
78       option copies the script, instead of creating a symbolic link.
79
80       After running sysconftoolize the macro AC_PROG_SYSCONFTOOL must be
81       manually added to configure.in, and Makefile.am must be modified as
82       follows.
83
84       Makefile.am must be modified to install configuration files as
85       filename.dist instead of filename. The default install-configure rule
86       assumes that sysconf_DATA lists all configuration files in sysconfdir,
87       and runs sysconftool on them. This will usually have to be modified,
88       according to the application's individual needs. Finally, Makefile.am
89       must be modified to distribute the sysconftool script in the
90       application's source distribution. Adding sysconftool to EXTRA_DIST is
91       what's needed in most cases.
92
93       Finally, certain sysconftool magic incantations must be added to the
94       application's configuration files, see sysconftool(7)[1] for more
95       information. The last step involves updating the application's INSTALL
96       instructions, so that the application can be properly installed. The
97       following instructions must be added to INSTALL:
98
99        1. Run "make install-configure" after "make install".
100
101        2. If this is the first sysconftool-ized version, DO NOT simply copy
102           over the old configuration files, and overwrite the new
103           configuration files. Instead, manually edit each configuration
104           file, and manually reset each configuration setting. This is
105           because the new configuration files include the magic code for
106           sysconftool, which would be lost when the configuration file is
107           overwritten.
108
109        3. If this is not the first sysconftool-ized version, the output of
110           make install-configure must be reviewed in order to manually adjust
111           or tweak what sysconftool did. Many large configuration files can
112           result in lots of output, so the output of make install-configure
113           should be saved into a file, and reviewed.
114

SEE ALSO

116       sysconftoolcheck(1)[2], sysconftool(7)[1].
117

AUTHORS

119       Double Precision, Inc.
120

NOTES

122        1. sysconftool(7)
123           [set $man.base.url.for.relative.links]/sysconftool.7.html
124
125        2. sysconftoolcheck(1)
126           [set $man.base.url.for.relative.links]/sysconftoolcheck.1.html
127
128
129
130Courier Mail Server               10/28/2019                    SYSCONFTOOL(1)
Impressum