1SYSCONFTOOL(1) sysconftool SYSCONFTOOL(1)
2
6 sysconftool, sysconftoolize - install configuration files
7
9 sysconftool [options] [filename.dist...]
10 sysconftoolize
12
14 sysconftool is a development utility that helps to install application
15 configuration files. sysconftool allows an existing application to be
16 upgraded without losing the older version's configuration settings.
17 A new version of an application often introduces new configuration
19 settings. Sometimes obsolete configuration settings are removed.
20 Existing configuration settings may also now have additional options,
21 or certain options are no longer valid any more. Because of this, an
22 application upgrade usually installs a fresh set of configuration
23 files, containing a default configuration that's known to work. Keeping
24 the existing files carries the risk of the application failing to
25 function properly due to a configuration that is no longer valid.
26 A typical application installation script copies over configuration
28 files with default settings. Existing configuration files are backed up
29 or overwritten. With sysconftool, an application will install a
30 configuration file names filename.dist, instead of filename. Then, the
31 application's installation script runs sysconftool. sysconftool copies
32 filename.dist to filename, but also checks if filename from an older
33 version of the application already exist. If filename an older
34 sysconftool-installed configuration file, its configuration settings
35 replace the defaults in filename.dist, which is then subsequently
36 installed as filename. sysconftool is smart enough to:
37 • Remove configuration settings that no longer exist.
39 • Add new configuration settings.
41 • Do not preserve an older configuration setting if there's a
43 possibility that it is no longer valid in the new version of the
44 application.
45 sysconftool produces a short report when it runs. The report lists
47 every configuration setting in $filename.dist, and its disposition. The
48 possible dispositions are:
49 new
51 This a new configuration setting that wasn't found in the existing
52 $filename.
53 unchanged
55 This setting's value was taken from the existing $filename,
56 replacing the default value provided by $filename.dist.
57 UPDATED
59 This setting has been previously set in $filename, but the
60 setting's value may no longer be valid in the new version of the
61 application, so its default value is taken from $filename.dist, and
62 it may need to be manually adjusted.
63 All this logic is based on some additional metadata that must be
65 included in each configuration file, that sysconftool reads. For this
66 to work, both the old and the new version of the application must be
67 sysconftool-ized. sysconftool operates in a fail-safe mode. If the old
68 version did not use sysconftool, $filename is backed up to
69 $filename.bak, and $filename is copied to $filename. This is what would
70 essentially happen anyway without sysconftool. The local configuration
71 needs to be reentered into $filename, so nothing is lost. However, the
72 next upgrade will see sysconftool do its job.
73
75 sysconftool requires the application to use autoconf and automake. The
76 first step is to run the sysconftoolize script from the application's
77 source directory. sysconftoolize creates a symbolic link to the
78 sysconftool script from the current directory, and appends a default
79 install-configure rule to Makefile.am. sysconftoolize with the --copy
80 option copies the script, instead of creating a symbolic link.
81 After running sysconftoolize the macro AC_PROG_SYSCONFTOOL must be
83 manually added to configure.ac, and Makefile.am must be modified as
84 follows.
85 Makefile.am must be modified to install configuration files as
87 filename.dist instead of filename. The default install-configure rule
88 assumes that sysconf_DATA lists all configuration files in sysconfdir,
89 and runs sysconftool on them. This will usually have to be modified,
90 according to the application's individual needs. Finally, Makefile.am
91 must be modified to distribute the sysconftool script in the
92 application's source distribution. Adding sysconftool to EXTRA_DIST is
93 what's needed in most cases.
94 Finally, certain sysconftool magic incantations must be added to the
96 application's configuration files, see sysconftool(7)[1] for more
97 information. The last step involves updating the application's INSTALL
98 instructions, so that the application can be properly installed. The
99 following instructions must be added to INSTALL:
100 1. Run "make install-configure" after "make install".
102 2. If this is the first sysconftool-ized version, DO NOT simply copy
104 over the old configuration files, and overwrite the new
105 configuration files. Instead, manually edit each configuration
106 file, and manually reset each configuration setting. This is
107 because the new configuration files include the magic code for
108 sysconftool, which would be lost when the configuration file is
109 overwritten.
110 3. If this is not the first sysconftool-ized version, the output of
112 make install-configure must be reviewed in order to manually adjust
113 or tweak what sysconftool did. Many large configuration files can
114 result in lots of output, so the output of make install-configure
115 should be saved into a file, and reviewed.
116
118 sysconftoolcheck(1)[2], sysconftool(7)[1].
119
121 Double Precision, Inc.
122
124 1. sysconftool(7)
125 https://www.courier-mta.org/sysconftool/sysconftool.7.html
126 2. sysconftoolcheck(1)
128 https://www.courier-mta.org/sysconftool/sysconftoolcheck.1.html
129Courier Mail Server 05/21/2022 SYSCONFTOOL(1)