[BACK]Return to Config.ms CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / othersrc / nastore / volman

File: [cvs.NetBSD.org] / othersrc / nastore / volman / Config.ms (download)

Revision 1.1, Mon Feb 28 02:18:21 2000 UTC (22 years, 5 months ago) by wrstuden
Branch point for: MAIN

Initial revision

.\" Process this file through nroff -ms
.\"
.ds OUT OF DATE
.ds vm Volume Manager
.ds rp \fBvoldaemon\fR
.ds RC \s-1RC\s0
.ds ac \s-1ACS\s0
.TL
NAStore \*(vm Setup Notes
.AU
Bill Ross
Jonathan Hahn
.NH
Introduction
.PP
This document is an overall description of the \*(vm and its 
components in view of the configuration parameters that need 
to be set and the directories that need to be created in order
to install and start it. A step-by-step procedure for installing 
and bringing up the \*(vm is in the last section.
.NH 1
Overall Description
.PP
The \*(vm is a system for managing removable volumes.
Its initial support was for round (3420) and square (3480) 
manually-mounted tapes and the StorageTek 4400 Automated Cartridge 
System (\*(ac). It was designed to be easily upgraded for future 
forms of storage, in that the server (Repository Controller, or RC)
for a particular type of medium (and mounting protocol) can be written 
and added to the configuration without basic redesign of the central 
volume management code. A prototype RC is provided (rc/proto/) which
was adapted without much change to form the basis of a fairly
generic, vault-protocol manual Repository Controller (rc/vault/),
which optionally interfaces across the net with a database server,
which in turn optionally connects with the cradle of a bar-code
reading gun device (all code included). The prototype RC was also
adapted to communicate with a StorageTek robot controller (rc/acs/).
The RCs are configured in vm_rctab.c, and their drives are listed
in the RCCONF file, traditionally placed in /usr/mss/lib/volman/.
The ACS RC configuration files are described in rc/acs/.
.PP
Operators get messages via syslog(3) broadcasts to login names which 
are configured in the Makefile (VOLMANACCT) and in vm.h (RCs); various 
directories, e.g. for logging and database files, are also defined in 
Makefile and vm.h. The database has information on volumes (e.g.
ownership and access privileges) and user quotas, if any.
The database is created automatically on initial startup,
provided the directory defined for it exists.
.NH 1
Directories
.PP
The
.I "source directory"
is where the distribution tape is read in and
is a working area for building the \*(vm binaries.
Some parts are copied into other directories, but most of the files
(primarily source files) exist only in the source directory.
.PP
The
.I "spool directory"
contains transient files associated with the operation of the \*(vm.
These files include an event/error log as well as FIFOs (inter-process 
communication ports) if this IPC method is chosen in the Makefile.
An acs subdirectory contains \*(ac state information.
.I Spool
is a bit of a misnomer here as there is no spooling going on
(\*`a la line printers) but
.I /usr/spool
is the most appropriate place for this directory.
The spool directory is
.I /usr/spool/mss/volman
in the default configuration.
.PP
The
.I "library directory"
contains non-transient files associated with the operation of the \*(vm.  
These include the \*(vm database directory, configuration files, and binaries. 
The database is default-configured to be in the
.B dbase
subdirectory.  The configuration files include
.B RCCONF
(the device configuration file) and 
.B acs/ACSCONF
(the \*(ac configuration file).  Binaries include:
.B vaultrc
(the manual tape repository controller),
.B acsrc
(the \*(ac controller when present),
.B voltimer
(the \*(vm system timer).  
Also included are administrative utilities such as
.B volentdb
and 
.B voldeldb.

The installer may want to put the admin utilities 
in a more accessible directory.  The utilities in the library directory 
are not typically invoked by ordinary users and are intended to be called 
from other programs and by the system administrator.
The library directory is
.I /usr/mss/lib/volman
in the default configuration.
.PP
User-accessible binaries are installed in a bin directory and
manual pages in a man directory.  These are respectively
.I /usr/mss/bin
and
.I /usr/mss/man
in the default configuration.
.NH 1
Administrative Binaries
.PP
\*(rp* is the \*(vm daemon.
.FS
The \*(rp is sometimes called the ``RP'' or Request Processor
for historical reasons.
.FE
This program should be invoked at boot time, probably from an 
\fI/etc/rc\fR-type file.  \*(rp puts itself into the background.
It should never die, but if it does
it can be restarted manually by root or the \*(vm operator account.
If the \*(rp is invoked while another is already running,
the new one will terminate itself.  In the default configuration,
\*(rp lives in /etc along with
.B vshutdown,
the program which brings the \*(vm down.
.PP
The \*(RCs are the repository controllers.  Each \*(RC provides the 
interface between the \*(rp and a physical volume repository
(e.g.: the \*(ac, the manual round tapes and the manual 3480 square tapes).
A repository is defined as a [location, medium] pair.
The \*(rp invokes \*(RCs when it begins execution according to the table in
.I vmrctab.c
described below.
The \*(RCs supplied are 
.I vaultrc,
the manual repository controller (a process is created for both 3480s and 
3420s in the default configuration) and
.I acsrc
for the \*(ac.
.NH 1
User-accessible Binaries
.PP
.B
vreserve, vol, volmv, volstat,
vls, vchmod, vchown, vchgrp, vquota, volvary,
volalloc, vrecycle, vlabel, vwlabel
.R
.PP
Note that the
.B vlabel
and the 
.B vwlabel
link to it must supplant any existing labeling command 
(e.g. under UTS see \f2label\f1(1)). The old command should be made 
unavailable since it can result in database inconsistencies (see below).
All other utilities are new and are not known to conflict with 
existing names in Unix, but the careful administrator will check for
overlap.  All utilities are documented in the man pages.
.NH 1
User-accessible Libraries
.PP
There is one library archive called
.B libvol.a.
This is used to create programs which interact with the \*(vm
and should be placed in a user-accessible library directory such as
.I /usr/lib.
.NH 1
Consoles
.PP
The \*(vm broadcasts status information to one or more consoles:
The consoles used are assigned by LOG_LOCALx (on UTS: LOG_USERx) codes
according to the host's syslog convention, which are used in vm_log.c 
and vm_rctab.c. These codes correspond to userX entries in the syslog(3) 
/etc/syslog.conf file, e.g. for LOG_LOCAL0 and LOG_LOCAL1 in the
default configuration, these entries belong in syslog.conf:
.nf

# volman RP console
#
local0.notice                                   volman
#
# acsrc lcl console
#
local1.notice                                   acs

.fi
There is one console associated with the
.B voldaemon
(LOG_USER0) and optionally one console for each \*(RC.
It is OK to use one console for all \*(RCs. Also, each console
can cause broadcasts to several accounts per the definition in 
/etc/syslog.conf. A hacked syslog facility was prepared for UTS
and can be found is volman/syslog/.
.NH 1
Configuration Parameters
.PP
This section describes the parameters (and their locations)
which may need to be considered and possibly changed by the installer.
.NH 2
vm.h
.PP
The parameters in this file are all manifest constants.
Some are intended to be reconfigured; however, the first
block contains fundamental constants which should not be changed.
Some constants are turned on if
.B DEBUG
is enabled in the Makefile and can be ignored otherwise.
.PP
.B SPOOLDIR
is the path to the spool directory described above.
.B NODEDIR
corresponds to
.I /dev/tape
in
.I tpdaemon(1M).
Some utilities (e.g. IBR) may require that this directory be
.I /dev/tape.
However, note that both the \*(vm and the 
.I tpdaemon(1M)
clear this directory when they start up,
and this can lead to major operational problems if both are run concurrently.
.PP
.B VOLMANDB
contains the location and name of the database,
.B ACSRC
contains the name for the \*(ac Server program.  (If ACSRC is not #defined,
the code should compile without it configured.) In the
.B sandbox
configuration, these are
.I /usr/mss/lib/volman/dbase/volman,
and
.I acssrvr,
respectively.
.PP
See ``Database Considerations''
below for information about
.B INFORMIXDIR,
.B SQLEXEC
and
.B VOLMANDB
(these are only relevant for conversion from old beta release databases).
.B ERRORLOG
is the name of the error/event log file in the
.B SPOOLDIR.
.NH 2
Makefile
.PP
The parameters in this file are simliar to those in
.I vm.h,
but are needed here for installation.
.B "LIBDIR, BINDIR, USRLIBDIR"
and
.B ETCDIR
are the paths to the library directory,
user binary directory, user library (as in C archive libraries),
and /etc directory respectively.
.B VOLMANACCT
is the name of the \*(vm operator account.
.NH 2
vmrctab.c
.PP
This file contains the \*(RC configuration table, called
.B vRCTab[\|]
and the
.B movetable[\|]
array which specifies which RC-RC moves are legal.
The only simple configurable parameters here are the 
vRCTab \*(RC console accounts
and the syslog facilities. The console accounts are used for permission
checking. The 
The manual RCs are currently set to
.B VOLMANACCT
which is the
.I volman
account (defined in Makefile) and the ACS account is set to ``acs.''
The syslog facility for the manual RCs is LOG_USER0 (same as the
voldaemon console) and the ACS is LOG_USER1. The meanings
of these symbols are described in the previous section.
.NH 2
RCCONF
.PP
This file contains one line for each device in the system and associates
each device with an \*(RC.
It is read each time the \*(vm begins execution.
The layout of the file is described in the comments at the top
in the sample version located in the source directory.
.B
Note: this file must be set up before the \*(vm can be operated.
.R
.NH 1
Database Considerations
.PP
The database of the moment is Hunter and Associates' BPLUS btree
index package. The code is in /usr/src/mss/bplus.
.PP
This paragraph can be skipped if an old-style Informix database
does not need to be converted to the new form.
The dbtrans.ec source file incorporates Informix/esql database
code, which requires `esql' in place of `cc' for compilation. This is
reflected in the Makefile. For the Makefile to work, the INFORMIXDIR
environment needs to be set to the location of Informix in the filesystem,
and esql needs to be in the path. The vm.h #define
.B INFORMIXDIR
needs to have the same value as the host path, and the
.B VOLMANDB
#define must be set to the location of the database. 
For example, if the database is called
.I volman
and resides in
.I /usr/mss/lib/volman/dbase,
.B VOLMANDB
would be
.I /usr/mss/lib/volman/dbase/volman.

Dbtrans is run once before starting the volume manager. Just make sure the
database paths in vdmlib.h are correct, then run the program.
.R
.NH 1
Man Pages
.PP
.NH 2
Old man pages
.PP
In cases where volman functions replace those of the UTS tpdaemon, the old man
pages should refer the user to the new system. 
Simple pages which do this are provided 
for tape(1), tape(8), tapemt(1M), tpdaemon(1M) and tapevary(1M). An improved
tape(7) page has also been provided. The label(1M) utility has been modified
and renamed vlabel(1M) and vwlabel(1M).
.NH 2
New man pages
.PP
In the complete NAStore release, the man pages are with the other NAStore
man pages in /usr/src/mann/mss/ and should be installed automatically
when the system is built. In the seperate Volume Manager release, the
man pages should be in a man/ subtree, and installation is left to the
site.  The man pages are:
vol(1), volmv(1), volalloc(1), vrecycle(1), vls(1), 
vchmod(1), vchown(1), vchgrp(1), 
vaudit(1M), vlabel(1M), vwlabel(1M), vquota(1m),
volstat(1M), voldaemon(1M), volvary(1M), volentdb(1M), 
voldeldb(1M), volmoddb(1M), rcerr(1M) and volman(8).
.R
.NH 1
ACS Robot
.PP
See the NAS \f2\*(ac Manual\f1: \s-1APPENDIX A: SETUP NOTES.\s0
.NH 1
Step-by-step Setup
.PP
.RS
.IP 1.
Create an account dedicated to the \*(vm, e.g.
``volman.''
This account will be used during setup to compile the code 
and create the database.
After setup, it will become the voldaemon console,
i.e. the voldaemon will broadcast its operator messages to 
volman logins and the account will have privileges to run operator utilities.
The messages the voldaemon broadcasts include errors and
requests to vary on devices.
It is better not to use an old account for this purpose.
This is an administrative account and its home directory could be the
source directory or spool directory.
.IP 2.
Do you want mount requests to go to a different account than the main
one? How about \*(ac log messages?
You can have separate accounts for receiving mount 
requests for different kinds of device for each location,
or you may choose to use the volman
account for these messages. If you want mount requests and/or \*(ac log messages
to go to one or more accounts other than the volman one, 
create these account(s) now.
.IP 3.
(Skip if not converting an old Informix database.)
Now configure the volman account to use INFORMIX. First, 
find out the correct informix path for your system. (In this example, it is
.I /usr/local/informix.)
Then, editing the .login file, add  the line
``setenv INFORMIXDIR /usr/local/informix'' 
and add ``/usr/local/informix/bin'' to the path list.
.IP 4.
Modify vm.h if necessary.
This is where to make any changes to SPOOLDIR, NODEDIR, INFORMIXDIR,
SQLEXEC, VOLMANDB, ACSRC, and ERORRLOG.
SQLEXEC will point to either sqlexec or sqlturbo depending on whether
you are running turbo Informix. If non-turbo, VOLMANDB will be set
to the pathname of the database directory without the .dbs extension;
with turbo, it should just be set to ``volman''. 
.IP 5.
Where do you want mount and error messages to go (see 2.)?
Look at syslog.conf in the \f2volman/syslog\f1 source directory, then
edit your syslogd(1M) configuration file to set up the facilities
for logging and the accounts they will log to. Then edit
.I vmrctab.c,
setting the syslog facilities in the vRCTab[] RC definitions, and
replace the entries of VOLMANACCT in the login name fields
with different account(s) if desired.
.IP 6.
Modify the Makefile if necessary.
This is where to make any changes to
LIBDIR, BINDIR, USRLIBDIR, ETCDIR, and VOLMANACCT.
Changes to LIBDIR should be reflected in shell variables in the 
acs :startacs and probelmu scripts. The probelmu script's LMUPATH
must also agree with the one in nasa.h, which as delivered points
to a file in the LIBDIR. probelmu also has a list of alternative
lmu ports that should be configured for the system.
.IP 7.
As root, type ``make creatlib.''
This creates the library directory.
.IP 8.
Create a version of the RCCONF file describing your configuration
(use the sample version as a guide) and copy it into the library directory.
.IP 9.
Type ``make all''
This will create all the binaries. The dbtrans utility (only needed
for converting from an old Informix volman database) is only made
by specific request.  If the compile of it fails because
.I esql
can't be found, the INFORMIXDIR path in the Makefile may be wrong. If this
is the case, check that INFORMIXDIR in vm.h corresponds: it should be
a string, e.g. ``INFORMIXDIR=/usr/local/informix''.
.IP 10.
(This step is relevant when only the Volume Manager is being installed
without the rest of the NAStore release.)
Remove old UTS tape-related binaries and replace \f2man\f1
pages as follows: cd to /usr/src/amdahl/cmd/tape and edit tape.mk, 
deleting all /f2make/f1 entries except for the \f2tm\f1(1) utility.
Delete the binaries themselves from /usr/bin/amdahl - this is
particularly important for the \f2label\f1 utility, which can
cause database discrepancies. Replace the /usr/src/man/amdahl
\f2man\f1 pages corresponding to the deleted utilities with the 
ones in volman/man/amdahl, and install the other volman/man pages somewhere.
.IP 11.
As root, type ``make install''
to copy the binaries to their various destinations;
they are \fIchown\fRed and \fIchmod\fRed as necessary.
.IP 12.
Now for the \*(ac setup. 
See the NAS \f2\*(ac Manual\f1: \s-1APPENDIX A: SETUP NOTES.\s0
.IP 13.
There are three Repository Controllers provided: manual
3480 tape and 3420 tape (they use the same binary, but run as
separate processes) and the \*(ac robot. Now is the time to give them drives. 
The drives have nodes in \f2/dev/rmt\f1, and the \*(RCs find out about
them from the RCCONF file in the library directory. Copy the RCCONF file
from the source directory and add drives to it per the format described
at the beginning of the file.
.IP 13.
Bring down the \fItpdaemon\fR(1M) and move the binary,
then invoke the voldaemon as root or the volman account
and ``tail -f ErrorLog'' (in the spool directory) to monitor its progress.
.IP 14.
Once the \f2voldaemon\f1 is working, it's time to substitute it for
the \f2tpdaemon\f1(1M).
Disable
.I tpdaemon
by removing the following lines in
.I /etc/local.rc:
.DS

	if [ "`vmid`" = native ]; then
		/etc/tpdaemon
	else
	#
	# start tape daemon which sends messages to VM user TAPEOPER.
	# If you wish to use the Waterloo mods for VM, change this line to
	# /etc/tpdaemon -v -m
	#
		/etc/tpdaemon -v

		/usr/amdahl/bin/spoolvary on /dev/printer00e
		/usr/amdahl/bin/spoolvary on /dev/punch00d
	f\&i

.DE
Insert these lines:
.DS

	echo "Starting syslogd and voldaemon and volvarying on ACS drives"
	/etc/syslogd
	(sleep 1 ; /etc/voldaemon; sleep 5; /usr/mss/bin/volvary on -rACSRC)&
.DE
Add these lines in
.I /etc/shutdown
before process accounting is stopped (already provided in complete
NAStore release):
.DS
        /usr/lib/cronshut && echo "Cron stopped."
	if /etc/vshutdown "System shutdown."
		then    echo "Volume manager shut down."
		else    echo "VOLDAEMON SHUTDOWN FAILURE - SEE LOG"
	fi
	/etc/acsdbg s
	echo "ACS server shutdown sent"
	/usr/lib/acct/shutacct
	echo "Process accounting stopped."
.DE
.fi
.IP 15.
What about volumes? The database has none when it is created. The
\f2volentdb\f1(1M) utility can be used to enter user volumes
in the vault as ALLOC/rw-r--r- belonging to the volman account,
and they can be \f2vchown\f1(1)'d to their owners if desired.
If there are unknown volumes in the \*(ac, an inventory can be performed
(see \*(ac Config.ms).
A list of \*(ac volumes can 
be generated and entered into the database with \f2volentdb\f1.
VIRGIN volumes can be converted to SCRATCH using the
.I scratchvol
script.
.RE MISC NOTES
(On UTS 2.1, the volman/syslog version is used
and the relevant man pages are consulted on other systems).