[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     ! 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>