+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename book.info
+@settitle TABS - The Terminal Allocation and Booking System
+@c @setchapternewpage off
+@headings double
+@afourpaper
+@c %**end of header
+
+@ifinfo
+
+@node TOP, Introduction, (dir), (dir)
+@top TABS - The Terminal Allocation and Booking System
+@comment node-name, next, previous, up
+This document describes the workstation booking system developed at,
+and used by, the School of Computer Science and Engineering, at the
+University of New South Wales.
+
+@end ifinfo
+
+@titlepage
+@title TABS
+@subtitle The Terminal Allocation and Booking System
+@subtitle from The University of New South Wales
+@author The School of Computer Science and Engineering
+@author Computing Support Group
+@end titlepage
+
+
+
+@menu
+* Introduction::
+* Concepts::
+* Components::
+* Bookings Database::
+* Laboratory Status and Management::
+* The full scoop on tokens and attributes::
+* Setting it up::
+* UNSW Local Lore::
+* Interaction with other systems::
+* Policy::
+@end menu
+
+@node Introduction, Concepts, TOP, TOP
+@chapter Introduction
+TABS - The Terminal Allocation and Booking System assists in controlling
+access to computing laboratories in the School of Computer Science and
+Engineering at The University Of New South Wales.
+
+It has been under development since 1994 and has a heritage extending
+back to other systems dating back to 1983. Though it has now reached a
+sufficient level of maturity that it can be given to others to use, it
+is still in several ways a @emph{work-in-progress}.
+
+
+
+@menu
+* Whats in a name?::
+* What the user sees::
+* The Administrators perspective::
+* Tools::
+@end menu
+
+@node Whats in a name?, What the user sees, Introduction, Introduction
+@section What's in a name?
+The answer to this question is, of course "four words"...
+
+@table @samp
+@item Terminal
+The system deals with @dfn{terminals} or @dfn{workstations} as the basic
+unit which is controlled. i.e. TABS only controls access to the computer
+system. No other resource (such as CPU time etc) is controlled.
+
+@item Allocation
+The system allocates terminals to particular users, or groups of
+users. Having made this allocation is honours the allocation by making
+sure that, at the appropriate time, no one else is using the terminal.
+This involves evicting any current user, and baring access to any
+non-booked user. This is the sole pro-active part of TABS.
+
+@item Booking
+The system accepts bookings by users or classes for workstations.
+A booking identifies the time when the workstation is needed, and the
+lab in which the workstation will be allocated. It does not identify a
+particular workstation - that is what allocation is for.
+The number of bookings which can be made, and the possible time/lab
+choices can be restricted with great flexibility.
+
+@item System
+TABS is not just a single program. It is a collection of daemons, (for
+storing, maintaining and monitoring the state of the system, and for
+evicting user), associated tools (for reporting on and changing the
+state of the system). It needs to interact fairly closely with the
+login process.
+@end table
+
+As TABS is primarily responsible for monitoring and controlling logins, it
+easily keeps track of both current and past logins, and so is useful for
+keeping @emph{Tabs} on users.
+
+@node What the user sees, The Administrators perspective, Whats in a name?, Introduction
+@section What the user sees
+
+Possibly the best way to give an introductory overview of the booking
+system is to describe some of the interactions that an ordinary user of
+the booking system might have with the system.
+
+
+
+@menu
+* Making a booking::
+* Claiming a booking::
+* Being evicted::
+@end menu
+
+@node Making a booking, Claiming a booking, What the user sees, What the user sees
+@subsection Making a booking
+Probably the first interaction a user will have is when they attempt
+to make a booking.
+This is done by running the program @code{book}, either while logged
+in normally, or by logging in to a @dfn{Booking Terminal}.
+
+@code{book} is an interactive line oriented program with online help.
+It allows the user to examine the bookings they have made, both
+pending and past, and to make new bookings or cancel old bookings.
+
+A booking is made by using the @code{book} command within the
+@code{book} program.
+This command can be given a range of times to try to find a bookable
+slot in, or can just be allowed to find the first available slot.
+It will offer any available time-slots to the user for confirmation.
+Once the user confirms a time slot, they will be asked to choose a
+token to be used for the booking (if there is more than one option)
+and then choose the lab in which the booking will be made (again, only if
+there is more than one option).
+
+Time slots are half an hour long. A booking can be made for one of more
+consecutive half hour periods.
+
+Once a booking has been made, the user knows @emph{when} it is for, and
+@emph{which lab} it will be in. Note however, that the user does not know
+which of the lab's workstations they will be allocated until the time has
+come to claim the booking.
+
+
+@node Claiming a booking, Being evicted, Making a booking, What the user sees
+@subsection Claiming a booking
+
+To claim a booking, the user must turn up at the appropriate lab at
+the appropriate time, preferably a few minutes early.
+
+In or near the lab will be an Allocation Display Terminal (or
+@dfn{Skyterm}).
+This is a @samp{Dumb Terminal} which continually displays unclaimed
+allocations in one or more labs.
+The user should find an entry on the display for their booking.
+It will have the first three letters of their family name, their login
+name, and the name of the workstation that they have been allocated.
+
+They should then go and find that workstation.
+If someone is currently using the workstation, the booking system will
+be sending them warnings that they should log off, and will force them
+to log off at the start time for the user's booking if they do not log
+off voluntarily.
+
+The booked user should wait for the current user to log off (if
+necessary) and then simply log on.
+
+If the user turns up late to claim their booking, they will have until
+seven minutes past the start of the period (starting on the hour or half
+hour) to log in. During this time, no-one else will be permitted to log
+in.
+
+If they arrive more than seven minutes late, and someone else has
+already logged in then they will miss out.
+If they had only booked a single half hour period, they are probably
+too late to be able to do any useful work anyway.
+If they had booked several half hour periods, it is NOT sufficient to
+wait for the next period and find the workstation reserved for them
+then.
+This is because the booking system "expects" them not to turn up, and
+so will not evict anyone to make room for them.
+In this situation, the user should log in to a booking terminal and
+use the @code{claim} command.
+This will find out which workstation the user was allocated to, and
+will commence eviction proceeding for whoever is logged on. This will
+give the currently logged on user at least 5 minutes to log off.
+The booked user will then be able to log on normally.
+
+@node Being evicted, , Claiming a booking, What the user sees
+@subsection Being evicted
+If a user is logged on to a workstation, but is not booked for the next
+half hour period, then there is a fair chance that they will be evicted
+at the end of the current period. If this is to happen, then 10 minutes
+before the end of the current period, a warning message will appear on
+their screen in a window similar to the windows that @code{xmessage}
+uses. The window will have a button on it allowing the user to
+acknowledge the message and make it go away. Further warning messages
+will appear at 6, 3, 2, and 1 minute to go. Each message will make it
+clear how much longer the current user has until they will be forced to
+log off. If they persist in not logging off, then, when the time
+arrives, all their windows will disappear, quite probably all their
+processes will be killed, and a login window will appear so that the
+booked user may log in. Note that the eviction process does not
+physically remove the user from the workstation as effective, legal
+techniques to achieve this are yet to be developed.
+
+@node The Administrators perspective, Tools, What the user sees, Introduction
+@section The Administrators perspective
+
+The other side of the coin to what the user sees is the system
+administrator's point of view.
+This section discusses the various components that the administrator
+sees.
+
+There are two important components to the inner workings of the booking
+system. They are the database and the lab management components which
+are introduced here and discussed in depth in subsequent chapters.
+
+
+
+@menu
+* The Database::
+* Lab Management::
+@end menu
+
+@node The Database, Lab Management, The Administrators perspective, The Administrators perspective
+@subsection The Database
+The booking system maintains a database of information which controls
+the running of the system.
+This information can broadly be classified into two classes:
+configuration information and booking information.
+
+Configuration information identifies all the workstations and hosts
+which will be managed by the system, as well as the various booking
+privileges which different users have.
+
+Booking information records all bookings that have been made along
+which their current status, such as @code{pending}, @code{cancelled},
+@code{allocated} etc.
+The database also stores some summary information such as how many more
+bookings can be made in each lab in each time-slot.
+
+This database can be replicated on a number of computers to provide high
+availability, and is remotely accessible over the network via ONC-RPC.
+Each copy of the database is managed by a pair of programs, one
+(@code{book_database}) which provides a controlled RPC interface to the
+files which store the information, and one (@code{book_maint}) which
+works to keep the multiple copies up to date with respect to one
+another.
+
+@node Lab Management, , The Database, The Administrators perspective
+@subsection Lab Management
+
+Lab management involves monitoring the status of hosts and workstations
+within a lab (or group of labs), allocating bookings to workstations as
+appropriate, and evicting users from workstations when required.
+
+The status of a lab, or group of labs, is represented in a table. This
+table lists various information about the lab such as who is logged
+on which workstation, and when they logged in; who is allocated to which
+workstation; and which workstations are currently working.
+
+This table is passed from host to host around all the hosts which manage
+workstations in a lab group. Each host updates any information in the
+table which it is responsible for before passing it on.
+
+One host in the group is designated a @dfn{master} and is responsible
+for retarding the speed of the table passing so that is does not exceed
+once around every 30 seconds, and for extracting booking information
+from the booking database as required, and allocated the bookings to
+particular workstations.
+
+The task of lab management rests on a pair of programs called
+@code{book_status} and @code{book_manager}.
+@code{book_status} holds a current copy of the table and responds to
+ONC-RPC requests to examine and update the table.
+@code{book_manager} periodically retrieves a copy of the table from the
+@code{book_status}, confirms and updates some of the information, and
+passes the table onto the next host in the list.
+@code{book_manager} also notes when some one needs to be warned to log
+off and possibly evicted, and takes the necessary action.
+
+@code{book_status} also maintains (with some help from
+@code{book_manager}) a list of known database locations so that clients
+can quickly find an active, up-to-date database replica.
+For this reason it is often useful to run @code{book_status} on all
+computers in a network rather than just those that are involved in
+running a bookable lab.
+
+@node Tools, , The Administrators perspective, Introduction
+@section Tools
+
+To maintain the database and to monitor the labs, there are a number of
+tools available.
+These are simple, non-interactive, commands which inspect and modify
+state information.
+Many of the commands are named after the parts of the system that they
+deal with (e.g. @code{token}, @code{booking} @code{lab}).
+These are detailed in @ref{Components}.
+
+@node Concepts, Components, Introduction, TOP
+@chapter Concepts
+There are a number of central concepts in the booking system. The
+following defines them and shows how they inter-relate.
+
+
+
+@menu
+* Workstation::
+* Host::
+* Lab::
+* HostGroup::
+* Period::
+* Attribute::
+* Token::
+* Class::
+* Full and Free Periods::
+* Open and Closed Times::
+* Allocations::
+* Evictions and Reservations::
+* Defaulters::
+* Booking::
+* Database::
+* Lab status::
+@end menu
+
+@node Workstation, Host, Concepts, Concepts
+@section Workstation
+A @dfn{workstation} is the I/O station (keyboard, monitor, and mouse)
+that a user uses to (hopefully) do work. It is the thing which the
+client of the booking system actually books and is allocated. In
+reality, it may be a workstation in the more traditional sense of the
+word, an X terminal, or even a @var{dumb} terminal.
+
+Unfortunately, it is not yet possible to book modems as we would need
+the modem to check the calling telephone number before answering the
+telephone.
+
+@node Host, Lab, Workstation, Concepts
+@section Host
+A @dfn{host} is a thing which supports one or more workstations; ie: the
+host will execute processes which use the workstation(s) for user
+interaction. In the case of traditional workstation, the @emph{host}
+and the @emph{workstation} are one and the same, but where X terminals
+are used, a host will usually be responsible for supporting multiple
+@emph{workstations}.
+
+Often a @emph{workstation} will be tied to a particular host, but this is not
+necessary.
+
+@node Lab, HostGroup, Host, Concepts
+@section Lab
+A @dfn{Lab} is a collection of physically close workstations, which are
+normally similar in configuration.
+When a booking is made, it is allocated to a particular @emph{Lab}, but not
+to any particular workstation within that @emph{Lab}.
+
+@node HostGroup, Period, Lab, Concepts
+@section HostGroup
+A @dfn{HostGroup} is a group of @emph{hosts} that work together to
+maintain a group of @emph{Labs}. In the case of a lab of workstations,
+the @emph{HostGroup} is most simply the group of workstation/hosts in
+the lab, while a lab of Xterminals all controlled by the one Xserver
+will have a @emph{HostGroup} made up that single Xserver host.
+
+In general however, the @emph{HostGroup} is chosen such that it is the
+smallest group of hosts needed to control an integral number of labs.
+
+Thus it may be necessary to have 2 Xterminal labs controlled by a
+@emph{HostGroup} of 3 Xserver hosts if both labs had some Xterminals
+controlled by a common Xserver host.
+
+@node Period, Attribute, HostGroup, Concepts
+@section Period
+A period is a half hour beginning on the hour or the half hour. A booking
+can be made for one or more periods.
+
+There are 48 periods in a day, and 365 (or 366) days in a year.
+TABS has no concept of a sequence of years. There is only one year - the
+current year.
+This is not normally a problem as academic years fit within calander
+years (at least in the southern hemisphere) though could be a problem
+with summer session subjects.
+
+
+@node Attribute, Token, Period, Concepts
+@section Attribute
+The differences between different workstations and different periods are
+recorded using a set of boolean @dfn{attributes} which a workstation or period
+may or may not possess.
+
+Every given workstation has a set of attributes
+associated with it for every given period.
+
+There may be attributes which indicate:
+@itemize @bullet
+@item type of host which supports a workstation
+@item type of display which the workstation has
+@item which lab a workstation is in
+@item which week of session a period is in
+@item whether a particular lab is closed during a particular period
+@item whether part time students should be given preferential access to
+a particular period.
+@end itemize
+
+Attributes are primarily used to determine booking privileges as
+described under @emph{Tokens}.
+
+@node Token, Class, Attribute, Concepts
+@section Token
+
+A @dfn{token} conveys a right to book a single workstation for a single
+period. @emph{Tokens} are allocated to classes and (occasionally) to
+users and are used up by making bookings. When a booking is cancelled
+or allocated, the token that was used to make it may be refund,
+depending on several variables. It may also be refunded in a special
+form which provides extra power --- see Policy.
+
+A token contains a set of attributes and conveys the right to book any
+workstation/period combination that only has attributes from that set.
+Thus, if a token has the attributes corresponding to weeks 1, 2, and 3
+of session, but no other week attributes set, then it can only be used
+to make bookings during those weeks.
+
+A token contains a second set of attributes which may be broader than
+the first set and is used if a booking is being made less than 4 days in
+advance. The rational for this is described later (I hope).
+
+Tokens may or may not be refundable.
+Non refundable tokens convey the right to a certain amount of terminal
+time. When it has been used up, it is gone.
+Refundable tokens convey a share of the available terminal time. The
+more one has, the greater share of the available time can be booked and
+hence used.
+This is (Will be) discussed in more detail in "The full scoop on tokens
+and attributes".
+
+@node Class, Full and Free Periods, Token, Concepts
+@section Class
+It is useful to group users together into classes for the purposes of
+token allocation and class bookings.
+When a number of tokens are allocated to a class, that number of tokens
+becomes available to each member of the class.
+Similarly if a booking is made for a class then the workstations
+reserved for that booking are made available to any member of the class.
+
+Class membership is recorded using netgroups. The booking system
+software uses YP lookup of the @code{netgroup.byuser} or
+@code{netgroup_byuser} to access class/netgroup information.
+
+Classes are treated internally as very similar to normal users. To keep
+a clear distinction, classes are assigned uid numbers greater than
+some large value, normally 1073741824 (40000000 in base 16). This value
+is configurable
+This means that all users, whose uids are looked up via normal
+mechanisms, must have uids less than this.
+
+@node Full and Free Periods, Open and Closed Times, Class, Concepts
+@section Full and Free Periods
+The distinction between full and free periods is only relevant when
+refundable tokens are not being used.
+
+A @dfn{full} period in a lab is any period in which the total number of
+bookings exceeds 90% of the number of available workstations.
+A @dfn{free} period is any other period.
+
+Bookings which are allocated in a free period fill have the token
+refunded. This is to encourage people to book times which are likely to
+be under used. If refundable tokens are used, this is fairly irrelevant
+as these tokens are refunded even for full periods.
+
+@node Open and Closed Times, Allocations, Full and Free Periods, Concepts
+@section Open and Closed Times
+
+The booking system knows about three different sorts of times: Times
+where a lab is open, times when it is closed, and other times.
+
+@itemize @bullet
+@item
+Bookings can only be made for times when a lab it open. Also, these are
+the only times when the system will attempt to allocate bookings to
+workstations.
+
+@item
+When a lab is closed, anyone who is logged on will be evicted, and no-one
+will be allowed to log in. This helps lab supervision staff to encourage
+people to leave the room so that it may be locked.
+
+@item
+When a lab is neither open nor closed, the booking system simply
+continues monitoring the lab and does not impose on logins at all. This
+state is particularly appropriate for the first half hour after a lab is
+opened in the morning: people should be allowed to login, but bookings
+should not be allowed, in case the lab is opened slightly late by
+mistake.
+@end itemize
+
+@node Allocations, Evictions and Reservations, Open and Closed Times, Concepts
+@section Allocations
+
+@dfn{Allocation} is the process of assigning bookings to workstations.
+This is done 10 minutes before the start of a period.
+
+Allocation is performed by ordering the bookings by the time they were
+made (so that bookings that are made early get preference); ordering the
+workstations in a @samp{most available} order, and then sequentially
+assigning the bookings to either (a) a workstation that the booked user
+is already using or (b) the first workstation that matches the
+requirements of the booking.
+
+The ordering of workstations is done in the following classifications:
+@itemize @bullet
+@item
+Unused workstations in order of id number come first.
+
+@item
+Workstations that are in use by users who are not booked for the coming
+period come next. Within this group, workstations are ordered by the
+amount of un-booked time that the user has used. Thus people who have
+been unbooked for a while are more likely to be evicted.
+
+@item
+Workstations that are in use by users who are booked for the coming
+period. These will only get allocated to other users if there are not
+enough workstations to go around.
+
+@item
+Finally, workstations which are not working. Rather than allocating a
+booking to a broken workstation, the allocation procedure will record
+that the booking could not be allocated and will refund the token.
+@end itemize
+
+Allocations come in two flavours: normal and firm.
+
+Normal allocations will reserve a workstation for a user for only
+a few (seven) minutes. If they do not turn up, then anyone else may log
+in.
+
+Firm allocations will reserve the workstation for the entire period of
+the booking. These are normally used only for supervised class bookings
+when the supervisor wants only people from the booked class to be in the
+room.
+
+TAKE TWO
+
+@itemize @bullet
+@item
+Any bookings for users who were allocated a workstation in the previous
+period, but are not logged on, are marked as @dfn{tentative} meaning
+that no eviction will be performed for them.
+@item
+Any bookings for a user who is determined to be a defaulter (see below)
+is marked as tentative.
+@item
+The bookings for each lab are sorted by the time that they are made,
+except that tentative bookings are sorted last.
+@item
+The workstations are sorted with
+@itemize @bullet
+@item
+Free workstations first in no particular order
+@item
+Workstations with someone logged in who has not booked for the coming
+period next. These workstations are sorted by how long the person has
+been logged on since their last booking. People who have been on a long
+time are sorted earlier in the list.
+@item
+Workstation with someone who has booked for the coming period.
+@item
+Workstation which don't seem to be working.
+@end itemize
+@item
+These two lists are then processed together, normally allocating the first booking
+to the first workstation, the second booking to the second workstation
+etc.
+If, however, a booking is found for a user who is currently logged in to
+an unallocated workstation, the booking is allocated to that workstation
+instead of the next one.
+@end itemize
+This allocation process achieves the following goals:
+@itemize @bullet
+@item
+Booked users who are currently logged on don't have to change
+workstation.
+@item
+Users who book multiple successive time slots, and don't turn up for the
+first, will have subsequent bookings allocated as @emph{tentative} which
+will not cause an eviction. (If they do turn up late, they can claim
+their booking at a booking terminal).
+@item
+When the lab is not fully booked, current users who have had recent
+bookings will be less likely to be evicted than users who have not had
+recent bookings.
+@item
+If the case so some workstations malfunctioning so that not all bookings
+can be honoured, bookings that were made earlier are more likely to be
+honoured.
+@end itemize
+
+@node Evictions and Reservations, Defaulters, Allocations, Concepts
+@section Evictions and Reservations
+
+Evictions and reservations are the two @emph{weapons} in the booking
+system's arsenal for honouring bookings.
+
+Eviction involves forcing someone who is not booked to leave a
+workstation that has been allocated to someone else. This is done by
+sending warning messages every few minutes for the ten minutes before
+the allocation begins, and then by logging the user out if there
+remained on despite all the warnings.
+Logging the user out is done by signalling the @emph{xdm} process which
+is controlling the login session.
+
+Reservation involves preventing anyone but the allocated user from
+logging in to a particular workstation. This is done by simply denying
+login, which is very easy to do when using @emph{xdm}.
+
+@node Defaulters, Booking, Evictions and Reservations, Concepts
+@section Defaulters
+
+A @dfn{defaulter} is a user of the booking system who has made some
+bookings, but did not turn up to claim them.
+TABS attempts to record when a user does or does not claim their
+booking, and applies a simple heuristic to determine whether they seem
+to be displaying a pattern of not claiming bookings.
+
+If a user is determined to be a @dfn{defaulter}, any allocation made for
+them will be made as a tentative allocation, so it will not cause an
+eviction or a reservation.
+The defaulter can still claim their bookings by using the @code{claim}
+command at a booking terminal.
+They will only need to do this a couple of times in order for TABS to
+determine that they are no longer to be treated as a @dfn{defaulter}.
+
+@node Booking, Database, Defaulters, Concepts
+@section Booking
+
+A @dfn{booking} is a request to be allocated a workstation in a
+particular lab at a particular time.
+
+@node Database, Lab status, Booking, Concepts
+@section Database
+
+The @dfn{Database} hold all of the non-transient state of the booking
+system.
+This includes the hardware (workstations, hosts, labs), the
+configuration (attributes, tokens, implications) and bookings.
+
+@node Lab status, , Database, Concepts
+@section Lab status
+
+@dfn{Lab status} refers to the transient status of the workstations and
+hosts in a lab. This includes current allocations, current usage or
+workstations, current state of workstations.
+
+
+@node Components, Bookings Database, Concepts, TOP
+@chapter Components
+
+
+@menu
+* dbadmin::
+* smadmin::
+* booking::
+* bkuser::
+* token - the program::
+* bkattr::
+* bkconf::
+* bkhg::
+* lab - the program::
+* bookterm::
+* bogin::
+* book::
+* tkbook::
+* messaged::
+* saveauth::
+* sendmess::
+* book_login::
+* book_logout::
+* book_database and book_maint::
+* book_status and book_manager::
+@end menu
+
+@node dbadmin, smadmin, Components, Components
+@section dbadmin
+
+The @code{dbadmin} command is used to help administer the database
+replica, particular when creating and deleting replicas.
+
+If @code{dbadmin} need to find a database server in order to perform its
+task, it will use the normal procedure of asking the local book_status
+server. It may be necessary or desirable to over ride this, such as when
+there is no status server running yet. In this case a @code{-r replica}
+flag may be given, in which case @code{dbadmin} will consult that
+replica as needed.
+
+The various uses are as follows:
+@table @code
+@item dbadmin [ -r replica ] -s [-A | serverlist]
+This will discover and show the status of various replicas. If a
+@code{serverlist} is given, then each server is queried in turn.
+If @code{-A} is given, then all registered servers will be queried.
+
+@item dbadmin [ -r replica ] -a replica
+This will register the given replica as an active replica.
+@code{dbadmin} will only attempt this if the new replica indeed seems to
+be working and is not currently registered.
+
+@item dbadmin [ -r replica ] -d replica
+This will de-register the given replica. If the @code{-r replica} flag is
+not given, then @code{dbadmin} will send the change request to the
+replica being deleted.
+
+@item dbadmin -x replica
+This command instructs the named replica to exit, which is slightly
+cleaner than sending it a SIGTERM signal.
+
+@item dbadmin -R replica
+This command instructs the replica to re-organise its datafiles.
+Re-organisation is needed as GDBM files will never shrink, even when
+lots of entries are removed.
+This command is no longer necessary as in normal operation, the
+@code{book_database} will automatically re-organise files about once a
+day.
+@end table
+
+The status information reported with @code{dbadmin -s} has one line for
+each server reported on. The line contains the state of the server,
+either @code{UP} for full update mode, @code{CP} for copy only mode, or
+@code{NO} for no update mode.
+Following this is a list of all registered replicas that the server
+knows about, together with the number of the last change received from
+that replica.
+
+@node smadmin, booking, dbadmin, Components
+@section smadmin
+
+@code{smadmin} is used for monitoring the status manager pair of
+servers.
+It can send commands to, and receive information from, the
+@code{book_status} server.
+
+The various uses are:
+@table @code
+@item smadmin -t @var{host}
+Get the status table from the host and print it.
+The resulting output has one line for each record in the table. See
+section on @ref{Status Table} for detailed information.
+
+@item smadmin -d @var{host}
+Get the list of database replicas from the host and print it.
+There will be one line for each replica showing the name of the host
+and the last known status of that replica.
+The list is ordered with the most preferred replica first.
+
+@item smadmin -D @var{host}
+Update the list of database replicas stored at the host. This collects
+the list, checks each listed replica to discover its status, and to
+discover if there are any changes to the list of registered replicas,
+and then sends changes back to the @code{book_status} server.
+
+This operation is performed regularly by the @code{book_manager}
+program.
+
+@item smadmin -r @var{host}
+
+Tell the @code{book_status} daemon to kill and restart its
+@code{book_manager}.
+This is useful after installing a new version of @code{book_manager},
+and also after updating information which would change the list of
+entries in the status table.
+
+When the @code{book_manager} starts, it extracts relevant host, lab,
+workstation etc. information from the database and builds a new status
+table. This table is merged with the current table stored in the
+@code{book_status} program ensuring the the status table has correct
+form and current information.
+@end table
+
+
+@node booking, bkuser, smadmin, Components
+@section booking
+
+The @code{booking} program is used to inspect, and to a limited extent
+change, bookings by time and lab.
+It does not allow the making of new bookings. This is solely the
+prerogative of the @code{book} program.
+
+@code{booking} does two quite distinct tasks: listing, and possibly
+deleting, bookings; and changing the status of a list of bookings.
+
+
+
+@menu
+* Listing Bookings::
+* Changing the status of bookings::
+@end menu
+
+@node Listing Bookings, Changing the status of bookings, booking, booking
+@subsection Listing Bookings
+
+@example
+ booking [-R] dates periods labs
+@end example
+
+To list bookings, @code{booking} should be given a range of dates, a
+range of times, and one or more labs. It will then list all the bookings
+in the database that match those criteria.
+
+The date range and the time range are in the same format as used for
+implications.
+e.g. @code{29feb-05mar} or @code{9:00-13:30}.
+The time range in optional and defaults to the whole day.
+
+The list of labs is given as one or more attributes.
+Any lab which implies (though the implications) one of the attributes
+ins included. Alternately, the labs can be given as @code{ALL} meaning
+all labs.
+
+The bookings are listed one per line giving: username, date, period,
+lab, status, number-of-workstations-booked, token-used, and the time
+that the booking was made.
+There may also be listed the user who made the booking (if it is
+different from the user who the booking is for) and the list of
+workstations that the booking was allocated to, if the booking has been
+allocated.
+
+For example:
+@example
+fred 29mar 09:30 in club ALLOCATED x1 undercroft 27/03;14:32:23 club07:0
+fred 01apr 10:00 in ring PENDING x1 undercroft 27/03;14:34:43
+COMP1011 02apr 11:00 in ring PENDING x19 ringlabbooking 01/03;09:31:03
+@end example
+
+In this example, @code{club} and @code{ring} are labs, @code{undercroft}
+and @code{ringlabbooking} are tokens, @code{fred} is a user and
+@code{COMP1011} is a class, which booked all 19 workstations in the ring lab.
+
+When listing bookings, @code{booking} can also remove bookings from the
+database.
+This is done to clean out old data, and should not be done until
+bookings are a couple of weeks old.
+
+When given the @code{-R} flag, @code{booking} will attempt to remove the
+bookings for each period/lab that it lists. The removal will only
+succeed if none of the bookings for the time/lab are still PENDING.
+
+@node Changing the status of bookings, , Listing Bookings, booking
+@subsection Changing the status of bookings
+
+Most changes to bookings are best done with the @code{book} program.
+However, this program can only deal with one user at a time, so it is
+not good at, for instance, cancelling all the bookings that were made
+for a particular time. This is a task that @code{booking} can do.
+
+@example
+ booking -s new-status < list-of-bookings
+@end example
+
+When given a list of bookings, and a new booking status, @code{booking}
+will attempt to set the status of that booking to the given status.
+The attempt can fail as status changes are one way. It is not, for
+instance, possible change change a booking from @code{CANCELLED} to
+@code{PENDING}.
+
+The possible status are PENDING, TENTATIVE, ALLOCATED, RETURNED,
+REFUNDED, CANCELLED, FREEBIE, which are (or should be) described else
+where.
+
+The list of bookings should appear on the standard input and should
+contain, one per line: date, period, lab, user, time-made.
+These fields can be easily extracted from the output of @code{booking}.
+For example, to cancel all the pending bookings in March, the following
+command could be used.
+
+@example
+ booking 01mar-31mar ALL | awk '$6 ~ /PENDING/ @{ print $2, $3, $5, $1, $11 @}' |
+ booking -s CANCELLED
+@end example
+
+
+@node bkuser, token - the program, booking, Components
+@section bkuser
+
+The @code{bkuser} program reports information about users and classes, and
+can allocate tokens to users and classes.
+It can also discard old information about users and classes when tidying
+up between sessions.
+
+The information that can be reported on is most available though the
+@code{book} program as well, however @code{bkuser} makes the information
+more readily available for post processing.
+
+There are three usages from @code{bkuser}: reporting, allocating tokens,
+and renaming classes.
+
+
+
+@menu
+* Reporting on users::
+* Creating classes and allotting tokens::
+* Renaming classes::
+@end menu
+
+@node Reporting on users, Creating classes and allotting tokens, bkuser, bkuser
+@subsection Reporting on users
+@example
+ bkuser -[Dtabp] [-m] [user|ALL]
+@end example
+With this form of usage, @code{bkuser} will report on one or more users
+and will possibly delete token usage information, providing that there
+are no bookings recorded.
+
+The flags have the following meanings.
+@table @code
+@item -D
+Delete token usage information for the user.
+Booking information must already have been deleted via the
+@code{booking} program.
+Allocation (allotment) information must be changed with the next usage
+of @code{bkuser}.
+
+@item -m
+Provide reports in @emph{machine readable} form. This just removes any
+noise and makes the report uniform and easily parsable.
+
+@item -t
+Report on token allocation and usage. For each token that has been
+allocated to the user (or a class which the user is a member of), the
+token name, the number allocated, and the number used (not currently
+available for reuse) are listed.
+
+@item -a
+Report on personal allocations. This is similar to @code{-t} except that
+only tokens allocated to that particular user or class are listed.
+
+@item -b
+Report on pending bookings. All pending bookings for the user are list
+in the same format as used for @code{booking} except that the leading
+username is left off.
+
+@item -p
+Report on past bookings. All bookings that are not pending (e.d,
+allocated or cancelled bookings) are listed in the same format as for
+@code{-b}.
+
+@end table
+If none of @code{-tabp} are given, then @code{-tbp} is assumed.
+
+@node Creating classes and allotting tokens, Renaming classes, Reporting on users, bkuser
+@subsection Creating classes and allotting tokens
+
+@example
+ bkuser [-C [-i id]] [-A token -c count] user ...
+@end example
+
+In this form, @code{bkuser} can register (create) class names and can
+allot tokens to classes or users.
+@table @code
+@item -C
+Register (create) the given names as class names, if they don't already
+exist.
+@item -i idnumber
+When registering a class name, use the id number given as its internal
+id number. Normally an unused id number greater than
+@strong{min_class_id} will be used.
+@item -A token
+Allocate some of the given token to the given users or classes.
+@item -c count
+Indicates how many tokens to be allocated.
+If @code{count} starts with a plus sign, then that many tokens are added
+to each users allocation.
+If @code{count} starts with a minus sign, then the given number of
+tokens is subtracted.
+Otherwise @code{bkuser} ensures that precisely the number given is
+allocated to each user or class given.
+@end table
+
+@node Renaming classes, , Creating classes and allotting tokens, bkuser
+@subsection Renaming classes
+@example
+ bkuser -R oldname newname
+@end example
+This simply changes the name of a class. The new name should exist as a
+netgroup, though this is not currently checked.
+
+
+@node token - the program, bkattr, bkuser, Components
+@section token
+
+The @code{token} program is used to create, modify, examine, and discard
+tokens.
+
+
+
+@menu
+* Creating a token::
+* Modifying a token::
+* Listing tokens::
+* Discarding Tokens::
+@end menu
+
+@node Creating a token, Modifying a token, token - the program, token - the program
+@subsection Creating a token
+@example
+ tools/token [-f] -c tokenname [-i idnum] attributes
+@end example
+
+This usage creates a token with the given @code{tokenname}. An
+@code{idnum} can be given but is not normally necessary as an unused id
+number will otherwise be allocated.
+The @code{-f} suppresses checking incase the token already exists.
+
+The attributes listed are assigned to both attribute sets of the token.
+
+@node Modifying a token, Listing tokens, Creating a token, token - the program
+@subsection Modifying a token
+@example
+ tools/token -R oldname newname
+ tools/token -[ads] attributes token[/EL]
+@end example
+
+The first usage given here simply changes the name of the token.
+
+The second usage changes the attributes assigned to a token or tokens.
+The attributes should be a period separated list of attribute names.
+The flags @code{a}, @code{d}, and @code{s} mean to @samp{add},
+@samp{delete}, and @samp{set} the given attributes respectively.
+
+There may be several token names given.
+If a token name is given unadorned, then both the early, and the late
+attribute sets are changed.
+If the token name is suffixed with @code{/E} then only the early token
+set is changed. If suffixed with @code{/L} then only the late token set
+is changed.
+
+@node Listing tokens, Discarding Tokens, Modifying a token, token - the program
+@subsection Listing tokens
+@example
+ tools/token [-v] -l
+ tools/token tokenname
+@end example
+The first usage lists all tokens, either just as token name or, with
+@code{-v}, with complete information.
+The second usage lists the full detail of the named token or tokens.
+
+The full detail lists the name of the token, the list of attributes used
+for advance bookings, and the list of attributes used for late bookings.
+For example
+@example
+ % tools/token firstyear
+ firstyear
+ Advance:
+ weekdays yellow cyan open available
+ Late:
+ weekend weekdays yellow cyan magenta open available
+@end example
+In this example, students with the @code{firstyear} token can book the
+yellow and cyan tokens on weekdays (provided that they are open and the
+machines are available (not out of service)) in advance.
+Providing that other more deserving students have not already booked the
+labs out, they can also book weekend times and the magenta labs when
+making a late booking.
+
+@node Discarding Tokens, , Listing tokens, token - the program
+@subsection Discarding Tokens
+@example
+ tools/token -D tokenname
+@end example
+
+This usage simply deletes the token. If this token is currently
+allocated to anyone, that allocation remains, but will be ineffective as
+the token will no longer exist.
+
+@node bkattr, bkconf, token - the program, Components
+@section bkattr
+
+@example
+ tools/bkattr attrfile
+ tools/bkattr
+@end example
+
+The @code{bkattr} program is used to set and examine the attributes and
+implications.
+See @ref{Attributes} and @ref{Implications} for the format of attribute
+and implication descriptions.
+
+The first form reads the given file and makes sure that the recorded
+attributes and implications match what is in the file.
+The second form reports on the current set of attributes and
+implications in a form that is suitable for input.
+
+
+@node bkconf, bkhg, bkattr, Components
+@section bkconf
+
+@example
+ tools/bkconf
+ tools/bkconf name
+ tools/bkconf name value
+@end example
+The @code{bkconf} program accesses and modifies the miscellaneous
+configuration values.
+The first form lists all values.
+The second form lists the named value.
+The third form sets the named value to the given value.
+
+@node bkhg, lab - the program, bkconf, Components
+@section bkhg, bkhost, bklb, bkws
+
+The @var{hostgroup}s, @var{host}s, @var{lab}s, and @var{workstation}s
+and their relationships can be registered using the commands
+@code{bkhg}, @code{host}, @code{bklb} and @code{bkws} respectively.
+
+These are all actually one program which determines what sort of object
+to manipulate by examining the least few character of the command used
+to invoke it.
+
+As @var{lab}s are registered as attributes via the @code{bkattr} program,
+@code{bklb} will not create or remove labs.
+
+There are two usages for these command that are common across all four
+commands:
+@example
+ tools/bk@var{object} -D @var{objectname}
+ tools/bk@var{object} -R @var{oldobjectname} @var{newobjectname}
+@end example
+The first will delete the named object, while the second will rename
+the named object.
+
+The third usage lists the relevant object(s) after possibly creating
+and/or modifying them.
+As the possible modifications differ between objects, each object type
+will be treated separately. In all cases, the @code{-c} allows the
+object to be created if it doesn't already exist.
+
+
+
+@menu
+* Creating hostgroups::
+* hosts and labs::
+* workstations::
+@end menu
+
+@node Creating hostgroups, hosts and labs, bkhg, bkhg
+@subsection Creating hostgroups
+
+@example
+tools/bkhg [-c] @var{hostgroupname}
+@end example
+
+No modifications are possible on hostgroup, they may only be created and
+listed.
+The listing simply lists the hosts and labs in the hostgroup:
+@example
+HostGroup: spectrum
+ hosts:
+ red, green, blue
+ labs:
+ cyan, magenta, yellow
+@end example
+
+@node hosts and labs, workstations, Creating hostgroups, bkhg
+@subsection hosts and labs
+
+@example
+tools/bkhost [-c] [-g group] @var{hostname}
+tools/bklb [-g group] @var{labname}
+@end example
+
+Hosts and labs are treated much the same by this program as the only
+thing that can be done to them is to put them in a hostgroup.
+This is done with the @code{-g} flag.
+
+The program will then list the lab or host giving the hostgroup that it
+is in, and any workstations attached to it.
+
+@example
+Host: green in HostGroup: spectrum
+ workstations:
+ yellow01:0, cyan01:0
+@end example
+
+@node workstations, , hosts and labs, bkhg
+@subsection workstations
+
+@example
+tools/bkws [-c] [-l lab] [-h host] [-d attributes] [ -r reason] @var{workstationname}
+@end example
+
+Each workstation has a set of attributes, possibly a controlling host,
+and possibly a reason why it has been taken out of service.
+This command allows all those to be set.
+
+@table @code
+@item -l lab
+will remove any lab attributes currently set and set the lab attribute
+for the given lab.
+
+@item -h host
+will set the given host to be the controlling host for the workstation.
+If the host is either the empty string or given as @code{none}, then
+the workstation will have no controlling host.
+
+@item -d attributes
+@code{attributes} should be a period separated list of attributes,
+possibly preceded by a plus or minus sign. This attribute list is then
+added to, subtracted from, or assigned to the set of attributes for the
+workstation. This option is not currently very useful as non-lab
+attributes are not supported very well.
+
+@item -r reason
+This will take a workstation out of service by removing the
+@code{available} bit (which is set by default) and recording the
+reason that the workstation is out of service, and the time it was
+taken out of service. If the reason string is the empty string, the
+workstation is returned to service.
+@end table
+
+The command will then list the workstation(s) giving name, host, reason
+if applicable, and attributes:
+@example
+Workstation: cyan01:0 On Host: green
+ cyan, available
+@end example
+
+@node lab - the program, bookterm, bkhg, Components
+@section lab
+
+@example
+tools/lab [-udosASht] labname ...
+@end example
+
+The @code{lab} program is used to view the current status workstations
+in one or more labs.
+It will normally list all workstations with their current status, login
+and allocation information.
+
+For each lab, @code{lab} will output a status line for the whole lab,
+followed by one line for each workstation.
+
+The lab status line reports the status of the lab (FULL, FREE, or
+CLOSED), which host performed the last allocation, the time when that
+allocation takes effect, and the time that the allocation was made.
+
+The workstation status lines report the workstation name, the
+workstation state (Up or Down), the allocation state (OutOfServuce,
+Broken, NotBookable, UnAllocated, Allocated, Tentative), the users
+currently logged on (if any), and the user or class currently allocated
+(if any).
+A final column will contain either the host which the workstation is
+currently logged on to (or was most recently logged on to), or the time
+of the last login or logoff, depending on a command line option.
+
+The set of workstations actually listed, plus a few other aspects of the
+output are controlable by the command line options.
+
+@table @code
+@item -u
+List only workstation which appear to be UP.
+
+@item -d
+List only workstation which appear to be DOWN.
+
+@item -o
+List only workstation which are OutOfService, and give the reason that
+was given when taking them out of service.
+
+@item -s
+Don't print the lab status lines. This is useful with @code{-d} or
+@code{-o} to get just a list of the offending workstations.
+
+@item -t
+Show the time of last login or logoff in the final column. This is the
+default.
+
+@item -h
+Show the host of the last login in the final column.
+
+@item -A
+List all labs.
+
+@item -S
+List all Student labs. Their are all labs for which the @code{open}
+attribute is set.
+
+@end table
+
+As with other programs which accept lab names, the lab names given on
+the command name can be any attribute. All labs which imply anyone of
+the given attributes will be reported on.
+Thus, for example @code{lab -A} is equivalent to @code{lab open}.
+
+
+@node bookterm, bogin, lab - the program, Components
+@section bookterm
+
+The @code{bookterm} program displays a continually updated list of
+unclaimed allocations, and available and unusable workstations.
+
+@code{bookterm} is normally run on a number of dedicated @emph{dumb}
+terminals which are positioned in or near labs, though it can equally
+well be run in an @code{xterm} or elsewhere.
+
+The display consists of a two line header, and a number of 24 character
+wide columns. On a standard @code{80x24} display, there will be three
+columns each with 20 rows.
+The header lists the labs that are being reported on, the start time of
+the current allocation period, the page number, and the time that the
+display was last updated.
+
+Each row of each column contains some information about the state of one
+workstation, or possibly lists an unallocatable booking.
+The different rows that are normally displayed are the following, listed
+here in the order that they will normally be listed on the display.
+@table @samp
+@item sur-username..workstation
+This indicates that the given workstation has been allocated to the
+given user, and that the user has not yet logged on.
+The @code{sur} refers to the first three letters of the users
+surname. It is the primary sort key for there rows.
+@item sur*username..workstation
+This indicates that the given workstation has been tentatively allocated
+to the given user, but that someone else is using the workstation.
+The user would have to use the @code{claim} command at a booking
+terminal to gain access to the workstation.
+This syntax is a little obscure, and may well be changed in a future
+release.
+@item sur-username.....REFUNDED
+The given user has a booking, but it could not be allocated due to a
+lack of usable workstations. The users token has been refunded, possibly
+with extra privilege.
+@item AVAILABLE.....workstation
+This indicates that the named workstation is available. It is not inuse
+and is not currently allocated.
+@item DOWN..........workstation
+The booking system has detected that the named workstation is not
+working properly.
+@item DEAD..........workstation
+The booking system has been told that the named workstation is
+out-of-service, and should not be used.
+The @code{bookterm} program displays a list of workstations and
+reservations for a lab (or labs). The display is continually updated,
+similar to an airline departure screen.
+@end table
+
+When multiple labs are being displayed, the rows for the different labs
+are grouped together and separated, one lab from another, by blank rows.
+
+The command line usage for @code{bookterm} is:
+@example
+ lablist/bookterm [-wfn] labname ...
+@end example
+@table @code
+@item -w
+This flag causes the listing to be sorted by workstation name instead of
+by user surname.
+@item -n
+Normally bookterm will clear the display before drawing each page, to
+make sure the whole page is drawn.
+This can be bothersome when it is run in an @code{xterm}, and the
+@code{-n} flag will suppress this clearing, so that only changes will be
+drawn.
+@item -f
+Full status information for the lab will be displayed. This includes a
+row for each workstation and for each allocation. The detail of the
+different rows is described below (or will be one day).
+A particularly useful addition is that the 3 letter surname is replaced
+with a three character time-since-login.
+@item labname
+One or more labs may be given to be display.
+In line with other programs which take a list of lab names, and
+attribute can be given, and all labs which imply that attribute will be
+included.
+@end table
+
+Note: Users surnames are found by examining the @code{GECOS} field. If
+there is a comma, the the surname is the word immediately before the
+comma, otherwise it is the last word in the field.
+
+
+@node bogin, book, bookterm, Components
+@section bogin
+
+@code{bogin} is a @code{/bin/login} replacement to be used on dedicated
+booking terminals. It will normally be run by @code{getty} or
+@code{init}.
+
+Usage is
+@example
+book/bogin [ -d devicename ] [ username ]
+@end example
+
+If a @samp{devicename} is given, @code{bogin} attempts to open that
+device instead of using @code{stdin} and @code{stdout}.
+
+If an @samp{username} is given, @code{bogin} immediately prompts for a
+password, otherwise it will first prompt for a user name.
+
+For normal users, @code{bogin} will then run @file{/usr/local/bin/book}
+as that user.
+There are, however, other possibilies.
+@itemize @bullet
+@item
+If the user's shell is not in @file{/etc/shells} and the user has a
+password, then @code{bogin} will not allow the login.
+@item
+If the user's shell is not in @file{/etc/shells} and the user has no
+password, then @code{bogin} will run the users shell.
+@item
+If the user's shell is in @file{/etc/shells} but the user has no
+password, then @code{bogin} will not allow the login.
+@item
+If the user is root then @code{bogin} will run @file{/bin/shell}
+@item
+If the user is in group @samp{wheel} or in group @samp{supervisor} then
+@code{bogin} will run the users shell.
+@end itemize
+
+@node book, tkbook, bogin, Components
+@section book
+
+MORE TO BE WRITTEN
+
+The book command is used to make all bookings for the system. It can
+be run either interactively or in batch mode via a script.
+
+
+
+@menu
+* Interactive Use::
+* Batch Use::
+@end menu
+
+@node Interactive Use, Batch Use, book, book
+@subsection Interactive Use
+In order to make bookings that user needs tokens. They can then use
+these tokens to make bookings in a particular lab at a particular time.
+It is not necessary to specify all attributes, as the program will
+prompt the user when there are ambiguities (e.g. a choice of tokens, a
+choice of labs etc.).
+
+The root user and members of group @code{supervisor} are able to invoke
+the book command as another user. This is useful in diagnosing
+problems or misunderstandings users may have with their bookings.
+
+@node Batch Use, , Interactive Use, book
+@subsection Batch Use
+The scripts that make class and lab bookings use the book command in
+batch mode. In this case all the attributes need to be defined
+uniquely. The token that is used to make the booking must define only
+one lab that is to be used. In addition, the number of machines
+required for each slot can be specified.
+
+The book command has extensive online help.
+
+@node tkbook, messaged, book, Components
+@section tkbook
+
+@code{tkbook} is a visual interface to the @code{book} program written
+using @dfn{Tk/Tcl}.
+It allows bookings to be made and cancelled in a reasonably intuitive,
+visual way.
+It provide an online help file which (hopefully) is included as appendix
+X.
+
+@node messaged, saveauth, tkbook, Components
+@section messaged
+
+@example
+messaged/multimessaged [-l] [-L port] [-t timeout] [-g geometry] [-f font]
+ [-D auth-dir] [-d domain]
+@end example
+
+@code{Messaged} is a daemon for displaying messages on X11 displays. It
+is used by the booking system to display warning messages which
+encourage users to log off.
+
+@code{messaged} will maintain multiple message windows on multiple
+displays concurrently, rather than requiring a separate process for each
+window.
+
+@code{messaged} accepts tcp connections over which messages are sent to
+it.
+Each message should start with a line that contains the display
+name. All subsequent lines, up to 2048 byte limit make up the message.
+Upon receiving a message, @code{messaged} will attempt to display it.
+The window used to display the message will contain an @code{OK} button
+which may be clicked to discard the window.
+
+Incoming connections will only be accepted if they come from a privileged
+port on localhost or, if the @code{-d domain} option is present, on a
+host within the domain given.
+
+@code{Messaged} can be run from some versions of @code{inetd} with
+support @code{stream/wait} services properly, or can be run as a stand
+alone daemon.
+
+The command line options have the following meanings:
+@table @code
+@item -l
+@code{messaged} will listen for tcp connection in @code{stdin} (file
+descriptor 1). This is the normal usage when started as a
+@code{stream/wait} service by @code{inetd}
+
+@item -L port
+Port may be a name given in @file{/etc/services} or a number. In either
+case, @code{messaged} will attempt to bind to and listen on that port
+for tcp connections.
+
+@item -t timeout
+If @code{messaged} has no windows to display for @code{timeout} minutes,
+it will exit. This is most useful with @code{-l}.
+
+@item -g geometry
+Specify the geometry for the displayed windows. The default is
+@code{+100+100}.
+Note that only the position can be specified this way. The size is
+calculated from the size of the message.
+
+@item -f font
+Specify the font to use for messaged. The default is
+@example
+-misc-fixed-*-*-normal-*-20-*-*-*-*-*-iso8859-*
+@end example
+
+@item -D auth-dir
+Specify the directory to find @file{Xauthority} file in. The default of
+@file{/var/X11/xdm/save_auth} works well with @code{saveauth}.
+
+@item -d domain
+Allow tcp connection from other hosts providing that they are in the
+given domain. Normally @code{messaged} only accepts connection from
+@code{localhost} (IP address 127.0.0.1).
+
+@end table
+
+If neither @code{-l} or @code{-L} are given, messaged will read a
+message from standard input and display it.
+This is useful for testing and can be used for a @code{stream/nowait}
+service under @code{inetd}, though that would waste the multi-window/
+multi-display funcitonality.
+
+@node saveauth, sendmess, messaged, Components
+@section saveauth
+
+@code{saveauth} attempts to save X11 authentication information for
+later use by @code{messaged}.
+
+It first verifyies that the authentication information available to it
+is correct by attempting to connect to the default display (which will
+be taken from the @code{DISPLAY} environment variable).
+If this succeeds, then the default @file{Xauthority} file (which will
+have been used to authenticate the connection) will be copied into a
+known place.
+
+To determine this known place, the display name is normalise, and used
+as a file name in the directory @file{/var/X11/xdm/save_auth}.
+
+To normalise the display name, the hostname part if fully qualified and
+converted to lower case, the display number is left unchanged and a
+screen number of @samp{0} is used.
+
+This program can safely be made setuid and then run from a default
+@file{Xsession} script.
+
+@node sendmess, book_login, saveauth, Components
+@section sendmess
+
+@code{sendmess} is a simple client of @code{messaged} which will ask
+message to display a message on some display.
+
+@example
+messaged/sendmess [display [host]] < message
+@end example
+
+@code{sendmess} is normally given a display name as a command line
+argument and a message on standard input. It will connect to the
+messaged on the local host and deliver the message.
+
+If @code{sendmess} is given a second argument, it will connect to the
+@code{messaged} on the given host. This is needed if the display is
+currently logged in to another host, and will only work if
+@code{messaged} on that host was started with an approriate @code{-d
+domain} flag.
+
+With no arguments, @code{sendmess} simply read from standard input and
+sends what it gets to the local @code{messaged}, so the first line of
+the standard input should be a display name.
+
+As @code{messaged} only accepts connections from privileged ports,
+@code{sendmess} can only be run by root (or be setuid, though that is
+not encouraged).
+
+@code{sendmess} plays no particular part in the booking system as
+@code{book_manager} sends eviction messages directly to the
+@code{messaged}.
+It is useful for testing, and can be used in any other circumstance
+where it is useful to display messages on particular workstations, such
+as informing a lab supervisor of a paperout condition on a printer.
+
+
+
+@node book_login, book_logout, sendmess, Components
+@section book_login
+
+@code{book_login} should be run as part of the login process so as to
+allow the booking system to be aware of logins, and to be able to control
+(restrict) logins.
+
+@example
+login/book_login [-w workstation | -d display] -u user [-p pid]
+@end example
+
+@code{book_login} will check with the booking system to see if the
+user is permitted to log in to the given workstation.
+If they are, the booking system is told that they have logged in, the
+login is recorded in @file{/var/book/logins} and
+@code{book_login} exits with @dfn{success} status.
+If not, the @code{book_login} will output an explanatory message and
+exit with a @dfn{failure} status.
+
+The options are interpreted as follows:
+@table @code
+@item -w workstation
+This indicates which workstation the user is trying to log in to. Either
+it or the @code{-d} argument must be given.
+
+@item -d display
+This indicates that the user is trying to log in to the given X11
+display.
+@code{book_login} trys to convert this name into a workstation name
+known to the booking system. The corresponding workstation name must be
+a valid display name, with the host part being a prefix of the full
+qualified domain name, the display number part being a simple number,
+and the screen part being absent.
+
+@item -u user
+This indicates which user is loging on.
+
+@item -p pid
+This gives the process id of a process which can be signalled in order
+to terminate the login session. This will normally be the @code{xdm}
+which is controlling the login. The process id is stored in
+@file{/var/book/xdm-pid/@var{workstationname}}.
+
+If this option is omitted, then the booking system will not be able to
+evict anyone (unless a process id is stored in the file by some other
+means).
+@end table
+
+@code{book_login} is normally run from the @code{Startup} under
+@code{xdm}.
+A possible usage would be:
+@example
+if book_login -d $DISPLAY -u $USER -d $PPID > /tmp/book_msg.$DISPLAY
+then # Ok to login
+ rm /tmp/book_msg.$DISPLAY
+else : NOT ok to login
+ sendmess $DISPLAY < /tmp/book_msg.$DISPLAY
+ rm /tmp/book_msg.$DISPLAY
+ sleep 15
+ exit 1
+fi
+@end example
+This example required the Korn Shell (@code{ksh}) or some other shell
+which understands @code{$PPID} to mean the parent process id.
+
+@node book_logout, book_database and book_maint, book_login, Components
+@section book_logout
+
+@code{book_logout} is the partner to @code{book_login} in that it
+informs the booking system that a user has logged out, and records the
+logout in @file{/var/book/logins}.
+@example
+login/book_logout -u user [-w workstation | -d display] [-K]
+@end example
+
+The @code{-u}, @code{-w} and @code{-d} options have the same meaning as
+for @code{book_login}.
+If @code{-K} is given, then @code{book_logout} attempts to kill all
+processes owned by the user.
+This is quite appropriate on traditional workstations, but it's use
+should be considered carefully on multi-user hosts.
+
+@code{book_logout} is normally run from the @code{xdm} @code{Reset}
+script. A possible usage would be:
+@example
+book_logout -u $USER -d $DISPLAY -K
+@end example
+
+@node book_database and book_maint, book_status and book_manager, book_logout, Components
+@section book_database and book_maint
+
+@code{book_database} and @code{book_maint} are the pair of programs that
+maintain the replicated booking system database.
+Their purpose and functionality is detailed elsewhere in
+@xref{BOOK_DATABASE} and @xref{BOOK_MAINT}.
+
+@example
+database/book_database [-I] [-n] [-M book_maint_path]
+database/book_maint
+@end example
+@code{book_maint} takes no arguments.
+@code{book_database} takes the following arguments.
+@table @code
+@item -I
+This tells @code{book_database} to create a new database. This will only
+succeed if none of the database files currently exist.
+The newly created database contains only one datum - that fact that @dfn{this}
+host is a registered replica.
+
+@item -n
+This tells @code{book_database} not to run @code{book_maint}.
+If this is done, then it is probably wise to run @code{book_maint}
+separately.
+
+@item -M book_maint_path
+This tells @code{book_database} where to find the @code{book_maint}
+program.
+By default it tries @file{/usr/local/etc/book_maint}.
+@end table
+
+@code{book_database} and @code{book_maint} do not fork, and so should
+normally be run the the background.
+
+
+
+@node book_status and book_manager, , book_database and book_maint, Components
+@section book_status and book_manager
+
+@code{book_status} and @code{book_manager} are the two programs which
+monitor the status of workstations and labs, and which perform the
+generally running of the system.
+They are described in purpose and functionality in @xref{BOOK_STATUS}
+and @xref{BOOK_MANAGER}.
+
+@example
+manager/book_status [-M book_manager_path] close database replica names
+manager/book_manager
+@end example
+
+@code{book_manager} takes no arguments.
+@code{book_status} takes an optional @code{-M} option which tells it
+where to find the @code{book_manager} program (default is
+@file{/usr/local/etc/book_manager}).
+
+Subsequent arguments are taken as names of database replicas which can
+be considered to be @dfn{close}. If these replicas are active and
+up-to-date, then they will be chosen in preference to other replicas.
+
+@code{book_status} should be run at boot time. It will in turn run
+@code{book_manager}.
+
+@node Bookings Database, Laboratory Status and Management, Components, TOP
+@chapter Bookings Database
+The booking system data base contains all the configuration information
+describing the various objects in the systems, and also all bookings
+that have been made.
+
+The database is replicated over multiple hosts with each replica able
+to accept updates. This minimised the effect of network or server disruptions.
+
+
+
+@menu
+* Databases::
+* Changes::
+* BOOK_DATABASE::
+* BOOK_MAINT::
+* Creating new replicas -- BOOK_COPYDB::
+* Removing replicas::
+@end menu
+
+@node Databases, Changes, Bookings Database, Bookings Database
+@section Databases
+There are several databases (gdbm files) most of which contain multiple
+tables. The separation into different files is an artifact of part of
+the implementation and not very significant.
+
+Each database file provides lookup of some content given a key.
+Keys are chosen to be unique across all tables in a given database file.
+The content is often stored in machine independent External Data Representation
+(@var{xdr}) format.
+
+The four database files are @code{REPLICA} which records information
+about the active database replicas, @code{CONFIG} which contains fairly
+static configuration information, @code{BOOKINGS} which contains highly
+dynamic booking information, and @code{ALLOCATIONS} which may one day
+record all the allocations that have been made.
+@table @code
+@item REPLICAS
+This contains all known active database replicas.
+There may be database replicas running that are not in this list,
+however these will not accept new changes, they will only copy changes from
+other replica. It contains one table.
+@table @samp
+@item server-name
+An integer representing
+number of changes from that server which have been included into this
+database.
+@end table
+
+@item BOOKINGS
+Contains all the bookings that have been made, including those that have
+been cancelled.
+The bookings are indexed by both when and where the booking is for, and
+who it is for. There is also some summary information.
+
+The tables within the database are:
+@table @samp
+@item ByTime
+ This table contains all the bookings. The key is a triple of
+ day-of-year, period-of-day, and lab-number.
+ The content is a list of bookings, each of which contains:
+ @table @samp
+ @item who_for
+ The user id or class id that workstations will be reserved for.
+ @item who_by
+ The user id who made the booking, and hence to whom the booking is
+ charged and to whom it may be refunded. This is normally the same as
+ @samp{who_for}.
+ @item ws_count
+ The number of workstation to be reserved, normally 1.
+ @item token
+ The id number of the token used for the booking.
+ @item timestamp
+ The time (in second since epoch) that the booking was made.
+ @item status
+ The status of the booking which may be one of PENDING, ALLOCATED,
+ REVOKED, REFUNDED, CANCELLED, FREEBIE
+ @item charged
+ A machine attribute set indicating which class of machines the booking
+ was tentatively allocated to.
+ @item request
+ An attribute set which is a subset of the token attributes, and
+ indicates attributes that are particularly asked for.
+ This is essentially unused at present.
+ @item allocations
+ The list of workstations that booking was allocated to.
+ @item claim_status
+ This records information about how and when the booking was claimed.
+ It has four booleans and an integer:
+ @table @code
+ @item DID_LOGIN
+ This is set to @code{True} when the user logs in during the
+ allocation time, in the lab of the booking.
+ @item DID_DEFAULT
+ This is set to @code{True} if, when the grace period expired,
+ the user was not logged on to their allocated workstation.
+ @item WAS_TENTATIVE
+ This is set to @code{True} if the allocation was made as a
+ @code{Tentative} allocation. This is information for human
+ viewers only and is not used by TABS.
+ @item LOGIN_ON_ALLOC
+ This is set when @code{DID_LOGIN} is set, if the user logged in
+ on the workstation to which they were allocated.
+ @item when_on
+ This is set to the time in the period when @code{DID_LOGIN} was
+ set. This will range from -10 minutes to 20 minutes.
+ If set to -10, it means that the user was logged in when
+ allocation were made.
+ @end table
+
+ @end table
+
+@item utilisation
+ This table records how many of which sort of machine has (tentatively)
+ been allocated so far.
+ The key is a triple of day-of-year, period-of-day, and machine
+ description, and the content is a number of workstations of that type
+ allocated at that time.
+
+@item ByUser
+ This table provide an index to the bookings by user id. It also
+ provides a summary of tokens used.
+ The key is simply a user id.
+ The content contains two lists of booking keys, one for pending
+ bookings, one for all other bookings.
+ The booking key is the same as the key for ByTime, combined with the
+ timestamp of the booking.
+ The summary of tokens used is simply a list of token numbers and usage
+ counts.
+ A token number with a high bit set indicates a privileged refund, and
+ the count will be negative.
+@end table
+
+@item CONFIG
+The CONFIG database contains all the (fairly) static configuration
+information about such things as hosts, workstations, tokens, attributes.
+The tables included in the database are:
+@table @samp
+
+@item Numbers
+Maps Names and types to id numbers. The types are: HostGroup,
+Host, Workstation, Token, Attribute, and Class.
+
+Note that Labs are also Attributes and so do not have separate names.
+
+@item Names
+This is the inverse of Numbers and maps types and id numbers to names.
+
+@item Workstations
+Maps workstation id to:
+@table @samp
+@item Attribute set
+ which describes the attributes of the workstation
+@item time_disabled
+ Which stores the time that a workstation was marked out-of-service, or 0 if it
+ is in service.
+@item why_disabled
+ A string indicating why and by whom the workstation was disabled.
+@item host
+ The hostid of the host which controls this workstation.
+ If a workstation can select between any of the hosts in the HostGroup,
+ then this field is set to -1.
+@end table
+
+@item Workstation_count
+ Maps an attribute set to the number of (in service) workstations
+ with that attribute set.
+
+@item HostGroups
+Maps a HostGroup id to a list of hosts in that HostGroup, and a list of
+labs served by hosts in the HostGroup.
+
+@item Hosts
+Maps a host id to a list of workstations served by that host, and the id
+of the HostGroup containing the host.
+
+@item Labs
+Maps a lab id to a list of workstation in that lab, and the id of the
+hostgroup which serves that lab.
+
+@item Tokens
+Maps a token id to the token description.
+
+@item Allotments
+Maps a user or class id to a list of token allotments for that
+entity. This list is a list of pairs of token id and count, where the
+count is non-zero.
+User id 0 always maps to a list containing an allotment of 1 of each
+defined token.
+
+The total allocation for a user is the sum of the individual allocations
+to that user and to all of the classes (netgroups) which the user is in.
+
+@item General
+This contains some ad-hoc string to string mappings.
+These include:
+@table @samp
+@item book_level
+Can be @samp{off} to disable evictions and reservations, or @samp{on}
+to fully enable the booking system.
+@item book_advance
+A number which indicate how far in advance the second
+part of a token comes into effect
+@item grace
+A number which is the number of minutes into a period for
+which a workstation will be held reserved for the allocated user.
+@item min_class_uid
+The minimum uid for classes, and hence one more than the maximum uid of
+users. Default value is 4000,0000 in hexadecimal.
+
+@end table
+
+@item Attribute_types
+This contains a single record recording the types of various attributes.
+There are 3 attribute set which contain:
+@itemize @bullet
+@item All defined attributes
+@item All required attributes
+@item All Lab attributes
+@end itemize
+and 5 special attribute numbers:
+@table @samp
+@item open
+which must be set for times when a lab is open. i.e. when allocations
+should be performed.
+@item closed
+which must be set for times when a lab is closed.
+@item available
+which must be set on any workstation which is not out of service
+@item reusable
+which should be set in any token which is always refunded
+@item firmalloc
+which should be set in a token which is use to make firm (supervised)
+class bookings.
+@end table
+Attributes are described in more detail in 'Configuration' --- 'Bitstrings'.
+
+@item Attribute_definitions
+This contains an ordered list of attribute implications.
+Each entry in the table contains a number of implications and also the
+total number of implications all together.
+Each entry is keyed by the index of the first implication that the entry
+contains. e.g if key @emph{0} mapped to the first 4 implications, then key 4
+would map to the next few implications.
+Attributes definitions
+are described in more detail in 'Configuration' --- 'Bitstrings'.
+
+An implication contains:
+@itemize @bullet
+@item a start and end day of the year
+@item a start and end day of the week
+@item a start and end period of the day
+@item a set of requisite attributes
+@item a set of anti-requisite attributes
+@item a single attribute to set if the period and current attributes
+match the requirements.
+@end itemize
+
+@end table
+@item ALLOCATIONS
+Not implemented at the moment. It is meant to record all the
+allocations that have been made in the labs.
+@end table
+
+@node Changes, BOOK_DATABASE, Databases, Bookings Database
+@section Changes
+As mentioned before changes can be given to any of the replicas in the
+system. The changes that have occured at a database manager are stored
+in the @file{db_log} file (/var/book/db_log). This file contains a header for each
+replica, containing the following fields
+@table @code
+@item lastchangenum
+The number of the last change received from that replica.
+This should match the number in the @code{REPLICAS} database.
+@item lowestchangenum
+The lowest number change still stored in the database.
+@end table
+
+
+
+@menu
+* Types of Changes::
+@end menu
+
+@node Types of Changes, , Changes, Changes
+@subsection Types of Changes
+The changes are designed as much as possible to be commutable. This
+means that it should not really matter which order changes from other
+database managers are applied, they should succeed. There are a number
+of different types of changes,
+@table @samp
+@item CHANGE_WS
+Change the information about a workstation.
+Giving a workstation an attribute list that does not contain any lab
+attribute will delete the workstation.
+@item CHANGE_HOST
+Change the hostgroup which a host is a member of.
+Setting the hostgroup to -1 removes the host.
+Note that this does not remove the mapping from the NAMES database.
+@item CHANGE_LAB
+Change the hostgroup that a lab is in.
+There must be no workstations in the lab for this to work.
+Setting the hostgroup to -1 deletes the lab.
+@item ADD_SERVER
+Adds a new server to the list of replicas.
+@item DEL_SERVER
+Removes a server from the list of replicas.
+This change is normally sent to the server being deleted.
+This makes sure all changes from that server are propagated properly.
+@item ADD_BOOKING
+Add a booking to the database.
+This can also be used to change the number of workstations reserved by
+the booking.
+@item CHANGE_BOOKING
+Change the state of the booking. This is done
+when cancelling or allocating bookings.
+When allocation bookings, the @code{CHANGE_BOOKING} request can also
+contain a list of workstations to which the booking was allocated, and
+an indication of whether the allocation was tentative, and whether the
+user was already logged on.
+@item CLAIM_BOOKING
+Set the @code{claim_status} information for a booking.
+This change can set any of the boolean values in @code{claim_status} to
+@code{True}, or can set then @code{when_on} value.
+It is used when a user logs on, and when @code{book_manager} notices
+that the grace period has expired.
+@item REMOVE_BOOKING
+Removed booking information. This is to save
+space in the booking database. It should be done very carefully. The
+operation checks that there are no outstanding bookings, so ensure all
+allocations have been performed before doing it.
+@item REMOVE_USER
+Remove token usage information for a user. This is done at the end of a
+session (or semester or term) to provide a clean slate for the new
+session.
+REMOVE_USER can only remove information for users who have no bookings
+(past or pending) recorded, so REMOVE_BOOKING should be used first.
+@item ADD_TOKEN
+Add a new token definition.
+If the lengths of the description are zero, the token is removed.
+Root is automatically alloted one of every token.
+@item ADD_CLASS
+Change the number of tokens allocated to a class or user.
+The number sent is added to the number already allocated, and may be
+negative.
+@item IMPLICATIONS
+Set the implications information in the CONFIG database.
+@item ATTR_TYPE
+Set the attr_type information.
+@item CONFIGDATA
+Add some generic configuration information
+@item SET_NAMENUM
+Add a mapping between a name and an id number.
+If the name is the empty string, any mapping is removed.
+@end table
+
+Changes are stored with a key of the change number plus the originating
+replica. The value is just the whole @code{book_changeent} structure.
+This allows requests to be made to fetch changes and give them to other
+database managers.
+
+Old changes can be purged from the log_file once they are at least one
+day old and have been copied to all registered replicas.
+
+
+@node BOOK_DATABASE, BOOK_MAINT, Changes, Bookings Database
+@section BOOK_DATABASE
+The @file{book_database} program is responsible for providing network
+access to the booking system database.
+It will accept changes as described above and impose them on the
+database, and will return any information requested from the database.
+
+It will also, on request, provide a complete copy of the database, so
+that a new replica may be started. While it is doing this, it will not
+accept any changes as this would corrupt the database copy being sent.
+
+@file{book_database} will fork the @file{book_maint} program which
+copies changes from other replicas to this replica, thus keeping all the
+database copies in synchrony.
+
+
+Each database replica may be in one of three state with respect to
+changes which it will accept.
+@table @samp
+@item full update mode
+All changes will be accepted.
+Most clients of the database will only accept information from a
+database in this state.
+@item copy only mode
+Only changes being copied from some other
+replica will be accepted. New changes are rejected.
+This allows a replica which has been out of action for a while to get
+up-to-date with other replicas before entering full service.
+
+The @code{book_database} program will automatically go into this mode if
+it has not been explicitly told that it is in synchrony with other
+replicas for a period of 10 minutes.
+
+@item no update mode
+No updates will be accepted.
+A replica enters this mode while it is transferring a copy of the
+database, or when it notices an internal error.
+@end table
+
+@node BOOK_MAINT, Creating new replicas -- BOOK_COPYDB, BOOK_DATABASE, Bookings Database
+@section BOOK_MAINT
+The @code{book_maint} program is responsible for keeping all the
+database replicas in synchrony with each other by copying changes from
+one to another.
+For each replica, there is one @code{book_maint} process which copies
+changes from other replicas to this replica.
+
+If @code{book_maint} cannot contact some other replica, it will try to
+copy changes that originated at that replica from another replica.
+
+@code{book_maint} checks the other replicas for new changes every
+minute. If it determines that all changes have been copied to the local
+database, it tells the local database that is it in synchrony so that it
+will stay in @code{full update} mode.
+
+@node Creating new replicas -- BOOK_COPYDB, Removing replicas, BOOK_MAINT, Bookings Database
+@section Creating new replicas -- BOOK_COPYDB
+
+The first database replica is created by running @file{book_database}
+with a @code{-I} flag (which requests it to initialise the databases).
+All other new replicas should be created with the @file{book_copydb} program.
+It is given the name of a server to copy from.
+
+Creating a fresh new database should be done with great care as having
+two independent database servers in the one network would be very
+problematic.
+
+If @code{book_copydb} is successful it will leave the database files in
+the book directory (normally @file{/var/book}) as files with names
+starting @file{db_}.
+
+With this done, it is only necessary to start @file{book_database}
+running and the replica will be available and kept in synchrony.
+
+Before the replica will be full functional it must be added to the
+replica list with the @code{dbadmin -a} command.
+This will cause it is start accepting changes and cause the other
+replicas to collect changes from it.
+
+@node Removing replicas, , Creating new replicas -- BOOK_COPYDB, Bookings Database
+@section Removing replicas
+
+The preferred way to remove a replica is to first delete it from the
+replica list with @code{dbadmin -d}. Once all other replicas have
+removed it from their replica lists, the @file{book_database} process
+can be killed and the files removed.
+
+If this is not possible, because the files or host supporting that
+replica are unavailable (host down, files corrupted), then the @code{-r replica}
+flag should be given with the @code{dbadmin -d} command to tell some
+other replica that the unavailable replica has been removed.
+The replica told should be the one that has received the most changes
+from the replica to be deleted, though hopefully all replicas will be
+equally up-to-date.
+
+Once all replicas have removed knowledge of the replica to be deleted from their
+lists, it is safe to remove the database files,
+and start a new database server to replace the deleted replica.
+
+
+@node Laboratory Status and Management, The full scoop on tokens and attributes, Bookings Database, TOP
+@chapter Laboratory Status and Management
+
+Each host within the booking system runs a pair of programs called
+@file{book_status} and @file{book_manager} which together monitor the
+status of the workstations and hosts, and perform the proactive tasks of
+the booking system such as workstation allocation and eviction.
+
+
+
+
+@menu
+* Table of Status Information::
+* BOOK_STATUS::
+* BOOK_MANAGER::
+@end menu
+
+@node Table of Status Information, BOOK_STATUS, Laboratory Status and Management, Laboratory Status and Management
+@section Table of Status Information
+
+All the status information that the booking system needs about the
+workstations and hosts in a given hostgroup is stored in a table.
+This table is passed from host to host with each host updating any
+entries which it has new information about.
+Thus every host in a host group knows the status of everything in the
+hostgroup.
+
+The table contains a number of records which hold different types of
+information. Each record has a timestamp which is updated when
+information in the record is modified. When a new table arrives at a
+particular host, it is merged with the current table by taking the most
+recent of each record present.
+
+A record contains:
+@itemize @bullet
+@item type
+@item identifier
+@item timestamp
+@item length of data
+@item data@code{[]}
+@end itemize
+
+Each record has a type and an identifier.
+The five different record types are:
+@table @code
+@item TABLERECORD
+This record refers to the whole table. The identifier is the identifier
+for the hostgroup. The data contains the id of the host which created the
+table.
+When two tables are merged, the table with the most recent
+@code{TABLERECORD} is considered primary and the set of records in
+that table determines the set of records in the resulting merged table.
+
+@item HOSTRECORD
+Contains information about the status of the host identified by the
+identifier.
+There is one of these for each host in the hostgroup.
+The data contains the status of the host, whether up or down.
+
+@item ALLOCRECORD
+This record records information about the last time an allocation was
+performed.
+There is one of these per lab.
+The time stamp is the time the allocation was for (rather than the time
+the allocation was made).
+
+@item WSRESRECORD
+There is one of these for each workstation in the host group.
+It records the result of the most recent allocation (See allocations
+below XREF!!). This includes the status of the allocation and the user
+or class that was allocated. It also records whether the allocation was
+@code{firm} or @code{normal}.
+
+@item WSSTATUSRECORD
+This record records the state of a workstation. It contains the status
+of the workstation (up or down), who is logged on, when they logged on,
+which host they are logged on to, and the last time that they were
+allocated to the workstation.
+@end table
+
+@node BOOK_STATUS, BOOK_MANAGER, Table of Status Information, Laboratory Status and Management
+@section BOOK_STATUS
+The @file{book_status} program is an rpc server which simply stores
+status information about the hostgroup and the booking system.
+If provides this information on request and will change it on request.
+
+The information it stores is the status table described above and a list
+of known database replicas.
+
+
+
+@menu
+* Status Table::
+* Replica List::
+@end menu
+
+@node Status Table, Replica List, BOOK_STATUS, BOOK_STATUS
+@subsection Status Table
+The status table can be changed either by sending a whole new table
+which is merged with the current table, or by sending change requests
+which change either the user who is logged on, or the user who is
+allocated to a particular workstation.
+
+As UDP is used for all rpc calls, and because the status table can get
+rather large, it is normally transferred in chunks of 20 records.
+
+Whenever @file{book_status} receives a copy of the table it signals it's
+partner @file{book_manager} process (with @code{SIGALRM}) to tell it
+that a new table is available.
+
+The protocol for sending a copy of the table to a @file{book_status}
+process tags each chunk sent with a time stamp (seconds since Unix
+epoch) so that the receiver can be certain whether or not chunks that
+arrive together are actually related.
+If two tables arrive at the same time, chunks interleaved, then the one
+with the later time stamp is accepted. If the time stamps are the same,
+then one one which was seen first is accepted.
+If a chunk arrives with a time stamp which is more than 3 minutes
+different to the current time, then the chunk is rejected. This allows
+for ignoring hosts with incorrect clocks, and guards against the
+possibility of a table with a timestamp in the far futre partially
+arriving and thus blocking all other arrivals.
+
+In normal operation, a table will be collected from a @file{book_status}
+as often as one is sent to it, or slightly more often as tables are
+collected for other purposes such as lab status monitoring. If tables
+stop being collected, then something is wrong, typcially the
+@file{book_maint} process is failing. If this happens, in particuilar
+if three consecutive tables are received without any being taken, then
+@file{book_status} will stop accepting tables, so that the upstream host
+will treat it as being down, and will exclude it from the system.
+
+@node Replica List, , Status Table, BOOK_STATUS
+@subsection Replica List
+@code{book_status} maintains a replica list which it keeps sorted in
+order of preference. Replicas that are up and accepting all updates are
+preferred over replicas that are not accepting updates or are down.
+
+Each @code{book_status} program can be told that some replicas are
+@emph{close by}. These replicas will be sorted early if they appear to be up.
+
+The replica list is initialised from a file and changes are stored in
+that file, so any changes to the replica configuration will be
+persistently remembered by every host.
+
+@node BOOK_MANAGER, , BOOK_STATUS, Laboratory Status and Management
+@section BOOK_MANAGER
+The @code{book_manager} process is responsible for passing the status
+table around the hostgroup, and for performing the proactive tasks of
+the booking system.
+
+
+
+@menu
+* Table Passing::
+* Eviction::
+@end menu
+
+@node Table Passing, Eviction, BOOK_MANAGER, BOOK_MANAGER
+@subsection Table Passing
+When a new table arrives at a @code{book_status} process, it signals the
+@code{book_manager}.
+The @code{book_manager} will then normally collect the table from the
+@code{book_status} and send it on to the next host in the hostgroup that
+is up.
+If that host appears to be down, it is marked as down in the table and
+the new table is sent back to the @code{book_status} that is was
+collected from. This causes another signal to be sent and the
+@code{book_manager} will try to send the table to the next host.
+
+The first host in the table which is up is considered to be the manager
+for the hostgroup. It behaves slightly differently.
+When a table arrives at the hostgroup manager (it will probably have
+been sent by the last host in the hostgroup), the
+@code{book_manager} does not pass it on immediately, by waits until 30
+seconds have passed since it last sent a table before passing it.
+This means that the table goes around the lab at most once every 30
+seconds.
+
+Also, if any host is down and has not had its HOSTRECORD updated for
+more than 5 minutes, the hostgroup manager will mark the oldest such
+record as up, thus attempting to re-include it in the table passing
+(incase it has in fact come up in the mean time).
+
+Another task of the @code{book_manager} is to pole all workstation owned
+by the host or (only for the hostgroup manager) not owned by any host to
+make sure the recorded status is correct.
+
+The @code{book_manager} notes when the grace period for any allocation
+expires, and check to see if the allocated user has logged on. If they
+ahve not, a @code{default} is recorded for that bookings.
+
+@node Allocation, Eviction, Table Passing, BOOK_MANAGER
+
+@subsection Allocation
+Allocations are made every 30 minutes i.e. for each booking period.
+Allocations are made 10 mins before the period starts so that there is
+time to evict the current user (if required). The hostgroup
+@code{master} is responsible for making the allocations.
+
+
+An entry is placed in @file{/var/book/book_errors} showing the time it
+made the allocations. There is also a file in
+@file{/var/book/book.dump} into which is written a copy of the
+lab status table, formatted that same way the @code{smadmin -t} formats
+it, immediately after allocations were made. This can be
+useful in tracing through exactly what happened when a complaint is received.
+
+The allocation process is described in the Concepts chapter.
+
+@node Eviction, , Table Passing, BOOK_MANAGER
+@subsection Eviction
+After allocations have been made, the book_manager will being the
+process of evicting anyone who is logged on to a workstation to which
+someone else has been allocated.
+
+This process starts by displaying messages on the workstation warning
+the user that they will have to log off soon (and telling them how long
+they have left).
+If the user has not logged of by the time that the new allocation is to
+take effect, book_manager forces the eviction by sending a SIGTERM
+signal to the @emph{xdm} process which is controlling the login session. This
+causes @emph{xdm} to reset the server which in-turn breaks any connection that
+the user had with the Xserver.
+
+@emph{xdm} with, as part of it's cleanup, run the @emph{Xreset} script. This
+script should call the @emph{book_logout} program which informs the booking
+system that the user has logged out, and may kill any remaining
+processes belonging to the user (depending on how it is configured).
+
+@emph{book_manager} determines the process id of the @emph{xdm} by looking in the
+file @file{/var/book/xdm-pid/@var{workstation-name}} which should have
+been setup properly by the Xstartup script.
+
+@emph{book_manager} uses the services of @emph{messaged} to display warning
+messages. For this to work, the file
+@file{/var/X11/xdm/save_auth/@var{workstation-name}} must have been
+setup to contain appropriate Xauthority information.
+
+To help track the eviction process, for use when responding to
+complaints about unfair treatment, book_manager keeps a log of all its
+eviction actions in @file{/var/book/evict_log}.
+This file contains the time, host, workstation, userid-being-evicted,
+time until eviction and time since last warning. A record in written
+whenever a messages is sent, an xdm is signalled, or when the eviction
+process is halted, such as when the user logs off.
+
+
+
+
+
+@node The full scoop on tokens and attributes, Setting it up, Laboratory Status and Management, TOP
+@chapter The full scoop on tokens and attributes
+
+@menu
+* Attributes::
+* Implications::
+* Attributes and subspaces::
+* Reusable versus non-reusable::
+* Firm Allocations for class bookings::
+* Advance and Late bookings::
+* Privileged Tokens::
+* Putting it together::
+@end menu
+
+@node Attributes, Implications, The full scoop on tokens and attributes, The full scoop on tokens and attributes
+@section Attributes
+
+Attributes are used for classifying workstations and time periods, are
+used to control when labs are open or closed, and when assigned to
+tokens, are used to controlling bookings and access to workstations and
+time periods.
+
+Attributes are defined using the @file{attr} program. This program reads
+specifications which define attributes and define their associated
+interrelationships using implications.
+
+Attributes are defined, one per line, by the following specification:
+@display
+@var{attribute-number} @samp{:} @var{attribute-name} [ @var{flags} ]
+@end display
+where flags are optional and may be one or more of the following:
+
+@table @code
+@item optional
+This flag indicates that the attribute is not a required attribute. The
+concept of required attributes are defined and discussed under
+@ref{Attributes and subspaces}.
+
+@item lab
+This flag indicates that the attribute is actually a lab name. Workstations
+get registered as being in a particular lab by having this attribute set.
+
+@item closed
+This flag marks the distinguished attribute which is used to mark a lab as
+being closed. If that attribute is assigned to a given lab at a given
+time, then that lab is deemed to be closed at that time.
+
+The attribute flagged with @code{closed} should always be required (not
+flagged @code{optional}) and should not be set in any token.
+
+The attribute flagged with @code{closed} is usually also named
+@samp{closed} for clarity, but it need not be.
+
+@item open
+This flag is similar to @code{closed} flag except that the attribute that it
+flags is used to mark a lab/time as open, so that allocations will be made
+as necessary.
+
+The attribute flagged with @code{open} should be included in all tokens,
+or marked @code{optional} (in which case some other mechanism would be
+needed to restrict bookings to times when the lab is open).
+
+The attribute flagged with @code{open} is usually also named
+@samp{open} for clarity, but it need not be.
+
+@item available
+This flags the attribute which is normally assigned to
+all working workstations. If a workstation becomes sufficiently broken
+that it is not expected to be in service for some time, it should have
+the @code{available} attribute removed (with the @code{ws}
+program). This will, among other things, reduce the number of bookings
+which the booking system will accept in that lab.
+
+The attribute flagged with @code{available} is usually also named
+@samp{available} for clarity, but it need not be.
+
+@item reusable
+This flags the attribute which is used to mark tokens as
+being reusable tokens.
+
+@item firmalloc
+The flags the attribute which is used to mark a token as requiring a firm
+allocation. This means that the allocation will be held for the full
+period of the booking, not just the first few minutes.
+This in normally only used for supervised class bookings.
+
+@end table
+
+@node Implications, Attributes and subspaces, Attributes, The full scoop on tokens and attributes
+@section Implications
+Implications are used to define more general attributes from specific
+attributes and/or times. The intention here is to combine specific
+attributes which are usually assigned to particular workstations (and
+which usually include at least one @code{lab} attribute), with specific
+times, days, or dates to produce attributes that are useful for
+defining tokens and/or opening and closing times for labs.
+The implications involving opening and closing times will usually
+(and fairly obviously) involve the attributes that were flagged @code{open} and
+@code{closed} (mentioned in the previous section).
+
+Implications are defined to the booking system using the @file{attr}
+program. This program reads specifications which define attributes and
+which define their associated interrelationships using implications.
+
+Implications are defined, one per line, according to the following
+specifications:
+@example
+@var{implication} = @var{premise} @samp{->} @var{attribute-name}
+
+@var{premise} = @{ @var{dates} | @var{days-of-week} | @var{times-of-day} @} @{ @var{included-attribute} | @var{excluded-attribute} @}
+
+@var{dates} = @var{day-of-month} @var{month} [ @samp{-} @var{day-of-month} @var{month} ]
+ eg: @code{25jul} or @code{01feb-30apr}
+
+@var{day-of-month} = @var{digit} @var{digit}
+
+@var{month} = @samp{jan} @dots{} @samp{dec}
+
+@var{days-of-week} = @var{day-of-week} [ @samp{-} @var{day-of-week} ]
+ Note: The week is from Sunday to Saturday, so @code{sa-su} is
+ not valid.
+
+@var{day-of-week} = @samp{su} @dots{} @samp{sa}
+
+@var{times-of-day} = @var{time} [ @samp{-} @var{time} ]
+ Note: A single time (eg: @code{6:30}) indicates the half hour period
+ starting with that time and so is equivalent to the range from that
+ time to the half hour later (@code{6:30-7:00}).
+
+@var{time} = @var{digit} [ @var{digit} ] @samp{:} @var{digit} @var{digit}
+ Note: this is a 24 hour time with a precision of 30 minutes
+ eg: @code{6:30} or @code{17:00}
+
+@var{included-attribute} = @var{attribute-name}
+ eg: @code{weekend}
+
+@var{excluded-attribute} = @samp{!} @var{attribute-name}
+ eg: @code{!publicholiday}
+
+@end example
+
+To understand implications, it helps to understand how they are
+processed.
+
+The processing starts with some particular date and time, and a set of
+specific attributes. The attributes will be that attributes of some
+workstation, or a single @code{lab} attribute.
+
+Then each implication is tested in turn. If the date and time match all
+the time ranges given, and all the @emph{included} attributes are
+currently in the attribute set, and none of the @emph{excluded} are in
+the attribute set, then the implied attribute is added to the attribute
+set.
+
+The resultant attribute set is then used, either to compare with a
+tokens attribute set, or to test for the @code{open} or @code{closed}
+attribute.
+
+NEED SOME EXAMPLES
+
+
+@node Attributes and subspaces, Reusable versus non-reusable, Implications, The full scoop on tokens and attributes
+@section Attributes and subspaces
+
+In order to understand fully how tokens and attributes work, it is
+helpful to consider the space of all possible workstation time periods.
+
+This is a two dimensional space, one dimension being all the
+workstations known to the booking system. The other being all the half
+hour periods, 48 per day, 365 (or 366) days per year.
+
+Each of the points in this space corresponds to a particular workstation
+during a particular half hour period.
+Each point has associated with it it's own, possibly unique, set of
+attributes.
+Some of these attributes come from the workstation. Others come from the
+implications which will probably include some termporal information.
+
+Each attribute will appear in the attribute set of some subset of the
+points in the space. Each such subset of points (or subspace) can be thought
+of as being defined by the corresponding attribute. Thus each attribute
+defines as subspace of the space of workstation time periods.
+
+For example, the @code{lab} attribute defines the space of all
+workstation time periods where the workstation is in the given lab.
+An attribute called @code{weekend} defined by
+@example
+su -> weekend
+sa -> weekend
+@end example
+would define a space of workstation time periods where the time period
+is on a Saturday or a Sunday.
+
+There are a couple of attributes with predefined meanings such that the
+space that they define has a specific meaning to the booking system.
+The @code{closed} attribute defines a space of workstation time periods
+where nobody may log in.
+The @code{open} attribute defines a space where allocations are made,
+and therefore where bookings can be made for.
+The @code{available} attribute defines a space of all workstations which
+are deemed to be usable. Any workstations outside this space are not
+bookable, and will reject all login attempts.
+
+Some attributes define spaces which are not, in themselves,
+interesting. They are only intermediate spaces used in defining more
+interesting spaces. The attributes @code{normalopen} and
+@code{normalclosed} in @ref{Setting it up} are examples of this. These
+attributes should be marked optional so that they are not involved in
+the evaluation of tokens.
+
+Token have associated with them, a set of attributes (actually two sets
+--- an advanced booking set and a late booking set, but this distinction
+is not relevant to the current discussion). The attribute set defines
+that subspace of the workstation time period space which can be booked
+using the token. Unfortunately however, the subspace defined by a token
+is not simply a union or intersection of the subspaces defined by the
+attributes in the token.
+
+Rather, a token's subspace is the complement of the union of the
+subspaces defined by the non-optional attributes which are @emph{not} in the
+token's attribute set. That is, a token's subspace is the set of all points
+which may or may not have attributes out of the token's attribute set,
+but which do not have any other interesting, non-optional attributes.
+
+Another way of looking at it, is to look at the situation from the
+workstation/period point of view (rather than the token's perspective):
+An individual workstation/period with a given set of non-optional
+attributes @emph{can only} be booked by a token that also contains at
+least these non-optional attributes. Note that the token may additionaly
+contain other optional and non-optional attributes, but these are
+irrelevant with respect to this individual workstation/period in
+question.
+
+To see how this is effective, it is best to consider the normal (or at
+least, the recommended) way of defining attributes.
+
+@menu
+* Choosing attributes::
+@end menu
+
+@node Choosing attributes, , Attributes and subspaces, Attributes and subspaces
+@subsection Choosing attributes
+A good way to choose attributes, or at least the
+@strong{interesting/non-optional} attributes is to choose some groups of
+attributes such that the subspaces defined by the attributes in the
+group are non-intersecting, and span the entire space. To put this
+another way, the attributes in a group serve to classify every
+workstation time period into one of a small number of classes.
+
+Some example of such attribute groups are:
+@itemize @bullet
+@item
+The lab attributes. Each workstation is in precisely one lab.
+@item
+@code{weekend}, @code{weekday}, @code{publicholiday}, could uniquely
+classify every day, if we chose @code{weekday} to only include normal
+week days that are not @code{publicholiday}s.
+@item
+@code{session}, @code{break}, @code{outofsession} could distinguish the
+different periods of the year.
+@item
+@code{wk1}, @code{wk2}, ..., @code{wk15}, @code{midsession},
+@code{endofsession}, @code{outofsession} could provide a finer grained
+classification of the year.
+@item
+@code{daytime} and @code{evening} could be used if there was a need to
+give some priority to evening students.
+@item
+@code{open}, @code{closed}, and @code{free} could classify the labs/times
+which are open for bookings, closed baring access, or free for
+unrestricted use.
+@end itemize
+
+Given a collection of attribute groups chosen in this manner to be
+spanning and non-intersecting, the attributes for a token can be chosen
+to be just the desired attributes out of each group.
+The subspace defined by the token would be the intersection of the
+groupwise unions of the subspaces defined by the attributes.
+
+@node Reusable versus non-reusable, Firm Allocations for class bookings, Attributes and subspaces, The full scoop on tokens and attributes
+@section Reusable versus non-reusable
+
+The previous section showed how the range of times and workstations
+for which a token is valid can be controlled with a great deal of
+precision. There is, however, a lot more to understanding tokens, as
+this and subsequent sections will detail.
+
+When creating a token, it can be marked as @emph{reusable}. This is
+done simply by setting a particular distinguished attribute (which is
+really overloading the meaning of what an attribute is, but was done
+as an implimentation convenience).
+
+If a token is marked as @emph{reusable} then when a booking is
+allocated that was made with that token, the token is returned to the
+user for further use.
+
+If a token is not marked as @emph{reusable} then after allocation, the
+token is normally not returned to the user for further use, unless the
+lab was underutilised at the time of allocation. This exception was
+introduced to encourage users to make bookings for the less popular
+labs and/or times.
+
+@menu
+* Reusable tokens as shares::
+* Non-reusable tokens --- for getting the job done.::
+@end menu
+
+@node Reusable tokens as shares, Non-reusable tokens --- for getting the job done., Reusable versus non-reusable, Reusable versus non-reusable
+@subsection Reusable tokens as shares
+
+Setting a limit on the number of reusable tokens available to a
+particular user limits the total number of bookings that can be
+outstanding, or pending, at any one time. The macroscopic effect of
+this is not at first obvious as the actual effect depend a lot on how
+other people book.
+
+The effect turns out to be that each token works like a @strong{share},
+and that the avalable workstation time periods are shared out among the
+people who want them in proportion to the number to tokens or
+@dfn{shares} that they each have.
+
+To see how this works, consider a senario in which, desparate for
+workstation time, each user books for the first available time slot as
+soon as any token is returned to them for reuse.
+In this senario, the immediate future will be solidly booked for some
+fixed amount of time which will depend on the total number of tokens
+allocated, and the total number of workstation periods available.
+Lets suppose that this totals three days.
+
+Then, a person with 10 tokens allocated to them will have booked 10
+periods, or 5 hours during that 3 day period. A different person with
+only 6 tokens will have booked only 3 hours worth of time. Providing
+that these two users book equally aggressively, this proportion of
+bookable time will remain the same, whether other users continue to
+book aggressively or not.
+
+In reality, people will not book as agressively as pictured
+here. Certain times of day will be more popular, and certain weeks of
+the session will be more popular. The more popular times will be more
+solidly booked out, and will only be able to be booked further in
+advance. The further in advance a user books, the more time they are
+without their token, and so the fewer booking can be made with that
+token. This will automatically reward people for booking less popular
+times, as they will get their booking sooner, get their token back
+sooner, and be able to book again sooner.
+
+
+Reusable tokens have other benefits. They are quite easy to manage as
+there is not the problem of users running out of tokens (not
+permanently anyway), and because the actual booking rights conferred
+by such token are dynamically determined, based on load, the number
+allocated to each different class of student need not precisely
+reflect their need.
+
+The one disadvantage of reusable tokens is that they do not allow the
+user to plan a long way in advance how the will book their time. It is
+unusual to book more than a week in advance. While this is a
+theoretical disadvantage, it may not have significant practical
+applications, as students are not generally known for a tentancy to
+plan ahead.
+
+At the authors site, reusable tokens are now the only tokens
+used. Unfortunately, we found that allocating large numbers of
+reusable tokens had a suprising and undesirable effect: many users
+would use their tokens to make large numbers of consecutive bookings
+most of which were defaulted upon. It appeared as if these users were
+using the booking system to reserve their option to turn up and use a
+terminal effectively whenever they felt like doing so. They obviously
+did not care about the penalty of being declared a defaulter, and did
+not mind having to claim their bookings from a booking terminal. They
+had an endless supply of tokens and would use them to buy the freedom
+to use a terminal whenever they liked, regardles of how many others it
+may have inconvenienced. Note that although it is true that this
+behaviour could only continue as long as everyone did not behave the
+same way, most users did not behave like this either because they
+hadn't thought of it, or because it went against the (implied)
+original principles of the booking system.
+
+@node Non-reusable tokens --- for getting the job done., , Reusable tokens as shares, Reusable versus non-reusable
+@subsection Non-reusable tokens --- for getting the job done.
+
+Non-reusable tokens were, in an earlier version, the only sort of
+tokens. While they have fallen out of favour at the author's site,
+they are described here for completeness and historical interest, and
+because someone may find a genuine use for them.
+
+The idea behind a non-reusable token is that booking rights are given
+for a purpose --- to get some specific piece of work done, typically an
+assignment.
+
+The sponsor of the work (the lecturer who set the assignment) would
+determine how much time the assignment required (or should require),
+and would determine when the work should be done (between when the
+assignment was set and when it was due). Also, and specfic needs of
+the assignment, such as a particular lab, would be determined.
+
+Then a token would be created for that assignment, and the appropriate
+number would be allocated to everyone doing that assignment.
+
+The advantage of this approach is that tokens have easily
+understandable meanings. People know from the start of session how
+much time they can book, when, and what for. Also, if students have
+different needs for different assignments, then this is easily
+accomodated into the token allocation scheme.
+
+The main disadvantage of this approach is that it is difficult to
+accurately determine how much time to allocate to each assignment.
+Meaningful feedback on how much time was actually used on each
+assignment is difficult to get (and only useful after the fact), and
+so the time allocated per assignment tends to be based on educated
+guesses.
+Other disadvantages are:
+@itemize @bullet
+@item
+It is far more administratively time consuming to create, allocate,
+and make adjustments to the numbers and types of tokens that are
+needed by this approach.
+@item
+Students can carelessly waste all their tokens and then be out on a
+limb. It is harder to waste a small number of reusable tokens.
+@item
+The tokens allocated will not necessarily reflect the amount of
+workstation time available, and there can be quite severe congestion
+at peak assignment periods with whole weeks being booked solid.
+@item
+The fact that non-reusable tokens are nonetheless returned when the
+lab and time booked are underutilised, makes the meaning of a token
+less precise. Nevertheless, this refunding is a valuable means of
+encouraging people to use less popular labs and/or times.
+@end itemize
+
+Experience has shown that both these schemes for token allocation can
+be made to work, though allocating a few reusable tokens that are
+valid for the full session is the easiest to administer. There is no
+reason that the two schemes cannot be combined if, for instance, one
+particular assignment has special needs. In this case the normal
+general purpose reusable tokens can be suplimented with a few special
+purpose tokens of limited duration, possibly non-reusable.
+
+@node Firm Allocations for class bookings, Advance and Late bookings, Reusable versus non-reusable, The full scoop on tokens and attributes
+@section Firm Allocations for class bookings
+
+Experience with the booking system has shown a need for two different
+styles of class bookings.
+
+One, which we call a @dfn{lab booking} is a time when students can
+work on assignments, when there is a tutor available to provide
+assitance. This is particularly used for first year students. In this
+situation there is no requirement to attend. For @dfn{lab bookings},
+a booking much like a normal student booking is made. If noone claims
+such a booking in the first 7 minutes, then the workstation becomes
+available to anyone who wants it.
+
+The other style of class booking is referred to as a @dfn{tut booking}
+as the time is run more like a tutorial. In this situation there is a
+tutor in attendance who will work with the class as a whole leading
+them through examples which each student can work on at their own
+workstation. This situation is quite different from @dfn{lab
+bookings} as the whole room should be reserved for the class, and
+people not in the class should not be allowed in, even if there are
+free workstations, as this could disrupt the lesson.
+
+To accomodate @dfn{tut bookings} an extra attribute can be included in
+the token used to make the booking. This attribute is the
+@code{firmalloc} attribute. It indicates that the allocation should be
+maintained for the entire extent of the period booked, rather than
+just the first 7 minutes.
+
+@node Advance and Late bookings, Privileged Tokens, Firm Allocations for class bookings, The full scoop on tokens and attributes
+@section Advance and Late bookings
+
+The distinction between advance and late bookings was designed to meet
+a potential need that has not yet arisen in practice, so the
+distinction has not yet been used.
+
+Lets say that a small number of workstations existed that had special
+or more desirable attributes. For instance, when the booking system
+was being designed, colour workstations were much less common, and
+consequently more desirable. Although this is no longer true, there
+may still be some extra functionality or attribute of workstations
+(perhaps sound, or availablility of DVD drives) which might still
+create a subclass of special purpose workstations.
+
+In any case, assuming that such workstations exist, and that there is
+a small group of users who have a particular need to use this subclass
+of workstations, then there are two obvious approaches that can be
+made to cater to these booking needs:
+@enumerate
+@item
+Only the users who need the workstations should be able to book. This
+would mean the people with need would always have the access they
+need. It would also mean that people without a demonstated need would
+never be able to book one of these @strong{better} workstations, even
+if they were under booked, which does not seem fair.
+@item
+All users could be allowed to book the special workstations.
+This would mean that the presumably large number of users without a
+specific need, but with a desire to use these workstations, could swamp
+the @strong{better} workstations, thus excluding the users with a real
+need.
+@end enumerate
+
+Neither of these solutions seems adequate. What is needed is a
+situation where users with a specific need can book whenever they want
+to, while users without a specific need should be able to book, but
+only if the needy users haven't.
+
+To achieve this we make a distinction between advance and late
+bookings. Advance bookings are those that are made at least 4 days
+before the time of the bookings. Late bookings are those that are made
+during the last 4 days before the time of the bookings.
+
+If users without a need are only allowed to book the special
+workstations when making a late bookings, while users with need can
+make such bookings at any time, then the desired soloution can be
+realised.
+
+It is to enable this, that tokens have two sets of attributes
+associated with them. One is used to determine booking privileges when
+making an early booking. The other is used when making a late booking.
+Normally the first set will be a subset of the second, but this is not
+enforced.
+
+Quite possibly, 4 days is too long a period for this to work well,
+and a number more like two days should be used. Hopefully this number
+will be made configurable soon.
+
+@node Privileged Tokens, Putting it together, Advance and Late bookings, The full scoop on tokens and attributes
+@section Privileged Tokens
+
+An extra complication in understanding tokens is that some tokens can be
+@dfn{Privileged}.
+This privilege is not actually associated with the token, but with the
+allocation of the token to a particular user.
+
+With normal (unprivileged) tokens, the last 10% of a lab can only be
+booked as a late booking. This was done to decrease the discontent if
+some workstations get put out of service. With a privileged token,
+the last 10% of a lab can also be booked as an advance booking.
+
+Privileged tokens (or more accurately, privileged allocation of tokens)
+result from a booking not being allocated due to a lack of working
+workstations. It is not possible to create (allocate) privileged
+tokens any other way.
+
+The rational is that if a users booking cannot be allocated due to a
+lack of working workstations, that user should get some
+recompense. That recompense is the ability to make a replacement
+booking in the near future, where @dfn{near} is determined by the
+definition of @code{late} bookings.
+
+The privilege attached to tokens is not very visible. There is no way
+to see if a user has any privileged tokens, or to change the privilege
+level. The only effect they have is to effect what bookings can be made
+when.
+
+@node Putting it together, , Privileged Tokens, The full scoop on tokens and attributes
+@section Putting it together
+
+As mentioned in @ref{Attributes and subspaces}, it is best to choose
+attributes in groups such that attributes in each group are
+nonintersecting and spanning. Given this, creating a token is simply a
+matter of choosing which attributes from each group are
+required. Some further tips are:
+@itemize @bullet
+@item
+Include at least one attribute from each group.
+@item
+Always include the @code{open} attribute and the @code{available}
+attribute.
+@item
+Remember to include the @code{reusable} attribute if reusable tokens are
+required.
+@item
+Normally there will be a lab attribute for each lab that the token is
+usable in.
+@end itemize
+
+Tokens for use in class booking will be created somewhat differently.
+@itemize @bullet
+@item
+They should only allow booking in one lab. This means that book will not
+prompt for a lab, so bookings can be made by a shell script.
+@item
+They will usually have no other restrictions
+@item
+They do not need to be reusable
+@item
+They may have @code{firmalloc} set of a @code{tut booking} is required.
+@end itemize
+
+@node Setting it up, UNSW Local Lore, The full scoop on tokens and attributes, TOP
+@chapter Setting it up
+
+There are a number of dependencies between different parts of the
+booking system such that certain parts cannot work until other parts are
+working. This can make the process of getting it up and running appear a
+bit daunting.
+To alleviate this, a number of recipes are presented here which provide
+step by step instructions on how to get things going.
+
+The different steps are given in an order that would be a reasonable
+order for doing things. There is some flexibility and so where there are
+dependencies, they are given explicitly.
+
+Paths names of programs are given as they appear in the distribution
+which is almost certainly not where they will be installed.
+
+
+
+@menu
+* Installing files.::
+* Creating the database::
+* Creating a database replica --- OPTIONAL::
+* Configuration::
+* Starting a status server::
+* Adding hostgroups and hosts::
+* Creating attributes and implications::
+* Adding workstations::
+* Creating tokens::
+* Creating classes::
+* Allocating tokens to classes::
+* Installing book_login and book_logout::
+* Enabling the system::
+@end menu
+
+@node Installing files., Creating the database, Setting it up, Setting it up
+@section Installing files.
+Every host on which any part of the booking system will be run must have
+a directory @file{/var/book}.
+This will contain, at the very least a file called @file{database_loc}
+which will contain a list of know database replicas.
+The things which may be in this directory are:
+@table @file
+
+@item database_loc
+File containing list of known database replicas, one host name per line.
+This file is maintained and used by
+@file{book_status}/@file{book_manager} but must be initialised to
+contain at least one name.
+
+@item db_@var{*}
+Some @code{gdbm} files which contain a replica of the
+database. Naturally these will only appear on hosts which run a database
+server.
+
+@item help
+The help file for @code{book}. It is used to provide online help. It
+should be installed on every host on which @code{book} might be run.
+
+@item periods
+The periods file for @code{book}. This lists some definitions of
+different periods that people might use when specifying bookings. It
+must exist for @code{book} to run.
+
+@item motd
+The contents of this file, if it is present, is displayed whenever
+@code{book} is run.
+
+@item whoison
+This directory will contain one file for each workstation that is
+currently logged on to the host. The files contains the uid, in ASCII,
+of the user who is logged on. It should exist on all hosts which support
+workstations.
+
+@item logins
+This file lists all logins and logouts that have happened on the host.
+There is one line per login or logout, with a date, a host name, a
+workstation nane, and a user name. The line start with a plus for logins
+and a minus for logouts.
+
+@item xdm-pid
+This directory contains one file for each workstation logged on to the
+host. The file contains an ASCII process id of a process to kill in
+order to force a logout on that workstation. The process id is usually
+that of the controlling @code{xdm}.
+
+@item book_errors
+A log of ad hoc messages from booking system daemons. It is fairly
+uninteresting without the source code.
+
+@item book.dump
+When ever an allocation is performed, a copy of the resulting status
+table is appended to this file. It should be rotated and discarded at
+least daily.
+
+@item evict_log
+A file containing a log of eviction messages and actions.
+
+@end table
+
+In order to use @code{messaged} a new service needs to be added to
+@file{/etc/services} and @file{/etc/inetd.conf}.
+The service should be called @code{message/tcp}. If @file{inetd} is used to run
+messaged, it must be run as a @code{stream wait} services.
+Many versions of @file{inetd} do not work properly for which type of
+service and so @file{messaged} will need to be run with the @code{-L}
+flag so that it binds and listens itself.
+
+Optionally, two new programs can be recorded in @file{/etc/rpc} they are
+@example
+ book_database 540033106
+ book_status 540033105
+@end example
+There are unofficial, unregistered program numbers.
+
+The various programs should be installed where
+needed. @file{book_status} and @file{book_manager} must be on every
+host. Other programs probably will be too.
+
+The only program which need to be setuid to root are @code{book} and
+@code{saveauth}.
+
+
+@itemize @bullet
+@item @file{book_status} should be run at boot time on all hosts
+@item @file{book_database} should be run at boot time on all replica hosts.
+@item @file{bookterm} should be run on all allocation display terminals.
+@item @file{bogin} should be run (by getty) on booking terminals.n
+@end itemize
+
+A final step, which should NOT be done until all else is ready, is
+modifying the xdm @file{startup}, @file{session} and @file{reset}
+scripts to call @file{book_login}, @file{save_auth} and
+@file{book_logout} respectively.
+
+The installation is essentially a pre-requisite for all other steps.
+
+@node Creating the database, Creating a database replica --- OPTIONAL, Installing files., Setting it up
+@section Creating the database
+
+The database is created by running @file{book_database} with the
+@code{-I} (initialise) flag. e.g.
+@example
+ /usr/local/etc/book_database -I -M /usr/local/etc/book_maint &
+@end example
+This will create a database with only one piece of information: that fact
+that the host it is on is has a replica of the database. It will also
+start the database server running.
+
+This database server can then be queried with
+@example
+ /usr/local/etc/dbadmin -r localhost -sA
+@end example
+which ask the replica on @file{localhost} for a status listing off all
+replicas.
+The one replica should be listed with a change count of zero. Its state
+will at first be @code{EXT} but will shortly change to @code{UP}.
+
+@node Creating a database replica --- OPTIONAL, Configuration, Creating the database, Setting it up
+@section Creating a database replica --- OPTIONAL
+
+This can only be done after the database has been created.
+
+The first step is to copy the current database onto a new machine. This
+is done with @file{book_copydb} e.g.
+@example
+ database/book_copydb name-of-source-replica
+@end example
+The start a database server.
+@example
+ database/book_database -M database/book_maint &
+@end example
+Due to shell interpretations, the following is needed
+@example
+ database/book_database -M /usr/local/etc/book_maint &
+@end example
+Check that this looks OK:
+@example
+ tools/dbadmin -r localhost -s localhost
+ tools/dbadmin -r localhost -sA
+@end example
+The first command with show that status of the new replica, the second
+will show the status of all registered replicas. They should be much the
+same, though the new replica will be in state @code{EXT}.
+
+Finally, register the replica
+@example
+ tools/dbadmin -r name-of-source-replica -a `hostname`
+@end example
+After a minute or so the new replica should discover that it is
+registered and
+@example
+ tools/dbadmin -r localhost -sA
+@end example
+should list all replicas, including the new one.
+
+@node Configuration, Starting a status server, Creating a database replica --- OPTIONAL, Setting it up
+@section Configuration
+
+Configuration of TABS involves describing the various parts of the
+system.
+These include:
+@table @samp
+@item Attributes
+The various attributes which be used to distinguish certain times and
+workstations need to be defined. This will include at least one
+attribute for each lab and the two attributes @emph{open} and @emph{closed}.
+It may also include other concepts such as @emph{weekend} @emph{evening}
+@emph{publicholiday} @emph{outofsession} etc.
+These are defined using the @code{attr} program.
+
+@item Implications
+These indicate how to determine more general attributes from specific
+attributes, and from particular times, days, or dates.
+These are also set using the @code{attr} program.
+
+@item hostgroup, hosts, labs, and workstation.
+These are the basic hardware that TABS need to know about. There is one
+program which is linked to the names @emph{hg}, @emph{host}, @emph{lb}, @emph{ws} for
+creating, examining, and modifying these different objects.
+
+@item tokens
+Each token identifies a set of workstation times which can be
+booked. Tokens need to be created for each set of workstation times that
+some group of users should be able to book.
+The @emph{token} command is used for this.
+
+@item users
+There is no need to explicitly tell the booking system about specific
+users as usernames and user ids are discovered through the normal
+password file access mechanisms.
+It is, however, necessary to inform the booking system of any classes
+(netgroups) which it will need to know about. The names of these classes
+should be chosen so as to be different from any user name.
+The command @code{user} is used to introduce these classes to the
+booking system.
+
+@item allotments
+Allotments record how many of which token has been alloted to each class
+or user. The term @emph{allocation} is used in various parts of this
+document for the handing out of tokens as it a more commonly used
+word. However we use @emph{allocation} to talk about allocating
+workstations to bookings, and so @emph{allotment} was chosen to describe
+allocating tokens to classes.
+
+Normally, individual users are not alloted person tokens, though this is
+certainly possible.
+Classes are the normal unit for allotting tokens to, and this is done
+with the @file{user} command, which can register classes with the
+booking system, can query the current allotment for classes, and can
+change the allotment.
+
+@item classes/netgroups
+
+As described elsewhere, classes memberships are recorded using
+@file{netgroups} and are not explicitly recorded by the booking system.
+Thus setting up of class memberships, while necessary for proper running
+of the system, is not discussed here.
+
+@end table
+
+@node Starting a status server, Adding hostgroups and hosts, Configuration, Setting it up
+@section Starting a status server
+
+The status server, @file{book_status} together with @file{book_manager},
+needs to be run on every host on which booking system commands are to be
+run. This is because it is used to find a database replica.
+
+Before @file{book_status} is run, the name of at least one replica site
+should be written to the @file{/var/book/database_loc} file. Given this
+information, the @file{book_manager} can find the others.
+
+For example, on a replica server:
+@example
+ hostname > /var/book/database_loc
+ manager/book_status -M manager/book_manager &
+@end example
+
+The list of known replicas can be checked with the @file{smadmin}
+command:
+@example
+ smadmin -d localhost
+@end example
+
+This step is a prerequisite to any further database operations, as
+@file{dbadmin} is the only command that can be explicitly given replica
+to talk to --- all other database management commands find a database
+replica to talk to.
+
+@node Adding hostgroups and hosts, Creating attributes and implications, Starting a status server, Setting it up
+@section Adding hostgroups and hosts
+
+Host groups and hosts can be added any time that the database and
+status servers are up and running, though they are usually just entered
+once when the system is set up.
+
+A host group is a group of hosts that together manager a group of labs,
+as discussed else where.
+A host group is created with the @file{bkhg} command.
+
+@example
+ tools/bkhg -c spectrum
+@end example
+
+Hosts can similarly be created and should be placed in a hostgroup.
+
+@example
+ tools/bkhost -c -g spectrum red blue green
+@end example
+
+Registers three hosts called @code{red}, @code{blue}, and @code{green} in
+a group called @code{spectrum}.
+
+Once this has been done, status/manager servers can should be started on
+each of the hosts, and they will start passing status information
+around and thereby monitoring the status of the host group.
+
+If the servers are already running, they can be asked to re-assess there
+membership in a hostgroup by requesting one of the status servers to
+restart its manager. The manager will create an appropriate status table
+which will be passed around among all hosts in the hostgroup.
+The status server can be told to restart its manager with the
+@file{smadmin} command:
+@example
+ tools/smadmin -r blue
+@end example
+
+The status table that is being passed around can be examined using the
+@file{smadmin} command. At this state it will only have @code{TABLE} and
+@code{HOST} records.
+@example
+ tools/snadmin -t blue
+
+ 00: TABLE spectrum 27/03;14:53:58 (1): on blue
+ 01: HOST red 29/03;13:42:27 (1): UP
+ 02: HOST green 29/03;13:42:27 (1): UP
+ 03: HOST blue 29/03;13:42:27 (1): UP
+
+@end example
+
+@node Creating attributes and implications, Adding workstations, Adding hostgroups and hosts, Setting it up
+@section Creating attributes and implications
+
+Creation of attributes and implications can be done as soon as at least
+one database replica is active, and a status manager is running (to
+help locate the replica).
+
+The sections on attributes and implications in the configuration chapter
+should be read and understood before proceeding.
+
+The minimum that should be created at this stage are the @code{open},
+@code{closed}, and @code{available} attributes, an attribute for each
+lab, and implications to determine when the labs are open.
+For following is an example input file for the @code{attr} command which
+provides this minimum.
+
+@example
+ 1: open open
+ 2: closed closed
+ 3: available available
+ 10: yellow lab
+ 11: magenta lab
+ 12: cyan lab
+
+ 100: normalopen optional
+ 101: normalclosed optional
+
+ sa 9:30-16:30 -> normalopen
+ sa 16:30-17:30 -> normalclosed
+ su 9:30-16:30 -> normalopen
+ su 9:30-16:30 -> normalclosed
+ mo-fr 8:30-19:30 -> normalopen
+ mo-fr 19:30-20:30 -> normalclosed
+
+ yellow normalopen -> open
+ yellow normalclosed -> closed
+ magenta normalopen -> open
+ magenta normalclosed -> closed
+ cyan mo-fr normalopen -> open
+ cyan mo-fr normalclosed -> closed
+@end example
+
+In this example, the @code{cyan} lab is not open on weekends.
+Also, the labs are only @code{closed} for an hour after closing
+time. This is because physical security is sufficient to keep people off
+at other times, and it does not hinder @emph{special} people who might
+have keys.
+
+The labs envisioned in this example are meant to be unlocked at 8am on
+week days and 9am on weekends. During the first half the lab is neither
+open (so no-one will have booked and then complain because the lab was
+opened late) or closed (so people who arrive can actually log on).
+
+Once the file can been created, it can be entered into the database with
+the @code{bkattr} command
+@example
+ tools/bkattr attr-file
+@end example
+
+The current attributes and implications can be extracted from the
+database by running the attr command with no arguments.
+
+
+@node Adding workstations, Creating tokens, Creating attributes and implications, Setting it up
+@section Adding workstations
+
+Once the @code{hostgroups}, @code{hosts}, and @code{attributes} (and
+thereby labs) have been defined, the workstations can be defined.
+These must at least be given a name and a lab. If they are tied to a
+particular host, they should be given a host as well.
+
+Each workstation's name should be a valid displayname for the X server
+running on the workstation.
+
+The following example registers two hosts in each of the previously
+created labs. For larger collections of workstations it can be useful to
+use a small shell script.
+
+@example
+ tools/bkws -c -l yellow -h red yellow00:0
+ tools/bkws -c -l yellow -h green yellow01:0
+ tools/bkws -c -l cyan -h blue cyan00:0
+ tools/bkws -c -l cyan -h green cyan01:0
+ tools/bkws -c -l magenta -h red magenta00:0
+ tools/bkws -c -l magenta -h blue magenta01:0
+@end example
+
+Once the workstations have been recorded, the status manager should be
+told to create a new table which will now contain this extra
+information:
+@example
+ tools/smadmin -r blue
+@end example
+
+@node Creating tokens, Creating classes, Adding workstations, Setting it up
+@section Creating tokens
+
+Class tokens should have only one lab
+
+@node Creating classes, Allocating tokens to classes, Creating tokens, Setting it up
+@section Creating classes
+
+NOTES: include teachers in class for class bookings.
+Possibly have tut classes within subject, possibly not
+
+@node Allocating tokens to classes, Installing book_login and book_logout, Creating classes, Setting it up
+@section Allocating tokens to classes
+
+@node Installing book_login and book_logout, Enabling the system, Allocating tokens to classes, Setting it up
+@section Installing book_login and book_logout
+
+@node Enabling the system, , Installing book_login and book_logout, Setting it up
+@section Enabling the system
+
+@example
+ tools/conf book_level on
+@end example
+
+This chapter should describe various scripts that are used to
+maintain the booking system...
+
+@node UNSW Local lore, Local setup, Setting it up, TOP
+@chapter UNSW Local lore
+This chapter describes the various formal and informal procedures
+developed at the School of Computer Science and Engineering (CSE) at
+the University of New South Wales to administer the booking system.
+This chapter is also includes some examples of common problems and
+their corresponding solutions.
+
+@menu
+* Local setup::
+* Keeping it going::
+* Skyterms and Booking terminals::
+* Common problems
+@end menu
+
+@node Local setup, File locations, Setting it up, UNSW Local lore
+@section Local setup
+The previous sections of the booking manual describe how to use the
+booking system in a general sense. What will be described here are
+some of the little quirks of the current (Dec 2000) setup and
+procedures used at the School of CSE.
+
+One thing to note is that most of the current
+workstations in student labs are also hosts (for themselves). Thus
+the host for the fife01 workstation is fife01. This is different from
+the days (pre-1998) when some labs (notably the Elec Eng Undercroft
+labs) were full of X-terminals controlled by only three hosts (bribe,
+bonus and boodle). Thus the distinction between @emph{Labs} and
+@emph{Hostgroups} may not seem particularly useful with our current
+configuration of machines in labs.
+
+Many of the booking services can be accessed and controlled using
+@code{metac}, so this is a useful command to become familiar with. In
+fact in some cases, @code{metac} becomes the failsafe command when all
+others have failed.
+
+@node File locations, Initialisation Procedure, Local Setup, UNSW Local lore
+@subsection File locations
+The main booking system files are kept under the SS directory:
+@example
+ /home/ss/book/@emph{current_session}
+@end example
+The term @emph{current_session} is substituted for the corresponding
+session, eg 97s2. Each session directory will usually have the
+following files:
+
+@itemize @bullet
+@item
+@file{bookings} - lists all the class bookings. Keep this file
+updated as it is the easiest way to find out what labs have class
+bookings.
+@item
+@file{attr} - sets up the attributes for the labs, and the booking
+periods defined for days of the week, the session, and the current
+year, etc.
+@item
+@file{tokens} - describes the token attributes.
+@item
+@file{allotments} - describes the token allotments that each subject
+has.
+@item
+@file{config} - record of commands run through the @code{bkconf}
+command.
+@end itemize
+
+@node Initialisation Procedure, Keeping it going, File locations, UNSW Local lore
+@subsection Initialisation Procedure
+Until fairly recently, there were no systems in place to clean out old
+bookings, nor was there any way of removing obsolete objects from the
+booking database. As the booking system only knows about the current
+year (booking periods are only identified relative to the start to the
+current year), it was necessary for the database to be cleaned out and
+reset sometime at the start of each year when there were no active
+bookings being made or allocated. Without this periodic reset, the
+previous year's bookings (and settings) would carry over into the
+current year.
+
+Unfortunately there is precious little time available at the beginning
+of the year when the system is not active, especially with the advent
+of summer session, so systems have now been put into place which mean
+that these yearly system resets are no longer necessary.
+
+Nevertheless, it is still useful to know how to reset the bookings
+system:
+
+Many of the following steps involve using scripts in the
+@file{/home/ss/book/bin/} directory, or files in the
+@file{/home/ss/book/@emph{current_session}} directory. These scripts
+and files make it much easier to make changes than doing so by
+hand. In addition if there are changes to be made during session, you
+simply update the file(s), and make the changes to the booking system
+via the appropriate script(s).
+
+@enumerate
+@item
+ Disable book and book_db on all database replicas:
+ @enumerate a
+ @item use dbadmin -sA to get the list of replicas.
+ @item metac -D book -K book replica
+ @item metac -D book_db -K book_db replica
+ @end enumerate
+@item
+Remove all the old database stuff on all old replicas:
+@example
+ rm /var/book/db_*
+@end example
+@item
+On one of the database servers, create the master book database server:
+ @enumerate a
+ @item
+ Reinitialise the database:
+ @example
+ /usr/local/etc/book_database -I -M /usr/local/etc/book_maint &
+ @end example
+ @item
+ kill the hand started book_database:
+ @example
+ dbadmin -x localhost
+ @end example
+ @item
+ Reenable and restart book and book_db:
+ @example
+ metac -E book localhost
+ metac -E book_db localhost
+ @end example
+ @end enumerate
+@item
+Create new database replicas, one on each replica machine:
+ @enumerate a
+ @item
+ copy the database over:
+ @example
+ /usr/local/etc/book_copydb source_machine
+ @end example
+ @item
+ start the database up:
+ @example
+ metac -E book_db localhost
+ @end example
+ @item
+ register the replica with the master (and others):
+ @example
+ dbadmin -r master_machine -a `hostname`
+ @end example
+ @item
+ check the replica has been registered (after waiting a while):
+ @example
+ dbadmin -r localhost -sA
+ @end example
+ @end enumerate
+@item
+Initialise the booking database:
+ @enumerate a
+ @item
+ Create a directory for the current session's config files:
+ @example
+ cd /home/ss/book/
+ mkdir yyyyss
+ @end example
+ @item
+ Copy the config files from the previous session to the current,
+ and update the current session:
+ @example
+ cd current
+ cp attr tokens bookings allotments allot_list config ../yyyyss
+ cd ..
+ rm current
+ ln -s yyyyss current
+ @end example
+ @item
+ Edit the config files and @file{/home/ss/book/lab.conf} as necessary.
+ @end enumerate
+@item
+Set up (or update) the booking system and database from the various files
+that are usually kept in @file{/home/ss/book/current/}:
+
+ @enumerate a
+ @item
+ Define the booking attributes:
+ @example
+ bkattr attributes
+ @end example
+ @item
+ Define the labs etc. (uses @file{/home/ss/book/lab.conf}):
+ @example
+ mk_hosts
+ @end example
+ @item
+ Create or redefine the tokens:
+ @example
+ mktokens < tokens
+ @end example
+ @item
+ Allocate tokens to classes:
+ @example
+ /home/ss/book/bin/allot < allotments
+ @end example
+ @item
+ Make any class bookings:
+ @example
+ ./bookings
+ @end example
+ @end enumerate
+@end enumerate
+
+@node Keeping it going, Administration of Course Class bookings, Initialisation Procedure, UNSW Local lore
+@section Keeping it going
+
+@subsection Flushing the database
+Every week the script:
+@example
+ /home/ss/book/bin/flushdb
+@end example
+is run to flush out old bookings that are more than one month old.
+The script, which uses the @code{booking} command,
+also needs to change any old PENDING bookings into CANCELLED bookings
+first, or they will not be removed.
+
+Logs are kept of the bookings that have been deleted in the files:
+@file{/home/ss/book/log/flush.start-end.gz}.
+
+This script is run on one of the replicated booking database servers
+(2004: maestro), and called by one of the nightly maintenance scripts
+in @file{/usr/local/maint/nightly/}.
+
+@node Administration of Course Class bookings, Skyterms and Booking terminals, Keeping it going, UNSW Local lore
+@subsection Administration of Course Class bookings
+Most CSE courses require labs of workstations to be booked for their
+students for tutorial and laboratory work. To enable this, tokens are
+allocated to every course class which are used to make lab bookings
+which can only be taken up by students enrolled in that
+class. Although each course class (or their administrator) could make
+their own regular suite of session bookings for their students, it is
+far better that these many and various course class bookings be
+coordinated through a central point to avoid conflicts, and to balance
+the loads and demands on limited laboratory resources.
+
+Currently (since 2000) all course administrators register their
+booking requirements as early as possible with a course coordinator
+whose job it is to determine the relative merits of potentially
+competing requests for limited (lab) resources. The coordinator is
+usually an academic who is empowered to refuse or change bookings that
+are either unreasonable, impractical, or submitted with too little
+warning. This academic then passes the final booking requests onto the
+@emph{Computing Services Group} (usually via @emph{ss}), and a system
+administrator makes the required bookings on behalf of the course
+classes. This chain of command has helped avoid the problems that the
+System Administrators once had dealing with poorly planned lab
+allocations from overworked subject administrators.
+
+Currently (since 2002), the course coordinator updates the file:
+
+ @file{/home/give/public_html/Timetables/labs/allYYSS}
+
+and after being notified of a change to this file, the system
+administrator (who needs root access to be able to make the bookings
+as the course classes), runs the script:
+
+ @file{/home/ss/book/bin/mkbookings}
+
+This script compares the existing bookings in the booking database,
+against the planned bookings, and
+@enumerate
+@item makes any planned bookings that don't exist yet;
+@item undoes any existing bookings that are no longer planned;
+@item logs all bookings and unbookings in the files:
+@file{/home/ss/book/current/[un]book.date}.
+@end enumerate
+
+There are some occasions when bookings are made by hand (using the
+@code{book} command) for course classes. This especially happens when
+the course class needs to make a once-off booking for a (prac) exam
+set at the terminals. In these cases it is important that
+@code{mkbookings} does not undo any of the once-off bookings.
+The command:
+@example
+ mkbookings -d
+@end example
+will create the files @file{/home/ss/book/current/book.raw} and
+@file{/home/ss/book/current/unbook.raw} which are the differences
+between the existing and planned bookings. These files can be
+inspected and/or edited, and then merged with the list of other
+bookings to be ignored with the command:
+@example
+ mkbookings -i
+@end example
+The command:
+@example
+ mkbookings -h
+@end example
+gives more details.
+
+
+@node Skyterms and Booking terminals, Setup, Local setup, UNSW Local lore
+@section Skyterms and Booking terminals
+One of the important features of the booking system is the operations of the booking terms and skyterms. For those who don't know (you should, since you're playing with the booking system) the booking terms allow people to log in for a short time, and make a booking, etc. The skyterms display the bookings that have been made, and are updated every booking period (ie every half hour). One final note is that the program that runs the skyterms is called @code{bookterm} and the program that runs the book terms is call @code{bogin}.
+
+@node Setup
+@subsection Setup
+The usual setup for either type of terminal display is for a dumb
+terminal to be connected to a machine via a serial cable. That
+machine is then set up to run either the book or sky term.
+Alternatively the terminal can be connected directly to the serial
+connection system (as the terminals in the third floor foyer are).
+This is connected to the patch pannel in 343d. Then the booking and
+skyterms are connected to the annex system (funnel0). The following
+steps are needed to get either type of terminal working from a lab
+machine serial port connection (ie the terminal is connected by serial
+cable to some machine, such as @code{fife00}).
+@itemize @bullet
+@item
+Connect the dumb terminal to the machine. At current the machine serial port is a 9 pin male, and the terminals (VT510-emulating a vt100) use a 25 pine male or female plug.
+@item
+Look at the file @file{/home/conform/products/unsw/book.v.2.4/config}. Change the file so it can handle the new book and/or sky terms.
+@item
+@code{rlogin} to the machine in question and run
+@code{conform -i -H /home/conform}
+
+NOTE : make sure you know what you are doing with @file{conform} before you do anything.
+@item
+Send the signal @code{kill -1 1} to the machine to start the process.
+@item
+If there are problems, make sure that the wiring of the serial cable is correct (a common problem).
+@end itemize
+
+To set up a terminal to run off the serial network (like the ones in the third floor foyer), try the following.
+@itemize @bullet
+@item
+Set up the terminal and make sure that the cable is wired correctly
+@item
+Look at @file{/home/conform/products/unsw/metad.v.2/filtered} and search for the phrase @code{bookterm}. Modify the relevant parts to include the new skyterm. Find somewhere in the annex (funnel0) to patch the skyterm to. Be careful with the wiring.
+@item
+For the booking terms, these can also be connected to the annex. First the port that the terminal connects to on the funnel must be set up to be a dedicated port to that terminal. Port 32 is an example. (This is using the annex system, ie @code{rlogin} to haydn, run @code{na}, etc)
+@item
+Next, a server has to have @code{bogin} running on it. At the moment composer runs the booking terminal in the third floor foyer. In the @file{/etc/services} file, there is a list of the services. Here you will find the link to funnel0, port32 from the above example.
+@item
+Update the @file{/home/conform/products/unsw/book.v.2.4/config} file to the new reality.
+@item
+Run conform, just like before.
+@item
+Be annoyed when you realise that the serial network wiring is shot, and doesn't work. Break out the multimeter.
+@end itemize
+
+@node Common problems
+@section Common problems
+This section not only details some common problems but also some situations that can occur and that the documentation doesn't cover elsewhere.
+@menu
+* Composite classes::
+* Lab command not updating, or showing wrong information::
+* User in certain class, but cannot log on during class booking::
+* Booking/Skyterm dies::
+* How can I tell if someone did log on when they said::
+@end menu
+
+@node Composite classes
+@subsection Composite classes
+A common occurance is for members of two classes to be able to log into the same lab. This usually is done for third year subjects and their equivalent post-grad subject. Such a class description is given as
+@example
+ COMP35119511
+@end example
+Ie with the two class numbers concatenated together. The steps to do this are as follows:
+@itemize @bullet
+@item
+Create a new class of the desired name:
+@example
+ acc -C .comp35119511
+@end example
+@item
+Set up the UserGroups class, with no expiry date.
+@example
+ acc classes+ UserGroups[forever] .comp35119511
+@end example
+@item
+For each class that is a component of the new dual class, do
+@example
+ acc classes+ comp35119511[forever] .comp3511
+and acc classes+ comp35119511[forever] .comp9511
+@end example
+Ie each class is a member (child) of the dual class
+@item
+Set the netgroup priority to 8.
+@example
+ acc netgroup=8 .comp3511
+@end example
+@item
+Add the class by using bkuser
+@example
+ bkuser -C comp35119511
+@end example
+@item
+Change the allotments file and run it through the system
+@example
+ /home/ss/book/bin/allot < allotments
+@end example
+@end itemize
+
+@node Lab command not updating, or showing wrong information
+@subsection Lab command not updating, or showing wrong information
+Occasionaly the information displayed by the @code{lab} command is incorrect. This is usually due to the status table not updating. The @code{smadmin} command is useful in this case, in order to force an update. If all else fails, try @code{metac -K book} on the machine in question. This will pretty much make sure the status table is updated.
+
+@node User in certain class, but cannot log on during class booking
+@subsection User in certain class, but can't log on during class booking
+The first thing to do is determine if this occurs for everyone who is a member of the class in question. If so, then it is likely that the lab booking was made for the wrong class. The usual cause of this problem is due to the Netgroup priority not being set correctly. This isn't the place to describe the details, but make sure the Netgroup priority of the subject is not 1, and in most cases should be 8.
+
+@node Booking/Skyterm dies
+@subsection Booking/Skyterm dies
+These little things can go down for a variety of reasons, but most are to do with either serial cable failure, or the status table not updating on the machine that the terminal is connected to. The following is a check list of things to look at:
+@itemize @bullet
+@item
+Check the serial cable. Make sure that it is connected at both end, and the plugs haven't been jerked thus snapping the wires. In addition, make sure the cable is plugged into the correct ports on both the terminal and the machine. If the terminal is plugged into the serial network, make sure no-one has done any re-wiring.
+@item
+Skyterms are rather easy, as they only recieve information. If a Skyterm is blank, check that the status table on that machine is being updated correctly. If it is not, then the Skyterm will die. See @ref{Lab command not updating, or showing wrong information,} for information about status tables.
+The Booking terms are a little more tricky, as they both send and recieve data. If a booking term isn't working, make sure that @file{bogin} is running on the machine that the terminal is connected to. After that, it much depends on the situation. If the terminal was working, then something on the system end may have changed. If you are trying just to get a machine working, getting the connections correct in the serial cable is a bit of a hassle. The best thing to do is to check an already existing cable, and go from there.
+@item
+Most problems are from the system end, not the hardware end. Those little dumb terminals are pretty bullet proof. The workstation machines are not.
+@end itemize
+
+@node How can I tell if someone did log on when they said
+@subsection How can I tell if someone did log on when they said
+Check out the logon logs :) on (Sep 97)
+@example
+ /import/elephant/1/all-logins/[YYMMDD]
+@end example
+
+
+
+@node Interaction with other systems, Policy, UNSW Local Lore, TOP
+@appendix Interaction with other systems
+This chapter summarises the interactions that the booking system needs
+to have with other systems in order to be able to do its job. These
+systems are the login system (which normally means @file{xdm}), the
+user interface (which must be via @file{xdm}), the YP/NIS system, and
+the people who use TABS.
+
+@menu
+* Login interaction::
+* User Interface Interaction::
+* YP/NIS interaction::
+* Interaction with users::
+@end menu
+
+@node Login interaction, User Interface Interaction, Interaction with other systems, Interaction with other systems
+@section Login interaction
+
+For obvious reasons, the booking system needs to be aware of, and have
+some control over, user logins and logouts.
+It maintains this awareness and control through three contact points:
+@table @file
+@item book_login
+@file{book_login} is a program which should be run as part of the login
+process. It should be passed various arguments discussed elsewhere
+including the username and the workstation name.
+
+@file{book_login} checks whether or not the user is allowed to log in to
+this workstation. If not, an explanatory message is sent to
+@file{stdout} and @file{book_login} exits with a failure status. It is
+expected that this failure status will cause the login to be aborted.
+If the user is allowed to login, @file{book_login} informs the booking
+system, logs the login, and exits with a success status.
+
+This program can easily be incorporated into an @file{xdm}
+@file{startup} script.
+
+@item book_logout
+@file{book_logout} is a program which should be run when a user logs
+out.
+It informs the booking system that the user has logged out, logs the
+logout, and optionally kills all processes on the host owned by the
+user.
+
+@file{book_logout} can easily be incorporated into an @file{xdm}
+@file{reset} script.
+
+@item /var/X11/xdm/xdm-pids/@var{displayname}
+This is a file which should hold the process id number of the @file{xdm}
+process which is controlling the named display.
+When the booking system needs to force someone to logout, it does so by
+sending a @code{SIGTERM} signal to the process named in this file.
+
+If the @file{xdm} @file{startup} file is a @file{ksh} script, then this
+can be achieved by echoing @code{$PPID} into the appropriate file.
+@end table
+
+@node User Interface Interaction, YP/NIS interaction, Login interaction, Interaction with other systems
+@section User Interface Interaction
+The only interaction that the booking system needs with the user
+interface occurs when it needs to send a message to the user informing
+that they should consider logging off.
+With the X11 window system, the only complexity in this is determining
+the appropriate authentication information.
+Rather than trusting @file{.Xauthority} in the users @file{HOME}
+directory, the booking system takes a copy of the @code{Xauthority}
+information and stores it in a known, protected place. This place is
+@file{/var/X11/xdm/save_auth/@var{displayname}}.
+The authority info is stored by running @file{saveauth} in the
+@file{xdm} @file{session} script.
+@file{saveauth} is set-uid to @code{root} and is careful only to save
+authentication information that is actually valid.
+@file{saveauth} needed to run in @file{session} with the X11R4
+@file{xdm} because authentication information was not available in
+@file{startup}. Possibly with X11R5 and later releases, @file{saveauth}
+can be run in @file{startup} and need not be set-uid.
+
+The messages are displayed on the workstation screen via a program
+called @file{messaged}. This program accepts requests (from privileged
+sources) to displays messages accordingly, using
+@file{/var/X11/xdm/save_auth/@var{displayname}} to authenticate itself
+to the Xserver. It can manage multiple message windows on multiple
+workstations simultaneously.
+
+@node YP/NIS interaction, Interaction with users, User Interface Interaction, Interaction with other systems
+@section YP/NIS interaction
+
+Apart from username/uid lookup and hostname/ip-address lookup, which
+may or may not go through YP, the only interaction that the booking
+system has with YP is to determine class membership.
+
+Class membership is needed to validate access to class bookings and to
+determine token allocations.
+
+Class membership should be recorded in the @code{netgroup} table within
+YP. Netgroups provide for hierarchical memberships and this can be quite
+useful for class memberships. For example, there could be a netgroup for
+each first year subject, and a netgroup for first year which contains
+each subject. Then a base level of token allocation could be given to the
+first-year class, and extra allocation to each particular subject.
+
+The booking system does not use the @code{innetgr} library routine for
+accessing netgroups as many implementations are not very
+efficient. Rather, it does direct YP lookups of the
+@file{netgroup.byuser} or @file{netgroup_byuser} maps.
+
+@node Interaction with users, , YP/NIS interaction, Interaction with other systems
+@section Interaction with users
+
+Apart from the obvious user initiated interactions, such as making,
+querying, and cancelling bookings, the booking system needs to provide
+two special interaction which must not require logging in to a
+workstation.
+
+
+
+@menu
+* Notification of allocations::
+* Discovery of late arrivals::
+@end menu
+
+@node Notification of allocations, Discovery of late arrivals, Interaction with users, Interaction with users
+@subsection Notification of allocations
+The booking system needs to be able to inform booked users which
+workstation they have been allocated to. For this the booking system
+needs one or more dedicated displays, which will usually be character
+based terminals.
+The program @file{bookterm} should be run in these terminals. It is
+given a list of labs to report on and will continually display a list of
+users who have been allocated workstation, but have not yet logged on.
+
+@node Discovery of late arrivals, , Notification of allocations, Interaction with users
+@subsection Discovery of late arrivals
+
+If a user books multiple consecutive periods and does not turn up for
+the first period, the booking system assumes that they couldn't make it
+and does not free up a workstation for subsequent periods.
+If they do eventually arrive, the booking system needs to be told.
+For this purpose, dedicated terminals need to be provided for late
+arrivals to announce their presence. These terminals should run
+@file{bogin} which works in a similar fashion to @file{/bin/login} except
+that instead of running the user's shell, it runs the @file{book}
+program.
+
+
+@node Policy, , Interaction with other systems, TOP
+@appendix Policy
+Restrictions:
+@itemize @bullet
+@item
+Users can only book for the future, and not the current or next
+period.
+@item Non-classes can only book one workstation at a time
+@item Classes can book any number of workstations at a time
+@item
+Users cannot cancel a booking on the day of allocation, unless it
+was also made on the day of allocation. (This might change)
+@item
+The last 10% of a lab can only be booked in the last 4 days before
+the time of the booking. Exceptions are where classes and privileged
+tokens are concerned.
+@item
+If a booking cannot be honoured, the token is refunded in a
+privileged form and can book from the last 10% of the lab.
+@item
+Users can make bookings for other users - to support group
+work. This is not fully implemented yet.
+@end itemize
+
+@contents
+@bye
+
projects / TABS.git / commitdiff