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

FreeBSD Manual Pages

  
 
  

home | help
SYSCONFTOOL(7)			  sysconftool			SYSCONFTOOL(7)

NAME
       sysconftool - format of configuration files installed by	sysconftool

SYNOPSIS
	  #
	  ##VERSION: $Id$

	  ##NAME: configname1:configname1version
	  #
	  # Description

	  SETTING1=VALUE1

	  ##NAME: configname2:configname2version
	  #
	  # Description

	  SETTING2=VALUE2

	  ...

DESCRIPTION
       This manual page	describes the format of	configuration files installed
       by sysconftool(1)[1]. This format is flexible enough to accomodate any
       kind of application configuration file format.  sysconftool makes four
       assumptions about the configuration file:

	1. It is a plain text file.

	2. Lines that begin with a single '#' character	are comments that
	   contain a description of the	following configuration	setting.

	3. Lines that do not begin with	the '#'	character contain the
	   configuration setting described by the previous comment lines.

	4. Configuration settings are self contained, and completely
	   independent,	changing one configuration setting never requires that
	   another, different, configuration setting must be changed too
	   (perhaps any	logical	conflicts are automatically resolved by	the
	   application in a safe, fallback, manner)

       The additional information used by sysconftool is encoded as
       specially-formatted comment lines that begin with two '#' characters.

FILENAMES
       An application installs a default configuration file as
       "filename.dist",	when the actual	name of	the configuration file is
       really "filename". If there is no existing filename, sysconftool	simply
       copies filename.dist to filename, and calls it a	day. Otherwise,
       sysconftool copies the existing filename	to filename.bak	and creates a
       new filename based on the contents of both files.

       sysconftool is designed to solve	a common problem with application
       configuration. New versions of applications often include additional
       functionality that requires new configuration settings. Without the new
       configuration settings the application will not work, so	new
       configuration files should be installed during the upgrade. However,
       when that happens, any changes to the existing configuration settings
       are lost.  sysconftool is designed to solve this	dillemma, and merge
       old configuration settings with new ones.  sysconftool is designed in a
       fail-safe way. Whenever there's a doubt as to what's The	Right Thing To
       Do, sysconftool will use	the configuration settings from	the new	file,
       that are	supposedly known to be good, and leave it up to	a physical
       being to	sort out any conflicts and make	any manual decisions.

FILE VERSIONING
       The following line should appear	at the beginning of filename.dist:

	      ##VERSION: version

       This doesn't have to be the very	first line in filename.dist, but it
       should appear somewhere within the first	twenty lines, right before the
       first configuration setting. "version" should be	some kind of an
       identifier for this particular version of the configuration files. All
       that sysconftool	cares about is that any	change to the default
       configuration, in filename.dist,	results	in a different version.	An
       excellent way to	do this	is to simply use the $Id$ RCS/CVS version
       identification strings, and have	this little detail taken care of
       automatically.

       New revisions of	an application should not necessarily have a new
       configuration file version. If the default application configuration
       settings	have not changed from the previous release, version can	remain
       the same.  version is copied from filename.dist to filename.

       If there's an existing filename,	and it includes	the same version
       identifier, sysconftool silently	skips over this	configuration file,
       and doesn't do anything,	assuming that this configuration file has
       already been installed. Therefore, running sysconftool more than	once
       (accidentally) will not break anything.

       If there's an existing filename,	but it's version is different,
       sysconftool backs it up to filename.bak,	then creates a new filename.
       If there's an existing filename,	but it doesn't contain a recognizable
       "##VERSION: version" line, sysconftool assumes that the previous
       version of the application did not use the sysconftool tool. That's not
       a problem.  filename is copied to filename.bak, and filename.dist gets
       installed as the	new filename, allowing sysconftool to work with	the
       next version of this configuration file.

CONFIGURATION SETTING VERSIONING
       Each configuration setting uses the following format in the
       configuration file:

	      ##NAME: name:revision
	      #
	      #	description

	      setting

       sysconftool looks for a line that begins	with "##NAME". This line gives
       the name	and the	revision of the	following setting.  name must be
       unique within its configuration file (the same name can be used by
       different configuration files, sysconftool works	with one file at a
       time).  revision	is used	by sysconftool to decide when the
       configuration setting can be safely carried over	from an	older
       configuration file, and when it is better to reinstall the default
       setting from the	new configuration file.

       One or more comment lines - lines that begin with the '#' character -
       may follow "##NAME". The	first line that	does not begin with '#'	is
       considered to be	the first line that contains the value of the
       configuration setting, which lasts. The value can be spread over
       multiple	lines. The configuration setting is considered to last until
       either the end of the file, or until the	first following	line that
       begins with another "##NAME".

       Aside from that,	sysconftool does not care how the configuration
       setting is represented. It can be "NAME=VALUE", it can be "NAME:
       VALUE", or "NAME<tab>VALUE", it can even	be a base64-encoded binary
       object, and it can always have leading or trailing blank	lines.
       sysconftool merely looks	at which lines begin with the '#' comment
       character. After	the '##NAME:' line, sysconftool	looks ahead until the
       first line that does not	begin with '#',	and that's the first line of
       the configuration setting. Then,	sysconftool looks ahead	until the next
       line that starts	with a "##NAME:", which	marks the end of this
       configuration setting.

       For this	reason it is important that all	commented description lines
       that follow '##NAME:' must begin	with the '#' character.	If a blank
       line follows the	line with '##NAME:' it is assumed to be	the start of
       the corresponding configuration setting.	For example, this is correct:

	      ##NAME: flag1:0
	      #
	      #
	      #	This is	the first configuration	flag
	      #

	      flag1=1

       This is not correct:

	      ##NAME: flag1:0

	      #
	      #	This is	the first configuration	flag
	      #

	      flag1=1

