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

Annotation of othersrc/nastore/volman/Config.ms, Revision 1.1.1.1

1.1       wrstuden    1: .\" Process this file through nroff -ms
                      2: .\"
                      3: .ds OUT OF DATE
                      4: .ds vm Volume Manager
                      5: .ds rp \fBvoldaemon\fR
                      6: .ds RC \s-1RC\s0
                      7: .ds ac \s-1ACS\s0
                      8: .TL
                      9: NAStore \*(vm Setup Notes
                     10: .AU
                     11: Bill Ross
                     12: Jonathan Hahn
                     13: .NH
                     14: Introduction
                     15: .PP
                     16: This document is an overall description of the \*(vm and its
                     17: components in view of the configuration parameters that need
                     18: to be set and the directories that need to be created in order
                     19: to install and start it. A step-by-step procedure for installing
                     20: and bringing up the \*(vm is in the last section.
                     21: .NH 1
                     22: Overall Description
                     23: .PP
                     24: The \*(vm is a system for managing removable volumes.
                     25: Its initial support was for round (3420) and square (3480)
                     26: manually-mounted tapes and the StorageTek 4400 Automated Cartridge
                     27: System (\*(ac). It was designed to be easily upgraded for future
                     28: forms of storage, in that the server (Repository Controller, or RC)
                     29: for a particular type of medium (and mounting protocol) can be written
                     30: and added to the configuration without basic redesign of the central
                     31: volume management code. A prototype RC is provided (rc/proto/) which
                     32: was adapted without much change to form the basis of a fairly
                     33: generic, vault-protocol manual Repository Controller (rc/vault/),
                     34: which optionally interfaces across the net with a database server,
                     35: which in turn optionally connects with the cradle of a bar-code
                     36: reading gun device (all code included). The prototype RC was also
                     37: adapted to communicate with a StorageTek robot controller (rc/acs/).
                     38: The RCs are configured in vm_rctab.c, and their drives are listed
                     39: in the RCCONF file, traditionally placed in /usr/mss/lib/volman/.
                     40: The ACS RC configuration files are described in rc/acs/.
                     41: .PP
                     42: Operators get messages via syslog(3) broadcasts to login names which
                     43: are configured in the Makefile (VOLMANACCT) and in vm.h (RCs); various
                     44: directories, e.g. for logging and database files, are also defined in
                     45: Makefile and vm.h. The database has information on volumes (e.g.
                     46: ownership and access privileges) and user quotas, if any.
                     47: The database is created automatically on initial startup,
                     48: provided the directory defined for it exists.
                     49: .NH 1
                     50: Directories
                     51: .PP
                     52: The
                     53: .I "source directory"
                     54: is where the distribution tape is read in and
                     55: is a working area for building the \*(vm binaries.
                     56: Some parts are copied into other directories, but most of the files
                     57: (primarily source files) exist only in the source directory.
                     58: .PP
                     59: The
                     60: .I "spool directory"
                     61: contains transient files associated with the operation of the \*(vm.
                     62: These files include an event/error log as well as FIFOs (inter-process
                     63: communication ports) if this IPC method is chosen in the Makefile.
                     64: An acs subdirectory contains \*(ac state information.
                     65: .I Spool
                     66: is a bit of a misnomer here as there is no spooling going on
                     67: (\*`a la line printers) but
                     68: .I /usr/spool
                     69: is the most appropriate place for this directory.
                     70: The spool directory is
                     71: .I /usr/spool/mss/volman
                     72: in the default configuration.
                     73: .PP
                     74: The
                     75: .I "library directory"
                     76: contains non-transient files associated with the operation of the \*(vm.
                     77: These include the \*(vm database directory, configuration files, and binaries.
                     78: The database is default-configured to be in the
                     79: .B dbase
                     80: subdirectory.  The configuration files include
                     81: .B RCCONF
                     82: (the device configuration file) and
                     83: .B acs/ACSCONF
                     84: (the \*(ac configuration file).  Binaries include:
                     85: .B vaultrc
                     86: (the manual tape repository controller),
                     87: .B acsrc
                     88: (the \*(ac controller when present),
                     89: .B voltimer
                     90: (the \*(vm system timer).
                     91: Also included are administrative utilities such as
                     92: .B volentdb
                     93: and
                     94: .B voldeldb.
                     95:
                     96: The installer may want to put the admin utilities
                     97: in a more accessible directory.  The utilities in the library directory
                     98: are not typically invoked by ordinary users and are intended to be called
                     99: from other programs and by the system administrator.
                    100: The library directory is
                    101: .I /usr/mss/lib/volman
                    102: in the default configuration.
                    103: .PP
                    104: User-accessible binaries are installed in a bin directory and
                    105: manual pages in a man directory.  These are respectively
                    106: .I /usr/mss/bin
                    107: and
                    108: .I /usr/mss/man
                    109: in the default configuration.
                    110: .NH 1
                    111: Administrative Binaries
                    112: .PP
                    113: \*(rp* is the \*(vm daemon.
                    114: .FS
                    115: The \*(rp is sometimes called the ``RP'' or Request Processor
                    116: for historical reasons.
                    117: .FE
                    118: This program should be invoked at boot time, probably from an
                    119: \fI/etc/rc\fR-type file.  \*(rp puts itself into the background.
                    120: It should never die, but if it does
                    121: it can be restarted manually by root or the \*(vm operator account.
                    122: If the \*(rp is invoked while another is already running,
                    123: the new one will terminate itself.  In the default configuration,
                    124: \*(rp lives in /etc along with
                    125: .B vshutdown,
                    126: the program which brings the \*(vm down.
                    127: .PP
                    128: The \*(RCs are the repository controllers.  Each \*(RC provides the
                    129: interface between the \*(rp and a physical volume repository
                    130: (e.g.: the \*(ac, the manual round tapes and the manual 3480 square tapes).
                    131: A repository is defined as a [location, medium] pair.
                    132: The \*(rp invokes \*(RCs when it begins execution according to the table in
                    133: .I vmrctab.c
                    134: described below.
                    135: The \*(RCs supplied are
                    136: .I vaultrc,
                    137: the manual repository controller (a process is created for both 3480s and
                    138: 3420s in the default configuration) and
                    139: .I acsrc
                    140: for the \*(ac.
                    141: .NH 1
                    142: User-accessible Binaries
                    143: .PP
                    144: .B
                    145: vreserve, vol, volmv, volstat,
                    146: vls, vchmod, vchown, vchgrp, vquota, volvary,
                    147: volalloc, vrecycle, vlabel, vwlabel
                    148: .R
                    149: .PP
                    150: Note that the
                    151: .B vlabel
                    152: and the
                    153: .B vwlabel
                    154: link to it must supplant any existing labeling command
                    155: (e.g. under UTS see \f2label\f1(1)). The old command should be made
                    156: unavailable since it can result in database inconsistencies (see below).
                    157: All other utilities are new and are not known to conflict with
                    158: existing names in Unix, but the careful administrator will check for
                    159: overlap.  All utilities are documented in the man pages.
                    160: .NH 1
                    161: User-accessible Libraries
                    162: .PP
                    163: There is one library archive called
                    164: .B libvol.a.
                    165: This is used to create programs which interact with the \*(vm
                    166: and should be placed in a user-accessible library directory such as
                    167: .I /usr/lib.
                    168: .NH 1
                    169: Consoles
                    170: .PP
                    171: The \*(vm broadcasts status information to one or more consoles:
                    172: The consoles used are assigned by LOG_LOCALx (on UTS: LOG_USERx) codes
                    173: according to the host's syslog convention, which are used in vm_log.c
                    174: and vm_rctab.c. These codes correspond to userX entries in the syslog(3)
                    175: /etc/syslog.conf file, e.g. for LOG_LOCAL0 and LOG_LOCAL1 in the
                    176: default configuration, these entries belong in syslog.conf:
                    177: .nf
                    178:
                    179: # volman RP console
                    180: #
                    181: local0.notice                                   volman
                    182: #
                    183: # acsrc lcl console
                    184: #
                    185: local1.notice                                   acs
                    186:
                    187: .fi
                    188: There is one console associated with the
                    189: .B voldaemon
                    190: (LOG_USER0) and optionally one console for each \*(RC.
                    191: It is OK to use one console for all \*(RCs. Also, each console
                    192: can cause broadcasts to several accounts per the definition in
                    193: /etc/syslog.conf. A hacked syslog facility was prepared for UTS
                    194: and can be found is volman/syslog/.
                    195: .NH 1
                    196: Configuration Parameters
                    197: .PP
                    198: This section describes the parameters (and their locations)
                    199: which may need to be considered and possibly changed by the installer.
                    200: .NH 2
                    201: vm.h
                    202: .PP
                    203: The parameters in this file are all manifest constants.
                    204: Some are intended to be reconfigured; however, the first
                    205: block contains fundamental constants which should not be changed.
                    206: Some constants are turned on if
                    207: .B DEBUG
                    208: is enabled in the Makefile and can be ignored otherwise.
                    209: .PP
                    210: .B SPOOLDIR
                    211: is the path to the spool directory described above.
                    212: .B NODEDIR
                    213: corresponds to
                    214: .I /dev/tape
                    215: in
                    216: .I tpdaemon(1M).
                    217: Some utilities (e.g. IBR) may require that this directory be
                    218: .I /dev/tape.
                    219: However, note that both the \*(vm and the
                    220: .I tpdaemon(1M)
                    221: clear this directory when they start up,
                    222: and this can lead to major operational problems if both are run concurrently.
                    223: .PP
                    224: .B VOLMANDB
                    225: contains the location and name of the database,
                    226: .B ACSRC
                    227: contains the name for the \*(ac Server program.  (If ACSRC is not #defined,
                    228: the code should compile without it configured.) In the
                    229: .B sandbox
                    230: configuration, these are
                    231: .I /usr/mss/lib/volman/dbase/volman,
                    232: and
                    233: .I acssrvr,
                    234: respectively.
                    235: .PP
                    236: See ``Database Considerations''
                    237: below for information about
                    238: .B INFORMIXDIR,
                    239: .B SQLEXEC
                    240: and
                    241: .B VOLMANDB
                    242: (these are only relevant for conversion from old beta release databases).
                    243: .B ERRORLOG
                    244: is the name of the error/event log file in the
                    245: .B SPOOLDIR.
                    246: .NH 2
                    247: Makefile
                    248: .PP
                    249: The parameters in this file are simliar to those in
                    250: .I vm.h,
                    251: but are needed here for installation.
                    252: .B "LIBDIR, BINDIR, USRLIBDIR"
                    253: and
                    254: .B ETCDIR
                    255: are the paths to the library directory,
                    256: user binary directory, user library (as in C archive libraries),
                    257: and /etc directory respectively.
                    258: .B VOLMANACCT
                    259: is the name of the \*(vm operator account.
                    260: .NH 2
                    261: vmrctab.c
                    262: .PP
                    263: This file contains the \*(RC configuration table, called
                    264: .B vRCTab[\|]
                    265: and the
                    266: .B movetable[\|]
                    267: array which specifies which RC-RC moves are legal.
                    268: The only simple configurable parameters here are the
                    269: vRCTab \*(RC console accounts
                    270: and the syslog facilities. The console accounts are used for permission
                    271: checking. The
                    272: The manual RCs are currently set to
                    273: .B VOLMANACCT
                    274: which is the
                    275: .I volman
                    276: account (defined in Makefile) and the ACS account is set to ``acs.''
                    277: The syslog facility for the manual RCs is LOG_USER0 (same as the
                    278: voldaemon console) and the ACS is LOG_USER1. The meanings
                    279: of these symbols are described in the previous section.
                    280: .NH 2
                    281: RCCONF
                    282: .PP
                    283: This file contains one line for each device in the system and associates
                    284: each device with an \*(RC.
                    285: It is read each time the \*(vm begins execution.
                    286: The layout of the file is described in the comments at the top
                    287: in the sample version located in the source directory.
                    288: .B
                    289: Note: this file must be set up before the \*(vm can be operated.
                    290: .R
                    291: .NH 1
                    292: Database Considerations
                    293: .PP
                    294: The database of the moment is Hunter and Associates' BPLUS btree
                    295: index package. The code is in /usr/src/mss/bplus.
                    296: .PP
                    297: This paragraph can be skipped if an old-style Informix database
                    298: does not need to be converted to the new form.
                    299: The dbtrans.ec source file incorporates Informix/esql database
                    300: code, which requires `esql' in place of `cc' for compilation. This is
                    301: reflected in the Makefile. For the Makefile to work, the INFORMIXDIR
                    302: environment needs to be set to the location of Informix in the filesystem,
                    303: and esql needs to be in the path. The vm.h #define
                    304: .B INFORMIXDIR
                    305: needs to have the same value as the host path, and the
                    306: .B VOLMANDB
                    307: #define must be set to the location of the database.
                    308: For example, if the database is called
                    309: .I volman
                    310: and resides in
                    311: .I /usr/mss/lib/volman/dbase,
                    312: .B VOLMANDB
                    313: would be
                    314: .I /usr/mss/lib/volman/dbase/volman.
                    315:
                    316: Dbtrans is run once before starting the volume manager. Just make sure the
                    317: database paths in vdmlib.h are correct, then run the program.
                    318: .R
                    319: .NH 1
                    320: Man Pages
                    321: .PP
                    322: .NH 2
                    323: Old man pages
                    324: .PP
                    325: In cases where volman functions replace those of the UTS tpdaemon, the old man
                    326: pages should refer the user to the new system.
                    327: Simple pages which do this are provided
                    328: for tape(1), tape(8), tapemt(1M), tpdaemon(1M) and tapevary(1M). An improved
                    329: tape(7) page has also been provided. The label(1M) utility has been modified
                    330: and renamed vlabel(1M) and vwlabel(1M).
                    331: .NH 2
                    332: New man pages
                    333: .PP
                    334: In the complete NAStore release, the man pages are with the other NAStore
                    335: man pages in /usr/src/mann/mss/ and should be installed automatically
                    336: when the system is built. In the seperate Volume Manager release, the
                    337: man pages should be in a man/ subtree, and installation is left to the
                    338: site.  The man pages are:
                    339: vol(1), volmv(1), volalloc(1), vrecycle(1), vls(1),
                    340: vchmod(1), vchown(1), vchgrp(1),
                    341: vaudit(1M), vlabel(1M), vwlabel(1M), vquota(1m),
                    342: volstat(1M), voldaemon(1M), volvary(1M), volentdb(1M),
                    343: voldeldb(1M), volmoddb(1M), rcerr(1M) and volman(8).
                    344: .R
                    345: .NH 1
                    346: ACS Robot
                    347: .PP
                    348: See the NAS \f2\*(ac Manual\f1: \s-1APPENDIX A: SETUP NOTES.\s0
                    349: .NH 1
                    350: Step-by-step Setup
                    351: .PP
                    352: .RS
                    353: .IP 1.
                    354: Create an account dedicated to the \*(vm, e.g.
                    355: ``volman.''
                    356: This account will be used during setup to compile the code
                    357: and create the database.
                    358: After setup, it will become the voldaemon console,
                    359: i.e. the voldaemon will broadcast its operator messages to
                    360: volman logins and the account will have privileges to run operator utilities.
                    361: The messages the voldaemon broadcasts include errors and
                    362: requests to vary on devices.
                    363: It is better not to use an old account for this purpose.
                    364: This is an administrative account and its home directory could be the
                    365: source directory or spool directory.
                    366: .IP 2.
                    367: Do you want mount requests to go to a different account than the main
                    368: one? How about \*(ac log messages?
                    369: You can have separate accounts for receiving mount
                    370: requests for different kinds of device for each location,
                    371: or you may choose to use the volman
                    372: account for these messages. If you want mount requests and/or \*(ac log messages
                    373: to go to one or more accounts other than the volman one,
                    374: create these account(s) now.
                    375: .IP 3.
                    376: (Skip if not converting an old Informix database.)
                    377: Now configure the volman account to use INFORMIX. First,
                    378: find out the correct informix path for your system. (In this example, it is
                    379: .I /usr/local/informix.)
                    380: Then, editing the .login file, add  the line
                    381: ``setenv INFORMIXDIR /usr/local/informix''
                    382: and add ``/usr/local/informix/bin'' to the path list.
                    383: .IP 4.
                    384: Modify vm.h if necessary.
                    385: This is where to make any changes to SPOOLDIR, NODEDIR, INFORMIXDIR,
                    386: SQLEXEC, VOLMANDB, ACSRC, and ERORRLOG.
                    387: SQLEXEC will point to either sqlexec or sqlturbo depending on whether
                    388: you are running turbo Informix. If non-turbo, VOLMANDB will be set
                    389: to the pathname of the database directory without the .dbs extension;
                    390: with turbo, it should just be set to ``volman''.
                    391: .IP 5.
                    392: Where do you want mount and error messages to go (see 2.)?
                    393: Look at syslog.conf in the \f2volman/syslog\f1 source directory, then
                    394: edit your syslogd(1M) configuration file to set up the facilities
                    395: for logging and the accounts they will log to. Then edit
                    396: .I vmrctab.c,
                    397: setting the syslog facilities in the vRCTab[] RC definitions, and
                    398: replace the entries of VOLMANACCT in the login name fields
                    399: with different account(s) if desired.
                    400: .IP 6.
                    401: Modify the Makefile if necessary.
                    402: This is where to make any changes to
                    403: LIBDIR, BINDIR, USRLIBDIR, ETCDIR, and VOLMANACCT.
                    404: Changes to LIBDIR should be reflected in shell variables in the
                    405: acs :startacs and probelmu scripts. The probelmu script's LMUPATH
                    406: must also agree with the one in nasa.h, which as delivered points
                    407: to a file in the LIBDIR. probelmu also has a list of alternative
                    408: lmu ports that should be configured for the system.
                    409: .IP 7.
                    410: As root, type ``make creatlib.''
                    411: This creates the library directory.
                    412: .IP 8.
                    413: Create a version of the RCCONF file describing your configuration
                    414: (use the sample version as a guide) and copy it into the library directory.
                    415: .IP 9.
                    416: Type ``make all''
                    417: This will create all the binaries. The dbtrans utility (only needed
                    418: for converting from an old Informix volman database) is only made
                    419: by specific request.  If the compile of it fails because
                    420: .I esql
                    421: can't be found, the INFORMIXDIR path in the Makefile may be wrong. If this
                    422: is the case, check that INFORMIXDIR in vm.h corresponds: it should be
                    423: a string, e.g. ``INFORMIXDIR=/usr/local/informix''.
                    424: .IP 10.
                    425: (This step is relevant when only the Volume Manager is being installed
                    426: without the rest of the NAStore release.)
                    427: Remove old UTS tape-related binaries and replace \f2man\f1
                    428: pages as follows: cd to /usr/src/amdahl/cmd/tape and edit tape.mk,
                    429: deleting all /f2make/f1 entries except for the \f2tm\f1(1) utility.
                    430: Delete the binaries themselves from /usr/bin/amdahl - this is
                    431: particularly important for the \f2label\f1 utility, which can
                    432: cause database discrepancies. Replace the /usr/src/man/amdahl
                    433: \f2man\f1 pages corresponding to the deleted utilities with the
                    434: ones in volman/man/amdahl, and install the other volman/man pages somewhere.
                    435: .IP 11.
                    436: As root, type ``make install''
                    437: to copy the binaries to their various destinations;
                    438: they are \fIchown\fRed and \fIchmod\fRed as necessary.
                    439: .IP 12.
                    440: Now for the \*(ac setup.
                    441: See the NAS \f2\*(ac Manual\f1: \s-1APPENDIX A: SETUP NOTES.\s0
                    442: .IP 13.
                    443: There are three Repository Controllers provided: manual
                    444: 3480 tape and 3420 tape (they use the same binary, but run as
                    445: separate processes) and the \*(ac robot. Now is the time to give them drives.
                    446: The drives have nodes in \f2/dev/rmt\f1, and the \*(RCs find out about
                    447: them from the RCCONF file in the library directory. Copy the RCCONF file
                    448: from the source directory and add drives to it per the format described
                    449: at the beginning of the file.
                    450: .IP 13.
                    451: Bring down the \fItpdaemon\fR(1M) and move the binary,
                    452: then invoke the voldaemon as root or the volman account
                    453: and ``tail -f ErrorLog'' (in the spool directory) to monitor its progress.
                    454: .IP 14.
                    455: Once the \f2voldaemon\f1 is working, it's time to substitute it for
                    456: the \f2tpdaemon\f1(1M).
                    457: Disable
                    458: .I tpdaemon
                    459: by removing the following lines in
                    460: .I /etc/local.rc:
                    461: .DS
                    462:
                    463:        if [ "`vmid`" = native ]; then
                    464:                /etc/tpdaemon
                    465:        else
                    466:        #
                    467:        # start tape daemon which sends messages to VM user TAPEOPER.
                    468:        # If you wish to use the Waterloo mods for VM, change this line to
                    469:        # /etc/tpdaemon -v -m
                    470:        #
                    471:                /etc/tpdaemon -v
                    472:
                    473:                /usr/amdahl/bin/spoolvary on /dev/printer00e
                    474:                /usr/amdahl/bin/spoolvary on /dev/punch00d
                    475:        f\&i
                    476:
                    477: .DE
                    478: Insert these lines:
                    479: .DS
                    480:
                    481:        echo "Starting syslogd and voldaemon and volvarying on ACS drives"
                    482:        /etc/syslogd
                    483:        (sleep 1 ; /etc/voldaemon; sleep 5; /usr/mss/bin/volvary on -rACSRC)&
                    484: .DE
                    485: Add these lines in
                    486: .I /etc/shutdown
                    487: before process accounting is stopped (already provided in complete
                    488: NAStore release):
                    489: .DS
                    490:         /usr/lib/cronshut && echo "Cron stopped."
                    491:        if /etc/vshutdown "System shutdown."
                    492:                then    echo "Volume manager shut down."
                    493:                else    echo "VOLDAEMON SHUTDOWN FAILURE - SEE LOG"
                    494:        fi
                    495:        /etc/acsdbg s
                    496:        echo "ACS server shutdown sent"
                    497:        /usr/lib/acct/shutacct
                    498:        echo "Process accounting stopped."
                    499: .DE
                    500: .fi
                    501: .IP 15.
                    502: What about volumes? The database has none when it is created. The
                    503: \f2volentdb\f1(1M) utility can be used to enter user volumes
                    504: in the vault as ALLOC/rw-r--r- belonging to the volman account,
                    505: and they can be \f2vchown\f1(1)'d to their owners if desired.
                    506: If there are unknown volumes in the \*(ac, an inventory can be performed
                    507: (see \*(ac Config.ms).
                    508: A list of \*(ac volumes can
                    509: be generated and entered into the database with \f2volentdb\f1.
                    510: VIRGIN volumes can be converted to SCRATCH using the
                    511: .I scratchvol
                    512: script.
                    513: .RE MISC NOTES
                    514: (On UTS 2.1, the volman/syslog version is used
                    515: and the relevant man pages are consulted on other systems).

CVSweb <webmaster@jp.NetBSD.org>