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>
![[BACK]](/icons/back.gif){kind=icon}
Return to Config.ms CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / othersrc / nastore / volman