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.
! 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
! 179: # volman RP console
! 180: #
! 181: local0.notice volman
! 182: #
! 183: # acsrc lcl console
! 184: #
! 185: local1.notice acs
! 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.
! 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
! 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
! 473: /usr/amdahl/bin/spoolvary on /dev/printer00e
! 474: /usr/amdahl/bin/spoolvary on /dev/punch00d
! 475: f\&i
! 477: .DE
! 478: Insert these lines:
! 479: .DS
! 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).