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

FreeBSD Manual Pages


home | help
SYSGATHER(1)	      User Contributed Perl Documentation	  SYSGATHER(1)

       sysgather - a configuration file	mismanager

       $Ringlet: 1279 2007-05-10 08:56:31Z	roam $

	 sysgather [-hnqvV] [-f	file] command [package...]

       The sysgather utility stores various collections	of configuration
       files, both for the system and for applications,	in order to facilitate
       keeping them under version control.

       The configuration files are organized into collections, or packages.
       Each package is defined by a section in the sysgather.conf file.	 An
       example of a package could be the base system configuration files (most
       of the contents of the /etc directory), the Apache webserver
       configuration files (httpd.conf,	access.conf, mime.types, etc.),	or a
       user's dotfiles.

       If the special value "ALL" is specified as the only package name,
       sysgather operates on all the groups defined on the "groups" line in
       the "default" section of	its configuration file.

       The sysgather utility processes two configuration files:	a system-wide
       one, located in /usr/local/etc/sysgather.conf, and a per-user file
       containing additional definitions and overrides,	located	in each	user's
       home directory and named	.sysgather.conf.  If the per-user file exists,
       any collections defined within it replace the corresponding collections
       from the	system-wide file, and any variables in the "default" section
       will also replace the corresponding variables from the system-wide

       -f file
	   Specify the configuration file to use instead of the	default

	   Note: If this option	is present, the	~/.sysgather.conf file is not
	   processed after the specified configuration file.

       -h  Display usage information and exit.

       -n  For the diff, get, and put commands,	do not actually	copy any files
	   or execute any system commands, but simply report what would	have
	   been	done.

       -q  Quiet operation - suppress informational and	warning	messages, only
	   complain about genuine error	conditions.

       -V  Display the program version and exit.

       -v  Verbose operation - display progress	messages during	the program's

       The sysgather utility recognizes	the following commands:

       o   diff

	   Show	the differences	between	the stored and current config files.

       o   diffsource (or diffsrc)

	   Show	the differences	between	the stored and current original
	   (vendor) versions of	the config files.

       o   get

	   Fetch the current versions of the config files.

       o   help

	   Display usage instructions and exit.

       o   put

	   Install the working copies of the config files to their real

       o   source (or src)

	   Fetch the original (vendor) versions	of the config files.

       o   version

	   Display the program version and exit.

       The configuration file for the sysgather	utility	usually	goes by	the
       name of sysgather.conf.	It is separated	into several sections, of
       which only one is mandatory - the default section.

   THE default SECTION
       The default section specifies global sysgather parameters - the list of
       file collections	and optional directory mapping.

       o   groups

	   The most important, mandatory variable in the default section - a
	   list	of file	collections for	sysgather to process.  For each	name
	   in this list, sysgather looks for a configuration file section by
	   the same name, and treats it	as a file collection section.

       o   mapbase

	   The common path prefix that will be replaced	in directory names if
	   remapping the source	and configuration directory paths (see
	   "MAPPING DIRECTORIES" below).  Note that this must be exactly the
	   same	as the path prefix at the start	of the basedir in each
	   collection that is to be remapped, and that sysgather will
	   automatically append	a slash	at the end.

       o   mapconf

	   The path to the actual top of the configuration directories'	tree
	   if remapping	the source directory paths.

       o   mapsrc

	   The path to the actual top of the source directories' tree if
	   remapping the source	directory paths.

       A file collection is, simply put, a list	of files to keep under version
       control together.  Each collection is represented by a INI-style	group
       - the name of the group serves as the name of the collection.  There
       are two kinds of	variables within the group - collection	properties and
       source file specifications.

       There are two modes of sysgather	operation - source files and actual
       files.  The files listed	in the "files" property	are the	actual files
       that will be kept track of.  For	some of	them, a	source file may	be
       specified - an "original", vendor version.  This	may be useful for
       keeping track of	local changes and merging the vendor modifications
       across upgrades.

       For each	collection, the	following configuration	directives may be

       o   basedir

	   The directory where the files from this collection will be stored
	   by sysgather.

       o   confdir

	   The directory where the actual files	from this collection are to be
	   found on the	system.

       o   srcdir

	   The directory where the source (vendor) copies of the files are to
	   be found on the system.

	   If a	package	does not provide default versions of any files,	the
	   "srcdir" property may be specified as "NONE"	and sysgather will
	   refuse to execute the "source" and "diffsource" commands on this

       o   files

	   The actual files comprising this collection.	 Those may be
	   specified as	simple filenames within	"confdir", paths relative to
	   "confdir", or absolute paths.

       For each	of the actual files listed in the "files" directive, a source
       file may	be specified.  This is done by defining	a "property" with the
       same name as the	actual file, the value of which	is the name of the
       source file relative to "srcdir".

       For an example, please consult the various configuration	files in the
       /usr/local/share/examples/sysgather/ directory, as well as the sample
       sysgather.conf file provided with the sysgather distribution.

       Depending on the	version	control	system used, sometimes it is desirable
       to keep the source and vendor versions of the configuration files in
       separate	directories.  For instance, the	branches in a Subversion
       repository are kept in different	directories under a common root, and
       the sysgather configuration repository may be structured	like this:

       o   mach

	   o   snark

	       o   apache

	       o   sysgather

	   o   straylight

	       o   lynx

	       o   sysgather

	   o   vendor

	       o   snark

		   o   apache

		   o   sysgather

	       o   straylight

		   o   lynx

		   o   sysgather

       In this case, for the straylight	host, the configuration	directories
       are rooted under	mach/straylight/, while	the vendor versions of the
       config files are	placed under mach/vendor/straylight/.  For such
       setups, sysgather supports configuration	directory mapping with the
       mapbase,	mapconf, and mapsrc directives - using a common	name, e.g.
       conf, as	an alias for different directories in the source and vendor
       collections.  The sysgather configuration file for the straylight host
       would look like this:

	 groups=lynx sysgather


       Thus, the lynx collection uses a	"virtual" path of conf/lynx/ for the
       configuration files, and	sysgather will expand it to
       mach/vendor/straylight/lynx/ for	the stock vendor version and to
       mach/straylight/lynx/ for the real configuration	files.

	   The default configuration file, unless overridden by	the -f
	   command-line	option.

	   The per-user	configuration file, located in the home	directory of
	   the account invoking	sysgather.  The	contents of this file is
	   merged with the contents of the system-wide file as described

	   Sample configuration	files.

       Grab the	base system's default configuration files for an import	into a
       version control system:

	 sysgather source sys-fbsd5

       Fetch the currently-used	versions of the	system files and the Apache
       webserver configuration for a check-in into the version control system:

	 sysgather get sys-fbsd5 apache

       Display the differences between the stored files	and the	currently
       active Apache configuration:

	 sysgather diff	apache

       Put the stored configuration files (presumably after a version control
       check-in) as the	active configuration for the Apache webserver:

	 sysgather put apache

       o   There is no -O option=value command-line option.

       o   This	documentation is much too sketchy.

       o   There is no test suite.

       The sysgather utility was written by Peter Pentchev in 2005.

       Peter Pentchev <>

perl v5.32.1			  2021-11-05			  SYSGATHER(1)


Want to link to this manual page? Use this URL:

home | help