1SYSCONFTOOL(1) SYSCONFTOOL(1)
2
6 sysconftool - install configuration files
7
9 sysconftool [ options ] [ filename.dist ... ]
10
13 sysconftool is a development utility that helps to install application
14 configuration files. sysconftool allows an existing application to be
15 upgraded without losing the older version's configuration settings.
16 A new version of an application often introduces new configuration set‐
18 tings. Sometimes obsolete configuration settings are removed. Existing
19 configuration settings may also now have additional options, or certain
20 options are no longer valid any more. Because of this, an application
21 upgrade usually installs a fresh set of configuration files, containing
22 a default configuration that's known to work. Keeping the existing
23 files carries the risk of the application failing to function properly
24 due to a configuration that is no longer valid.
25 A typical application installation script copies over configuration
27 files with default settings. Existing configuration files are backed
28 up or overwritten. With sysconftool, an application will install a con‐
29 figuration file names filename.dist, instead of filename. Then, the
30 application's installation script runs sysconftool. sysconftool copies
31 filename.dist to filename, but also checks if filename from an older
32 version of the application already exist. If filename an older syscon‐
33 ftool-installed configuration file, it's configuration settings replace
34 the defaults in filename.dist, which is then subsequently installed as
35 filename. sysconftool is smart enough to:
36 · Remove configuration settings that no longer exist.
38 · Add new configuration settings.
40 · Do not preserve an older configuration setting if there's a possibil‐
42 ity that it is no longer valid in the new version of the application.
43 sysconftool produces a short report when it runs. The report lists
45 every configuration setting in $filename.dist, and its disposition.
46 The possible dispositions are:
47 new This a new configuration setting that wasn't found in the exist‐
49 ing $filename.
50 unchanged
52 This setting's value was taken from the existing $filename,
53 replacing the default value provided by $filename.dist.
54 UPDATED
56 This setting has been previously set in $filename, but the set‐
57 ting's value may no longer be valid in the new version of the
58 application, so its default value is taken from $filename.dist,
59 and it may need to be manually adjusted.
60 All this logic is based on some additional metadata that must be
62 included in each configuration file, that sysconftool reads. For this
63 to work, both the old and the new version of the application must be
64 sysconftool-ized. sysconftool operates in a fail-safe mode. If the
65 old version did not use sysconftool, $filename is backed up to $file‐
66 name.bak, and $filename is copied to $filename. This is what would
67 essentially happen anyway without sysconftool. The local configuration
68 needs to be reentered into $filename, so nothing is lost. However, the
69 next upgrade will see sysconftool do its job.
70
72 sysconftool requires the application to use autoconf and automake. The
73 first step is to run the sysconftoolize script from the application's
74 source directory. sysconftoolize copies the sysconftool script to the
75 current directory, and appends a default install-configure rule to
76 Makefile.am. After running sysconftoolize the macro AC_PROG_SYSCONFTOOL
77 must be manually added to configure.in, and Makefile.am must be modi‐
78 fied as follows.
79 Makefile.am must be modified to install configuration files as file‐
81 name.dist instead of filename. The default install-configure rule
82 assumes that sysconf_DATA lists all configuration files in sysconfdir,
83 and runs sysconftool on them. This will usually have to be modified,
84 according to the application's individual needs. Finally, Makefile.am
85 must be modified to distribute the sysconftool script in the applica‐
86 tion's source distribution. Adding sysconftool to EXTRA_DIST is what's
87 needed in most cases.
88 Finally, certain sysconftool magic incantations must be added to the
90 application's configuration files, see sysconftool(7) for more informa‐
91 tion. The last step involves updating the application's INSTALL
92 instructions, so that the application can be properly installed. The
93 following instructions must be added to INSTALL:
94 1. Run "make install-configure" after "make install".
96 2. If this is the first sysconftool-ized version, DO NOT simply copy
98 over the old configuration files, and overwrite the new configura‐
99 tion files. Instead, manually edit each configuration file, and
100 manually reset each configuration setting. This is because the new
101 configuration files include the magic code for sysconftool, which
102 would be lost when the configuration file is overwritten.
103 3. If this is not the first sysconftool-ized version, the output of
105 make install-configure must be reviewed in order to manually adjust
106 or tweak what sysconftool did. Many large configuration files can
107 result in lots of output, so the output of make install-configure
108 should be saved into a file, and reviewed.
109
111 sysconftoolcheck(1), sysconftool(7).
112Double Precision, Inc. 16 July 2005 SYSCONFTOOL(1)