'\" t
.\"<!-- Copyright 2000-2003 S. Varshavchik.  See COPYING for -->
.\"<!-- distribution information. -->
.\"     Title: sysconftool
.\"    Author: S. Varshavchik.
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/11/2026
.\"    Manual: sysconftool
.\"    Source: Courier Mail Server
.\"  Language: English
.\"
.TH "SYSCONFTOOL" "1" "01/11/2026" "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, sysconftoolize \- install configuration files
.SH "SYNOPSIS"
.HP \w'\fBsysconftool\fR\ 'u
\fBsysconftool\fR [options] [filename\&.dist...]
.HP \w'\fBsysconftoolize\fR\ 'u
\fBsysconftoolize\fR
.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, its 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\&.ac, 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
\fBS\&. Varshavchik\&.\fR
.SH "NOTES"
.IP " 1." 4
\fBsysconftool\fR(7)
.RS 4
\%https://www.courier-mta.org/sysconftool/sysconftool.7.html
.RE
.IP " 2." 4
\fBsysconftoolcheck\fR(1)
.RS 4
\%https://www.courier-mta.org/sysconftool/sysconftoolcheck.1.html
.RE