\documentstyle[a4,12pt]{article} \begin{document} \author{APM Manual pages} \title{Filestore System Manager's Guide} \maketitle \parskip .1 in \setcounter{secnumdepth}{10} \parindent 0in \section{preamble} Written and revised by JGH and JHB between April 1985 and October 1986 Revised by RWT in March 1987 This document describes the facilities which exist for managing the Edinburgh University Department of Computer Science's network Filestores. An overview of the system can be found in "The Filestore" [1], "The New Filestore" [2], and readers of this document are assumed to be familiar with the basic operating system commands described in "The APM working notes" [3]. The facilities described in this document were mainly written by George Ross, Rainer Thonnes and John Butler, with some revisions by Gordon Hughes and John Butler \section{Introduction} The filestore manager is assummed to be familiar with the basic commands on the system, but the following is a brief overview of the ones which are required. The user must be logged on to the filestore using the command L. Some management information (such as file use statistics) is unprotected and anyone may read it, but other information may be protected, and certain administrative operations require special privilege, and in this case the "system password" must be quoted (when or after logging on). It is desirable that people who are going to do privileged operations, log in as themselves (rather than generic user names such as MANAGR), since these operations are logged on the system console, and if the name of the person making the change is present, then this is more useful. If the person wishing to do a privileged operation is already logged in, they can use the command QUOTE to quote the system password, without the need to log in again. Users should note that while they have logged in, or quoted the system password, they have 'owner' authority on all the directories on the filestore, and should be careful in the use of commands which affect other users' files. Some of the programs, (notably the ADMIN program) were written assuming that the user has set his current directory to be MANAGR. This should be done by using the command SET before the ADMIN program is entered. \subsection*{References} [1] "The Filestore", Dewar et al, Internal report. Aug 1983 [2] "The New Filestore", Ross, Internal report. Jun 1984 [3] "The APM Working notes", Tansley, Internal report. May 1983 \section{System Wide Administration} The following commands control the filestore on a system wide basis. If the user is not logged on as MANAGR, they can all be run from other directories by appending MANAGR: to the command verb. The commands all fail if the user is not privileged. The command USERS shows any privileged users by printing an exclaimation mark after their username in the output. \subsection{ACCESS} The ACCESS command is used to control who can currently use the filestore. The command take a string as parameter which should be one of the following - \begin{description} \item[NONE] prohibit connects and logins (except using system pass) \item[SYSPASS] allow connects, prohibit logins (except using system pass) \item[ALL] allow connects and logins \end{description} If the above strings cannot be remembered the command ACCESS ? may be used to remind the user of the options. \subsection{REBOOT} The reboot command causes the filestore machine to reboot itself. Note that the machine having issued the command (as well as any other machine which were talking to the filestore at the time) will also need to be re-booted. \subsection{SYSPASS} This command allows the system manager to set a new system password. The new password is not echoed, and must be typed twice to avoid typing errors. It is good policy to change the system password at regular random intervals. \section{Individual User Administration} The control of invividual user quotas, and user accreditation is controlled by the single program, ADMIN. There are two aspects to ADMIN. One is to allow the system manager to issue commands to the filestore for user administation, and the other is to maintain a data base of users, on all the filestores. Within the admin program the commands listed below are available. The command words may be abbreviated to single letters. \subsection{H(elp)} This command prints out a three line summary of the commands available and their expected parameters. \subsection{D(efault) $<$part$>$ $<$quota$>$ $<$prot$>$} The system has defaults for the partition, quota, and protection which any new users created inherit. The defaults are printed when the ADMIN program is first entered, and if alternatives are desired, these must be set before the use of the Create command. The appendices at the back of this document should be used as the basis of the choice of partition. It is often useful to check the ammount used in each partition (by FSTATS) before the ADMIN program is entered. The default quota (2000 blocks tends to be sufficient. The default protection (FRA) is OK for research workers and staff, but a more strict protection such as FNA is suggested for students. (The Filestore document describes the significance of these protection fields). \subsection{C(reate) $<$owner$>$ } This command is used to create users on the filestore. The manager is then prompted for information for the user database. \subsection{K(ill) $<$owner$>$ } This command is used to delete a user from the filestore, and also removes them from the administative database. Before a user is deleted, their directory on the filestore must be empty. This must be done before the ADMIN program is entered. \subsection{N(ewname) $<$owner$>$ $<$new$>$ } This command is used to rename users. (I (who?) am dubious about how this affects the database!) \subsection{Q(uota) $<$owner$>$ $<$inc$>$ } This command allows a users quote to be changed. The manager specifies an increment to the existing quota. The increment can be negative! It is a good idea to keep the users' quotas below 32000 blocks. \subsection{P(ass) $<$owner$>$ $<$pass$>$ } This allows a privileged user to change another users password, without the need to log on as the user with the system pass, and have to quote the system pass a number of times when using the PASS command as that user. \subsection{F(ind) $<$owner$>$ } This command can be used to look for users on the filestore. It also reports whether the directory contains any files and the current quota in the case of a single user, or simply lists the matching database entries if the user name contains a wildcard (*). \subsection{R(egister) $<$part$>$ $<$file$>$} This command lists all the users of the partition specified. If the $<$file$>$ parameter is omitted, the output is sent to the users terminal. \subsection{L(ist) $<$file$>$} This command lists all of the users of all the partitions. If the $<$file$>$ parameter is omitted, the output is sent to the users terminal. \subsection{M(odify) $<$owner$>$ } This command enters a sub-command system which allows the manager to alter the database. (It does not require the user to be privileged) The sub-commands are - \begin{description} \item[(E)xit] Exit from the Mod option \item[(F)emale] Specified user is female (for 'her' room, etc.) \item[(G)roup] Allows the manager to specify a new group for the user. \item[(L)aser] The user is allowed to use the LASER command. \item[(P)renames] Allows the manager to specify a new pre-name string. \item[(S)urname] Allows the manager to specify a new surname string. \item[(T)rusted] Claims the user is Trusted, can be tested by program. \item[(V)ax] The user is also accredited to VAX. \end{description} \subsection{S(how) $<$name$>$ } This command shows the database for the surname specifed. This can contain wildcards (*). \subsection{T(idy)} This command is used to check the users which the filestore knows about against the users in the database and resolve any ambiguities by deleting or adding database users. \subsection{E(xit)} This command is used to leave the ADMIN program. If the user signals `end of input', the program is also terminated. After the program has terminated the file ADMIN.DAT should be EFTP'd to all other filestores on the network to keep the data-bases consistant. \section{Individual Machine administration} There is a proposal that there should be a database which covers machine configuration and locations which would be maintained by a program similar to ADMIN. This has not yet been implented. See, however NS.TXT. \section{Backing up the system} Selective Backups One of the parameters to the program is a list of directories to be done, which defaults to "*", but can be specified as a single directory, an explicit short list of directories (separated by commas but the whole list enclosed in double quotes), or an indirect list (specified as a filename prefixed with "@"). So if, for example, you want to back up all of CS4's directories, you simply place a list of their directory names into a file (one per line will do), and then, assuming the file is called CS4.DAT, give the following commands instead of the normal ones shown below as well: BACKUP XXX, @CS4.DAT / YYY \\ FULLBACKUP, @CS4.DAT / YYY \\ TOTALBACKUP, @CS4.DAT / YYY \\ instead of BACKUP XXX / YYY \\ FULLBACKUP / YYY \\ TOTALBACKUP / YYY \\ where YYY is the name of the log files to be used for this backup, and XXX is either the name of the previous backup log (in the case of incrementals) or an explicit threshold date enclosed in double quotes, supplied automatically in teh case of the FULL and TOTAL variants of the command. Note that in all cases you must supply a comma in front of the indirect filename. \section{Ether Administration} \subsection{CHOP} This does not work at present. \section{File Usage Information} \subsection{FSTATS $<$partition$>$ $<$mode$>$ $<$output$>$} Find out file statistics on the filestore. \begin{description} \item[-PARTITION=] can be used to restrict the output to one partition, default being to report on all partitions. \item[-OUTPUT=] can be used to output the results into a file. Default is the terminal. \end{description} mode can be (?one or more of..) \begin{description} \item[-FULL (or -NOFULL)] The default is that only a summary of the disk block usage is provided, and -FULL gives the file statistics for each user. \item[-HITLIST] Gives statistics in decreasing order of resources used i.e. the biggest users come first. \end{description} eg. \small \tt \begin{verbatim} } FSTATS Partition 0 has 50263 blocks (78.54%) used Partition 1 has 51962 blocks (81.19%) used Partition 2 has 41295 blocks (64.52%) used Partition 3 has 30458 blocks (47.59%) used Partition 4 has 35178 blocks (54.97%) used Partition 5 has 32611 blocks (50.95%) used Partition 6 has 24366 blocks (38.07%) used Partition 7 has 16926 blocks (26.45%) used Grand total of 283059 blocks (55.28%) used } FSTATS -PART=4 -FULL Partition 4 at 19.29 on 03/04/85 User Files Blocks Extents B/F E/F B/E -------------------------------------------------------------------- HIER 30 18238 30 607.9 1.0 607.9 NEWS 24 1345 48 56.0 2.0 28.0 NEWS_S 80 807 81 10.1 1.0 10.0 NPH 32 4052 33 126.6 1.0 122.8 T_1200 - - - - - - V_PIC 51 10736 51 210.5 1.0 210.5 -------------------------------------------------------------------- Totals 217 35178 243 162.1 1.1 144.8 Files Blocks Extents B/F E/F B/E \end{verbatim} \normalsize \rm \section{Bitmap Information} The command BITMAP is used to find out details of the filestore bit maps. The -PARTITION= qualifier can be used to restrict the output to one partition, and the -OUTPUT= qualifier can be used to output the results into a file. The defaults are that all partitions are scanned, and the results are output to the terminal. The other parameter is the mode of analysis, which can either be -USAGE, -HOLES, -MAP. The -USAGE qualifier is just the percentage of the bitmap which is not in use (ie. the same as FSTATS default output). The -HOLES qualifier gives the sizes of the holes in the bitmap, and the -MAP qualifier outputs a map of the bitmap using asterixes to indicate the state of the bits. eg. \small \tt \begin{verbatim} } BITMAP -USAGE Partition 0 has 50263 blocks (78.54%) used Partition 1 has 51962 blocks (81.19%) used Partition 2 has 41295 blocks (64.52%) used Partition 3 has 30458 blocks (47.59%) used Partition 4 has 35178 blocks (54.97%) used Partition 5 has 32611 blocks (50.95%) used Partition 6 has 24366 blocks (38.07%) used Partition 7 has 16926 blocks (26.45%) used Grand total of 283059 blocks (55.28%) used \end{verbatim} \normalsize \rm \} BITMAP -HOLES -PART=1 Hole analysis for partition 1 on 03/04/85 at 19.21 \small \tt \begin{verbatim} Size Count Size Count Size Count Size Count 356 1 211 1 192 1 154 1 127 1 126 1 90 1 85 1 79 1 72 1 70 1 66 1 65 1 59 1 55 1 52 1 45 1 44 1 42 1 41 1 40 2 39 5 38 1 37 6 36 4 35 8 34 5 33 9 32 38 31 34 30 23 29 12 28 10 27 12 26 8 25 11 24 12 23 10 22 11 21 11 20 21 19 12 18 11 17 11 16 8 15 6 14 6 13 12 12 18 11 21 10 13 9 13 8 15 7 18 6 25 5 27 4 33 3 42 2 66 1 97 \end{verbatim} \normalsize \rm \} BITMAP -MAP -PART=0 \small \tt \begin{verbatim} Partition 0: 78.536% used 0000: *********************************************************** **** 0040: ** ************************************************************ 0080: *********************************************************** **** 00C0: ** ***************************************** ********** ****** 0100: ******************** ************* *********************** *** etc. \end{verbatim} \normalsize \rm Note that the -MAP option produces a large amount of output! \section{General Utilities} \subsection{ADDBAD} Add bad blocks to the bad block list Utility prompts for block numbers to be added to the list. Terminate with block number $<$= 0 or end-of-input. \subsection{ARCHFILE} This utility scans one or all users and returns a count of the number of blocks marked for archive (Arch.) and vulnerable (Vuln.) A null parameter gives the totals for the current directory. '*' gives the totals for the entire filestore. \subsection{DELALL} Delete all files of the current directory. No parameters. For each file on the directory, this utility sets the permission to "FFV" then deletes the file. There are two interlocks \begin{enumerate} \item The utility will not delete the files of the current user. To use it you must SET across to the nominated directory. \item You will be asked to confirm ( 'Y' or 'y' ) that you really want to delete the files. \end{enumerate} \subsection{DUMPBAD} Dump the bad block list (Also held in :BADLIST) \subsection{LASTUSED} This command returns the date the first (most recent) file in the directory or directories was created or last written to. If the file is permitted to the calling user (or in practice if the calling user quotes the system password) then this should give a lower bound to when the directory was last used. No information is kept by the filestore about logons so this is the most accurate date available. '*' gives last use of all directories. \subsection{LPZAP} Kill the print job currently on the FS printer The calling directory is logged on the filestore console. The job will stop at the end of the current buffer i.e. not absolutely immediately. \subsection{SETPASS} This command sets the password on one or more directories. Parameter is the name of an input file or device. \subsection{SETTIME} Set new date and time. Takes either one or two parameters viz: SETTIME dd/mm/yy hh.mm or SETTIME hh.mm In the former case both the date and time will be changed, while in the latter case only the time will be changed. Anything invalid should be rejected. Spaces should be ignored. \section{Filestore console commands} \subsection{Filestore console log output} The console responds to the following commands (These are described more fully in [2]. \begin{tabbing} mmmmmmmmmmmmmmm\=mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm\kill Control+\_ \> Toggle the keyboard (default is it is disabled) \\ ? \> Report on the current FS status \\ B \> Baud rates of RS232 lines present \\ O \> cf. the ACCESS command above, 3 or 0 to close, -1 to open \\ Q \> Show Qsart status \\ S \> Show System buffers \\ T \> Set trace mode (default = 0) \\ W \> Set file system protect mode (default = 1, 0 =$>$ disk is r/o) \\ \end{tabbing} 0: read-only \\ 1: normal operation The filestore puts out regular timestamped statistics messages. The entries in the timestamp are: \begin{tabbing} mmmmm\=mmmmmmmmmmmmmm\kill FR \> file reads \\ FW \> file writes \\ DR \> directory reads \\ DW \> directory writes \\ DE \> disc errors \\ ER \> ether readsd \\ EW \> ether writes \\ EE \> ether errors \\ OO \> OK operations \\ EO \> operations which got an error response \\ LO \> logons \\ BHW \> buffer high-water mark \\ DHW \> disc queue high water mark (since last stamp) \\ DCH \> disc cache hits \\ DCM \> disc cache misses \\ DCF \> disc cache forgets \\ U \> active Unos \\ X \> active Xnos \\ P \> active ports \\ \end{tabbing} Anything which says "timeout" means exactly that. Disc and ether timeouts usually recover, but if they're repeated indefinitely you might need to reboot. QSart timeouts usually result in the interface being reset ("clobbering"). "Print...." means what it says. Generally speaking, if it rings the bell when you hit the space bar it's probably still live, otherwise it probably isn't. \section{The APM name server table} There is a very simple-minded table in MANAGR:NS.TXT giving basic details about APMs. The first line is a comment. The next 128 lines are indexed by APM station and give.. \begin{tabbing} mmm\=mmm\=mmmmmmmmmmmmmmmmmm\=mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm\kill \> The Ethernet. \>\>\> K for KB, A for A.T. etc.\\ \> The station number \>\>\> Hex\\ \> The APM case number \>\>\> On the metal plate on the side\\ \> The short name \>\>\> This is a seven-character name.\\ \> \>\>\> User machines begin with an '@'.\\ \> The location \>\>\> A room number or machine halls area.\\ \> The APM configuration\\ \> The long name modifier \>\>\> See below\\ \> The long name \>\>\> A descriptive name describing the APM.\\ \\ \> The modifiers are used to fit the name into context. They are...\\ \\ \>\> A \> At\\ \>\> I \> In\\ \>\> O \> On\\ \>\> T \> The\\ \>\> R \> 's Room\\ \\ \>\> IR John Butler becomes $<$In$>$ John Butler$<$'s Room$>$, \\ \>\> OT Robot machine becomes $<$On$>$ $<$The$>$ Robot machine \\ \>\> and so on.\\ \end{tabbing} NSGEN converts this text file into a binary file NS.DAT which is used by a variety of management utilities through the following IMP include files. NSDEFS.INC contains the NS.DAT record formats and so on. NS.INC contains a set of routines for accessing NS.DAT: OPEN NS DB opens access to the database and returns a reference number (xno) for use by read ns db and close ns db. READ NS DB takes parameters.. reference no., station reference, address. The station reference is a station number (bottom byte) and a short/long flag (top bit). If the bit is clear, a short station name will be dumped in the 8 bytes from ADDRESS, padded to right with characters $<$= ' '. If the bit is set, a 64-byte record of type ns lfm will be dumped from ADDRESS. The result passed back is either the length of the requested data or a -ve number denoting a failure. CLOSE NS DB closes the database FS SNAME takes a station number and returns the short station name or "". FS LNAME takes a station number and returns the long station name or "". FS GET NS INFO takes a station number and returns a record of type ns lfm The utilities WHATIS, DUMPLOG and INVENTY use this database WHATIS returns details of what machine should correspond to a given station numer INVENTY takes the machine configurations and produces a complete inventory of APM components, sorted several ways. \subsection{The LOG file} The LOG command (logon/logoff) adds one record to the file LOG:.LOGFILE every time it is called. This contains a time stamp, the station number, the user ID and a bit to determine whether it was a logon or logoff. This information may be analysed by a couple of utilities in directoy LOG:. \subsubsection{DUMPLOG} This dumps the logon/off statistics found in .LOGFILE Parameters may be $<$null$>$ or any combination of B, C, and M. The utility expects to find files .LOGFILE, .LOGFILEC and .LOGFILEM in directory LOG. The letter (s) instruct it on which of these files to include in the dump. The result is a table giving the number and duration of logged-on sessions plus a list of unused stations. .LOGFILEM and .LOGFILEC must be brought across from filestores 'M' and 'C' respectively (by hand) first. The utility will prompt for start and end dates. $<$return$>$ defaults to the start and end of file respectively. \subsection{FORCE} Once upon a time it was decided to force all CS3 students to put the command "TYPE CS3:ALERT" into their LOGIN.COM files. To this end the FORCE program was written. It takes four parameters (which it asks for). They are: - the name of a file containing the directory names of the people concerned. - the name of the file in the directory to be inspected. - the string to be searched for in that file. - the line to be added to the file if that string is not found in the file. \section{The Shoearea} The ROM bootstraps in all the APMs first fill memory with a known pattern, find out how much main memory there is, then connect to their favourite filestore (or, alternatively, initialise their local disk controller), and finally ask for a particular file (FMAC:NSYS) to be sent from that filestore (or read off the local disk). That file is read into the APM boot processor's local memory and is either an operating system or a secondary bootstrap which wheels in further system components. In the normal case of booting off a remote filestore everything is straightforward. The boot ROMs need only contain sufficient code to talk through the ethernet controller to the remote filestore. With local disks the situation is more complicated. Looking for a file in what is potentially a highly involved directory structure would require more code than would fit into the ROMs. Therefore a small portion of the disk is reserved as an area (originally called "boot area" but subsequently (for no good reason) renamed "shoe area") into which all files relating to bootstrapping the system must be copied. Each disk begins with two such shoe areas (each 0.5 MBytes in size, perhaps less on the smaller disks). The key switch on the front of the APM is used to decide which of these two areas to boot from (Area 0 for position 0 (the first notch you reach when you switch on), area 1 for position 1 (the next notch); you'll probably get area 0 for positions 2, 4, and 8 as well). Each shoe area begins with a directory which is so simple that code in the small ROMs can look up and find named files. The SHOEAREA program is a utility (which you run under the normal operating system) to transfer files between the normal file system and the shoe areas. Access to the shoe areas is protected by the filestores and you must either have the system password quoted or be logged on as SYSTEM (the directory in which all the filestore programs (including the SHOEAREA program) are kept). The program is mildly self-documenting. Type the command H at it and it will tell you what it can do: \begin{description} \item[A] select the boot AREA to manipulate (0 or 1) \item[I] initialise the directory for the selected area \item[B] define a bad patch on the disk (relevant only for bad patches within the shoe area - it prevents attempts to write files over them) \item[F] show what FILES are in the directory \item[W] write a FILE SYSTEM FILE into a BOOT AREA FILE \item[R] read a BOOT AREA FILE copying it into a FILE SYSTEM FILE \item[C] compare a BOOT AREA FILE with a FILE SYSTEM FILE \item[D] delete a file in the boot area \item[N] rename a file in the boot area \end{description} It is important to note that the SHOEAREA program manipulates the shoe areas on the disk of the filestore to which your APM is connected. If you wish to manipulate boot areas of local disks, a different program must be used. \section{Appendix A - Filestore hardware configurations} \subsection{Filestore B} RS232 Communications lines - QSART at ???????? \begin{tabbing} mmmmm\=mmmmmmmmm\=mmmmmmmmm\kill 0: \> 9600 \> Printer \\ 1: \> 9600 \> ECUVAX \\ 2: \> 4800 \> Itspna \\ 3: \> 9600 \> unused \\ \end{tabbing} \subsection{Filestore C} RS232 Communications lines - QSART at ???????? \begin{tabbing} mmmmm\=mmmmmmmmm\=mmmmmmmmm\kill 0: \> 9600 \> unused \\ 1: \> 9600 \> unused \\ 2: \> 4800 \> Itspna \\ 3: \> 9600 \> unused \\ \end{tabbing} \end{document}