CONFIGURATION FILE CREATION
       A new configuration file, "filename", is	created	from its previous
       version,	"filename.bak" and the new default configuration file,
       "filename.dist",	using the following, simple, two-step process.

	1. sysconftool begins with filename.dist in hand. This makes sure that
	   sysconftool begins with a good, known, default configuration	file.

	2. sysconftool then takes each configuration setting in	filename.dist,
	   then	searches filename.bak. If it finds a configuration setting
	   that	has an identical "name"	and "version", then the	corresponding
	   configuration setting value is taken	from filename.bak, replacing
	   the default in filename.dist. After all configuration settings in
	   filename.dist are looked up (and potentially	replaced), what's left
	   becomes the new filename.

THE END	RESULT
       The above process is a logical description. The actual technical
       implementation is slightly different (for example, filename is not
       backed up to filename.bak until the new configuration file has been
       already created), but is	logically equivalent to	this process. This
       process carries a number	of consequences	that must be considered.

       If a new	application revision needs a new configuration setting,	it
       will get	a new name and version.	Since filename.dist is used as a
       starting	point for the new configuration	file, the new configuration
       file will include the new configuration setting.	When a configuration
       setting is removed, it will disappear from the new configuration	file
       for the same exact reason.

CONFIGURATION SETTING VERSION
       sysconftool looks at both name and version. A configuration setting
       with the	same name but different	versions are seen by sysconftool as
       completely different settings. The existence of version allows a
       finer-grained control of	configuration upgrades,	as described below.

       sysconftool copies setting values with the same name and	version	from
       the old configuration file to the new configuration file. However, the
       associated descriptive comments are not copied, and are taken from the
       new filename.dist. Therefore, if	a new version of the configuration
       file contains an	updated	or an embellished description of a particular
       setting,	it will	be included in the new configuration file, but the
       existing	configuration value will be preserved! Generally, if a
       configuration setting does not change its meaning or function, its name
       and version should remain the same. Its comments	can be edited to fix a
       typo, or	revised	in a more substantive fashion.	Name and version
       should only be changed if there's a functional change in	the
       configuration setting.

       What to do with name and	version	after a	functional change depends on
       the nature and the magnitude of the change. The nature and the
       magnitude of the	change must be considered not only with	respect	to the
       most recent revision of the application,	but to all the previous
       revisions as well. When in doubt, go based upon the largest change in
       magnitude, in order to guarantee	a functional default setting, from
       filename.dist, and leave	it up to a living being	to manually figure it
       out.

       If only the default value of a setting should be	changed	for new
       application installation, but the existing installations	can continue
       to use the existing value of the	setting, both the name and version
       should be left alone. Existing configuration settings will be
       preserved, and new installations	will get the new default. The
       descriptive comment of this setting can be updated too (see above).

       This should be done only	as long	as ALL previous	values of this
       configuration setting will ALWAYS be valid in the new application
       revision. If some possible values of this configuration setting will no
       longer be valid,	version	should be changed.  sysconftool	does not care
       how name	and version are	formatted. Both	are opaque labels. The only
       requirements is for the label to	be different. The difference between
       changing	version	and changing both name and version is this:

       If there's an old configuration setting with the	same name but
       different version, sysconftool will still use the new, safe, default
       value from filename.dist, however sysconftool will also append an
       additional comment, on its own accord, reminding	the reader that	this
       configuration value has been reset, and the reader should consider
       whether to manually restore the configuration value from	the old
       configuration.

MISCELLANEA
       When sysconftool	decides	to keep	an existing setting, with the same
       name and	value, it will also insert a short comment to that effect,
       reminding the reader to check the default in filename.dist.

SEE ALSO
       sysconftool(1)[1].

AUTHORS
       Double Precision, Inc.

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

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

NAME | SYNOPSIS | DESCRIPTION | FILENAMES | FILE VERSIONING | CONFIGURATION SETTING VERSIONING | CONFIGURATION FILE CREATION | THE END RESULT | CONFIGURATION SETTING VERSION | MISCELLANEA | SEE ALSO | AUTHORS | NOTES

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

home | help