SYSGATHER(1) User Contributed Perl Documentation SYSGATHER(1)NAMEsysgather - a configuration file mismanager
$Ringlet: sysgather.pl 1279 2007-05-10 08:56:31Z roam $
SYNOPSISsysgather [-hnqvV] [-f file] command [package...]
DESCRIPTION
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
file.
OPTIONS-f file
Specify the configuration file to use instead of the default
/usr/local/etc/sysgather.conf.
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
work.
COMMANDS
The sysgather utility recognizes the following commands:
· diff
Show the differences between the stored and current config files.
· diffsource (or diffsrc)
Show the differences between the stored and current original
(vendor) versions of the config files.
· get
Fetch the current versions of the config files.
· help
Display usage instructions and exit.
· put
Install the working copies of the config files to their real
locations.
· source (or src)
Fetch the original (vendor) versions of the config files.
· version
Display the program version and exit.
CONFIGURATION FILE SYNTAX
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.
· 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.
· 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.
· mapconf
The path to the actual top of the configuration directories' tree
if remapping the source directory paths.
· mapsrc
The path to the actual top of the source directories' tree if
remapping the source directory paths.
FILE COLLECTION SECTIONS
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
specified:
· basedir
The directory where the files from this collection will be stored
by sysgather.
· confdir
The directory where the actual files from this collection are to be
found on the system.
· 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
collection.
· 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.
MAPPING DIRECTORIES
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:
· mach
· snark
· apache
· sysgather
· straylight
· lynx
· sysgather
· vendor
· snark
· apache
· sysgather
· straylight
· lynx
· 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:
[default]
groups=lynx sysgather
mapbase=conf
mapconf=mach/straylight
mapsrc=mach/vendor/straylight
[lynx]
basedir=/usr/local/etc
confdir=conf/lynx
srcdir=/usr/local/etc
files=lynx.cfg
lynx.cfg=lynx.cfg.default
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.
FILES
/usr/local/etc/sysgather.conf
The default configuration file, unless overridden by the -f
command-line option.
~/.sysgather.conf
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
above.
/usr/local/share/examples/sysgather/*.conf
Sample configuration files.
EXAMPLES
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
BUGS
· There is no -O option=value command-line option.
· This documentation is much too sketchy.
· There is no test suite.
HISTORY
The sysgather utility was written by Peter Pentchev in 2005.
AUTHOR
Peter Pentchev <roam@ringlet.net>
perl v5.20.3 2015-10-07 SYSGATHER(1)
