Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SYSCONFTOOL(1)			  sysconftool			SYSCONFTOOL(1)

NAME
       sysconftool - install configuration files

SYNOPSIS
       sysconftool [options] [filename.dist...]

DESCRIPTION
       sysconftool is a	development utility that helps to install application
       configuration files.  sysconftool allows	an existing application	to be
       upgraded	without	losing the older version's configuration settings.

       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's	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.

       A typical application installation script copies	over configuration
       files with default settings. Existing configuration files are backed up
       or overwritten. With sysconftool, an application	will install a
       configuration file names	filename.dist, instead of filename. Then, the
       application's installation script runs sysconftool.  sysconftool	copies
       filename.dist to	filename, but also checks if filename from an older
       version of the application already exist. If filename an	older
       sysconftool-installed configuration file, it's configuration settings
       replace the defaults in filename.dist, which is then subsequently
       installed as filename.  sysconftool is smart enough to:

       o   Remove configuration	settings that no longer	exist.

       o   Add new configuration settings.

       o   Do not preserve an older configuration setting if there's a
	   possibility that it is no longer valid in the new version of	the
	   application.

       sysconftool produces a short report when	it runs. The report lists
       every configuration setting in $filename.dist, and its disposition. The
       possible	dispositions are:

       new
	   This	a new configuration setting that wasn't	found in the existing
	   $filename.

       unchanged
	   This	setting's value	was taken from the existing $filename,
	   replacing the default value provided	by $filename.dist.

       UPDATED
	   This	setting	has been previously set	in $filename, but the
	   setting's 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.

       All this	logic is based on some additional metadata that	must be
       included	in each	configuration file, that sysconftool reads. For	this
       to work,	both the old and the new version of the	application must be
       sysconftool-ized.  sysconftool operates in a fail-safe mode. If the old
       version did not use sysconftool,	$filename is backed up to
       $filename.bak, and $filename is copied to $filename. This is what would
       essentially happen anyway without sysconftool. The local	configuration
       needs to	be reentered into $filename, so	nothing	is lost. However, the
       next upgrade will see sysconftool do its	job.

ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION
       sysconftool requires the	application to use autoconf and	automake. The
       first step is to	run the	sysconftoolize script from the application's
       source directory.  sysconftoolize creates a symbolic link to the
       sysconftool script from the current directory, and appends a default
       install-configure rule to Makefile.am.  sysconftoolize with the --copy
       option copies the script, instead of creating a symbolic	link.

       After running sysconftoolize the	macro AC_PROG_SYSCONFTOOL must be
       manually	added to configure.in, and Makefile.am must be modified	as
       follows.

       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	sysconftool on them. This will usually have to be modified,
       according to the	application's individual needs.	Finally, Makefile.am
       must be modified	to distribute the sysconftool script in	the
       application's source distribution. Adding sysconftool to	EXTRA_DIST is
       what's needed in	most cases.

       Finally,	certain	sysconftool magic incantations must be added to	the
       application's configuration files, see sysconftool(7)[1]	for more
       information. The	last step involves updating the	application's INSTALL
       instructions, so	that the application can be properly installed.	The
       following instructions must be added to INSTALL:

	1. Run "make install-configure"	after "make install".

	2. If this is the first	sysconftool-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
	   sysconftool,	which would be lost when the configuration file	is
	   overwritten.

	3. If this is not the first sysconftool-ized version, the output of
	   make	install-configure must be reviewed in order to manually	adjust
	   or tweak what sysconftool did. Many large configuration files can
	   result in lots of output, so	the output of make install-configure
	   should be saved into	a file,	and reviewed.

SEE ALSO
       sysconftoolcheck(1)[2], sysconftool(7)[1].

AUTHORS
       Double Precision, Inc.

NOTES
	1. sysconftool(7)
	   [set	$man.base.url.for.relative.links]/sysconftool.7.html

	2. sysconftoolcheck(1)
	   [set	$man.base.url.for.relative.links]/sysconftoolcheck.1.html

Courier	Mail Server		  08/25/2013			SYSCONFTOOL(1)

NAME | SYNOPSIS | DESCRIPTION | ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION | SEE ALSO | AUTHORS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sysconftool&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help