\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}
