'\" t .\" .\" .\" Title: sysconftool .\" Author: Double Precision, Inc. .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" Date: 08/25/2013 .\" Manual: sysconftool .\" Source: Courier Mail Server .\" Language: English .\" .TH "SYSCONFTOOL" "1" "08/25/2013" "Courier Mail Server" "sysconftool" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" sysconftool \- install configuration files .SH "SYNOPSIS" .HP \w'\fBsysconftool\fR\ 'u \fBsysconftool\fR [options] [filename\&.dist...] .SH "DESCRIPTION" .PP \fBsysconftool\fR is a development utility that helps to install application configuration files\&. \fBsysconftool\fR allows an existing application to be upgraded without losing the older version\*(Aqs configuration settings\&. .PP 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\*(Aqs 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\&. .PP A typical application installation script copies over configuration files with default settings\&. Existing configuration files are backed up or overwritten\&. With \fBsysconftool\fR, an application will install a configuration file names filename\&.dist, instead of filename\&. Then, the application\*(Aqs installation script runs \fBsysconftool\fR\&. \fBsysconftool\fR copies filename\&.dist to filename, but also checks if filename from an older version of the application already exist\&. If filename an older \fBsysconftool\fR\-installed configuration file, it\*(Aqs configuration settings replace the defaults in filename\&.dist, which is then subsequently installed as filename\&. \fBsysconftool\fR is smart enough to: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Remove configuration settings that no longer exist\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Add new configuration settings\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Do not preserve an older configuration setting if there\*(Aqs a possibility that it is no longer valid in the new version of the application\&. .RE .PP \fBsysconftool\fR produces a short report when it runs\&. The report lists every configuration setting in $filename\&.dist, and its disposition\&. The possible dispositions are: .PP new .RS 4 This a new configuration setting that wasn\*(Aqt found in the existing $filename\&. .RE .PP unchanged .RS 4 This setting\*(Aqs value was taken from the existing $filename, replacing the default value provided by $filename\&.dist\&. .RE .PP UPDATED .RS 4 This setting has been previously set in $filename, but the setting\*(Aqs value may no longer be valid in the new version of the application, so its default value is taken from $filename\&.dist, and it may need to be manually adjusted\&. .RE .PP All this logic is based on some additional metadata that must be included in each configuration file, that \fBsysconftool\fR reads\&. For this to work, both the old and the new version of the application must be \fBsysconftool\fR\-ized\&. \fBsysconftool\fR operates in a fail\-safe mode\&. If the old version did not use \fBsysconftool\fR, $filename is backed up to $filename\&.bak, and $filename is copied to $filename\&. This is what would essentially happen anyway without \fBsysconftool\fR\&. The local configuration needs to be reentered into $filename, so nothing is lost\&. However, the next upgrade will see \fBsysconftool\fR do its job\&. .SH "ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION" .PP \fBsysconftool\fR requires the application to use \fBautoconf\fR and \fBautomake\fR\&. The first step is to run the \fBsysconftoolize\fR script from the application\*(Aqs source directory\&. \fBsysconftoolize\fR creates a symbolic link to the \fBsysconftool\fR script from the current directory, and appends a default install\-configure rule to Makefile\&.am\&. \fBsysconftoolize\fR with the \fB\-\-copy\fR option copies the script, instead of creating a symbolic link\&. .PP After running \fBsysconftoolize\fR the macro AC_PROG_SYSCONFTOOL must be manually added to configure\&.in, and Makefile\&.am must be modified as follows\&. .PP Makefile\&.am must be modified to install configuration files as filename\&.dist instead of filename\&. The default install\-configure rule assumes that sysconf_DATA lists all configuration files in sysconfdir, and runs \fBsysconftool\fR on them\&. This will usually have to be modified, according to the application\*(Aqs individual needs\&. Finally, Makefile\&.am must be modified to distribute the \fBsysconftool\fR script in the application\*(Aqs source distribution\&. Adding \fBsysconftool\fR to EXTRA_DIST is what\*(Aqs needed in most cases\&. .PP Finally, certain \fBsysconftool\fR magic incantations must be added to the application\*(Aqs configuration files, see \m[blue]\fB\fBsysconftool\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2 for more information\&. The last step involves updating the application\*(Aqs INSTALL instructions, so that the application can be properly installed\&. The following instructions must be added to INSTALL: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} Run "make install\-configure" after "make install"\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} If this is the first \fBsysconftool\fR\-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 \fBsysconftool\fR, which would be lost when the configuration file is overwritten\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} If this is not the first \fBsysconftool\fR\-ized version, the output of \fBmake install\-configure\fR must be reviewed in order to manually adjust or tweak what \fBsysconftool\fR did\&. Many large configuration files can result in lots of output, so the output of \fBmake install\-configure\fR should be saved into a file, and reviewed\&. .RE .SH "SEE ALSO" .PP \m[blue]\fB\fBsysconftoolcheck\fR(1)\fR\m[]\&\s-2\u[2]\d\s+2, \m[blue]\fB\fBsysconftool\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2\&. .SH "AUTHORS" .PP \fBDouble Precision, Inc\&.\fR .SH "NOTES" .IP " 1." 4 \fBsysconftool\fR(7) .RS 4 \%[set $man.base.url.for.relative.links]/sysconftool.7.html .RE .IP " 2." 4 \fBsysconftoolcheck\fR(1) .RS 4 \%[set $man.base.url.for.relative.links]/sysconftoolcheck.1.html .RE