rcs.mgr - manage an RCS repository of configuration files
rcs.mgr options
Typically:
rcs.mgr -e, --edit file
rcs.mgr -i, --install file
rcs.mgr is designed to manage an RCS repository of configuration files. Typically a working directory will be created for a workstation under which the RCS directory is created. For example /usr/local/config will be the working directory and /usr/local/config/RCS will contain the RCS files. Managed files in the repository will be named with their full path names, with slashes changed to another character, by default a colon (:) (/etc/printcap becomes :etc:printcap). This allows a repository to contain files for a single workstation from multiple directories without having to include any directory in its entirety.
A configuration file (located in /etc/rcsmgr.conf,
/usr/local/etc/rcsmgr.conf, or rcsmgr.conf in the local directory) is used to provide defaults for the program. Values
are specified as ``variable = value''. The most important values are PATH
(designating the converted path separation character), WORKING DIRECTORY
(designating the parent directory of the RCS repository), and INSTALLDB
(designating the database of installation defaults for each file). When a
repository is created with the --initialize
(-I) command, the rcsmgr.conf and installdb files are created in the designated directory. rcsmgr.conf should be moved to /etc or </usr/local/etc> in order to be able to run the program from
anywhere on the system.
The following options are recognized by rcs.mgr. In all cases where a file name is required, it may be specified either in the live form (full path name) or repository form (path slashes replaced with the repository's path separator).
Add the named file to the repository of managed files. If the file exists and is readable by the current user, it is copied to the working directory. If it does not exist, an empty file is created. The file in the working directory is then checked in and the user is asked to provide the initial check in description of the file. The user is also requested to provide the user, group, mode, post-installation commands, and alternate editor associated with the file for entry into the install database.
Change the installation database attributes of a file. With no other
options, it sets the installation attributes to the defaults as stored in rcsmgr.conf or the internal program defaults. With the --attributes option, it sets the attributes to those specified.
Use an alternate configuration file. If found, this file takes precedence over any other configuration file that may be present on the system.
Show the differences (as per diff(1)) between the latest (or
requested) version of the file in the repository and the currently
installed version of the file. This can be used as a poor man's
rcsdiff(1) between an earlier version of the file and the
latest or as a way of seeing what changes have been made without rcs.mgr
if --check reports a signature difference.
Check out the named file and edit it. The program used to edit the file is determined in this order:
1. If the file has an 'editor' attribute set,
this program is used.
2. If the EDITOR environment variable is set,
this is used.
3. The default editor (usually vi(1)) is used.
When the editor process exits, the user is asked whether to save this file
for further editing. If so, rcs.mgr will exit after giving a reminder to check in changes with
ci(1). If the user is done editing, rcs.mgr will call ci(1) directly.
Specify a group name or numeric ID for ownership of the installed file.
This option is a shortcut for specifying the group in the
--attributes command and is deprecated.
Print out a brief help synopsis and then exits.
Initialize the working directory named. This creates the directory and the RCS repository directory and creates the rcsmgr.conf file that overrides program defaults and the installation database. This step is strongly advised but not necessary in creating the repository of managed files. The working directory and RCS repository must be created by hand if this step is not performed.
Install the named file. It will be installed in the directory determined by its repository name. The user will be asked whether any post-installation commands found in the installation database should be run at this time.
Run rlog(1) on the named file, giving a history of all RCS log
messages.
List the managed files in the RCS repository in the current working directory. The output will give the names of files in their final locations, not the repository name.
Set the checkin log message to the string given. If the message text is present, the user will not be prompted for a message.
Specify the mode (in octal) of the installed file. See
chmod(1). The default is 0444. This option is a shortcut for
specifying the mode in the --attributes command and is deprecated.
Remove the named file from the RCS repository and the install database. Do not use this option lightly, as it removes the entire history of the file.
Run silently and non-interactively for those commands where it is appropriate (not available for log, list, or remove commands). If unexpected conditions are found while running (e.g., MD5 signature mismatch), the program exits.
Specify the user name or numeric ID for ownership of the installed file.
This option is a shortcut for specifying the user in the
--attributes command and is deprecated.
Specify an RCS revision number to edit or install. Specifying a revision
earlier than the latest while editing will create a branch in the
repository. If an earlier branch is installed, it will become the default
branch for all future operations (this may be changed by running
rcs(1) directly).
Bypass all prompts and provide the default answer. When adding a file to the repository, default values are used for ownership, permissions, and post-installation commands. When editing a file, assume that the file should be checked in after editing. When installing a file, run the post-installation commands listed for the file.
The following options are available in long format only. There is getting to be too many options for short format to make any sense, and these options are less often used.
Set the installation database attributes for the file. The attributes that can be changed are user, group, mode, commands, and editor. See the section on the installation database for further details.
Check out a file for editing and exit, leaving the file in the working
directory. This is identical to entering the working directory and running
co(1) for the file, except that the rcs.mgr niceties are present.
Check in a file that has been checked out using either the --checkout option or left in the working directory after an editing session.
Check the MD5 signatures of the installed files and compare them against the signatures stored in the install database for all managed files. For those that are different, a warning is issued. This is a quick and dirty way to determine if a file has changed without going through the rcs.mgr management. It is not a replacement for an intrusion detection system like Tripwire. Since rcs.mgr requires a writeable install database and repository, there is nothing to keep intruders from modifying the signature stored in the database.
Check the MD5 signature for a single file.
Update all the MD5 signatures in the installation database on the assumption that the currently installed version is correct.
Update the MD5 signature for a single file.
First, a working directory for the repository is created and initialized
with the --initialize (-I) option. This directory may be located wherever it is most convenient
(e.g., under
/usr/local, on an NFS-mounted volume with repositories for other workstations, etc.).
Typically a managed file is added to the repository with the --add
(-a) option. This puts the original version of the file as the first version
in the repository, making rollback to the initial state possible (see the --version (-v) option).
Files may be edited either with the --edit (-e) option or by specifying the --checkout option and making the desired modifications. In the latter case (or if the
file has been retained in the working directory after an edit session), the
file may be checked in with the --checkin option.
When an updated file is ready for installation, rcs.mgr is called with the --install (-i) option. The file is checked out for reading and the installation database
is consulted to find the file ownership and post-installation commands
associated with the file. install(1) is called to do the
actual installation, and the user is asked whether any post-installation
commands should be run. When the file has been installed, the checked out
copy is deleted.
A file may be removed from the repository with the --remove
(-r) option. Do not use this feature lightly.
In practice, the lifecycle of a particular file within a repository will consist of an add command:
rcs.mgr --add /path/to/file
Followed by an indefinite repition of the edit and install commands:
rcs.mgr --edit /path/to/file rcs.mgr --install /path/to/file
The configuration file (rcsmgr.conf) for a repository is a simple file that contains ``name = value'' pairs. It is created when a repository is initialized and may be edited. For simple usage, this file is not required, however to access a repository from anywhere on the system, this file must be present and must live in /etc or /usr/local/etc and must specify the working directory. The following values are set:
WORKING DIRECTORY = /path/to/directory
PATH = :
USER = root
GROUP = root
MODE = 0444
EDITOR = /usr/bin/vi
INSTALLDB = /path/to/directory/installdb
The user, group, mode, and editor values are used as defaults when adding
files to the repository (and the installation database) and may be changed
either at addition or with the --attributes
option. If the editor associated with a file is 'DEFAULT', the value in
this file or the EDITOR environment variable will be used.
The working directory must be specified and rcsmgr.conf must be present in /etc or /usr/local/etc in order to be able to run rcs.mgr from any directory on the system. As a last resort, it looks for the configuration file in the current directory or uses defaults within the program.
The installation database resides in the working directory and is named installdb by default. As files are added to the repository, the default user, group,
and mode of the file are recorded, along with any commands that should be
run after the file is installed (e.g. newaliases(1) for /etc/aliases). The MD5 signature of the file (assuming md5 or md5sum is available on the system) is stored every time the file is installed as a
simple way to determine if changes have been made without the use of rcs.mgr. If an MD5 program is not available, the MD5 signature of a zero length
file is recorded (d41d8cd98f00b204e9800998ecf8427e). Starting with
rcs.mgr 3.0, a final field is also stored to indicate a non-default editor that
should be used when editing the file.
The format of the database is
filename:user:group:mode:md5_signature:post-install commands:editor
Blank lines and lines beginning with '#' are ignored.
Multiple post-installation commands may be specified with a semicolon (';')
between each. A file need not have an entry in the database (although if it
was added with the -a command, there will be an entry). In this case, the default values from rcsmgr.conf are used. It is highly advised that all files be present in the
installation database; in future releases the database may become a
requisite part of the system.
The fields for any file may be changed by using the --attributes
and the --change options in conjunction. The fields that may be specified in the --attributes option are:
The user ownership of the file.
The group ownership of the file.
The octal mode bits of the file.
The post-installation commands to be run for the file.
The editor to use for the file.
Replacing path name slashes with another character will lead to problems with files that include that character in their live name. The only option in this case is to use a different path separator in the repository. Multi-character path separators may be chosen to minimize the chances of name-space collision at the risk of increasing obfuscation. Separators with forward slashes in them in any form just ain't never gonna work.
If a previous version of a file is checked out and changed, it will not become the default branch until it is installed. In particular, this means that the maintainer must pay attention to what version number is reported at check in and use that version with the install command. This also has the effect that unless specified otherwise, edits on a non-default branch must all be told what version to check out until the file is installed. Pay attention.
Copyright (c) 2000-2002, John ``Rowan'' Littell. All rights reserved.
Redistribution of this script, either in source or any compiled binary format, with or without modificiation, is permitted provided the following conditions are met:
Redistributions must retain the above copyright notice, this list of conditions, and the following disclaimer either within the script itself or within the documentation or other materials accompanying the script.
The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rcs(1), ci(1), co(1),
rlog(1), install(1)
John ``Rowan'' Littell <littejo@earlham.edu>