• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• COMMANDS
• CONFIGURATION FILE SYNTAX
• THE default SECTION
• FILE COLLECTION SECTIONS
• FILES
• EXAMPLES
• BUGS
• HISTORY
• AUTHOR

NAME

sysgather - a configuration file mismanager

$Ringlet: sysgather.pl 319 2006-02-14 12:28:18Z roam $

SYNOPSIS

  sysgather [-hnvV] [-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.

-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

Currently, the default section only contains one setting: the groups variable, 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.

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.

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

If a file resides in a subdirectory (its name contains a slash), sysgather does not attempt to create the subdirectory itself, but errors out instead.
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>