% $Id: internals.tex,v 1.1.1.1 2018/04/24 16:12:57 root Exp $
%
% Copyright (c) 1989 Jan-Simon Pendry
% Copyright (c) 1989 Imperial College of Science, Technology & Medicine
% Copyright (c) 1989 The Regents of the University of California.
% All rights reserved.
%
% This code is derived from software contributed to Berkeley by
% Jan-Simon Pendry at Imperial College, London.
%
% Redistribution and use in source and binary forms are permitted provided
% that: (1) source distributions retain this entire copyright notice and
% comment, and (2) distributions including binaries display the following
% acknowledgement:  ``This product includes software developed by the
% University of California, Berkeley and its contributors'' in the
% documentation or other materials provided with the distribution and in
% all advertising materials mentioning features or use of this software.
% Neither the name of the University nor the names of its contributors may
% be used to endorse or promote products derived from this software without
% specific prior written permission.
% THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
% WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
%
%	@(#)internals.tex	5.1 (Berkeley) 7/19/90


\Chapter{Internals}

\Section{Log Messages}

In the following sections a brief explanation is given of some
of the log messages made by \amd.
Where the message is in {\tt typewriter} font, it corresponds
exactly to the message produced by \amd.  Words in {\em italic}
are replaced by an appropriate string.  Variables, \Var{{\em var}},
indicate that the value of the appropriate variable is output.

Log messages are either sent direct to a file,
or logged via the {\bf syslog}(3) mechanism.
Messages are logged with facility {\tt LOG\_DAEMON} when using {\bf syslog}(3).
In either case, entries in the file are of the form:
\begin{quote}
{\em date-string}\ \ {\em hostname} {\tt amd[}{\em pid}{\tt ]}\ \ {\em message}
\end{quote}

\Subsection{Fatal errors}
\Amd\ attempts to deal with unusual events.
Whenever it is not possible to deal with such an error, \Amd\ will
log an appropriate message and, if it cannot possibly continue, will
either exit or abort.
These messages are selected by {\tt -x~fatal} on the command line.
When {\bf syslog}(3) is being used, they are logged with
level {\tt LOG\_FATAL}.
Even if \amd\ continues to operate it is likely to remain in a precarious
state and should be restarted at the earliest opportunity.

\begin{description}
\item [\tt Attempting to inherit not-a-filesystem]\mbox{}\\
The prototype mount point created during a filesystem restart
did not contain a reference to the restarted filesystem.
This erorr ``should never happen''.

\item [\tt Can't bind to domain "{\em yp-domain}"]\mbox{}\\
A specific YP domain was requested on the command line, but no
server for that domain is available on the local net.

\item [\tt Can't determine IP address of this host ({\em hostname})]\mbox{}\\
When \amd\ starts it determines its own IP address.
If this lookup fails then \amd\ cannot continue.
The hostname it looks up is that obtained returned by
{\bf gethostname}(2) system call.

\item [\tt Can't find root file handle for {\em automount point}]\mbox{}\\
\Amd\ creates its own file handles for the automount points.
When it mounts itself as a server, it must pass these
file handles to the local kernel.
If the filehandle is not obtainable the mount point is ignored.
This error ``should never happen''.

\item [\tt Must be root to mount filesystems (euid = {\em euid})]\mbox{}\\
To prevent embarrassment, \amd\ makes sure it has appropriate
system privileges.  This amounts to having an euid of 0.
The check is made after argument processing complete to
give non-root users a chance to access the ``-v'' option.

\item [\tt No work to do - quitting]\mbox{}\\
No automount points were given on the command line and so
there is no work to do.

\item [\tt Out of memory in realloc]\mbox{}\\
While attempting to realloc some memory, the memory space
available to \amd\ was exhausted.  This is an unrecoverable
error.

\item [\tt Out of memory]\mbox{}\\
While attempting to malloc some memory, the memory space
available to \amd\ was exhausted.  This is an unrecoverable
error.

\item [\tt cannot create rpc/udp service]\mbox{}\\
Either the NFS or AMQ endpoint could not be created.

\item [\tt gethostname:\ {\em description}]\mbox{}\\
The {\bf gethostname}(2) system call failed during startup.

\item [\tt host name is not set]\mbox{}\\
The {\bf gethostname}(2) system call returned a zero length
host name.
This can happen if \amd\ is started in single user mode just
after booting the system.

\item [\tt ifs\_match called!]\mbox{}\\
An internal error occurred while restarting a pre-mounted
filesystem.
This error ``should never happen''.

\item [\tt mount\_afs:\ {\em description}]\mbox{}\\
An error occured while \amd\ was mounting itself.

\item [\tt run\_rpc failed]\mbox{}\\
Somehow the main NFS server loop failed.
This error ``should never happen''.

\item [\tt unable to free rpc arguments in amqprog\_1]\mbox{}\\
The incoming arguments to the AMQ server could not be
free'ed.

\item [\tt unable to free rpc arguments in nfs\_program\_1]\mbox{}\\
The incoming arguments to the NFS server could not be
free'ed.

\item [\tt unable to register (AMQ\_PROGRAM, AMQ\_VERSION, udp)]\mbox{}\\
The AMQ server could not be registered with the local portmapper
or the internal RPC dispatcher.

\item [\tt unable to register (NFS\_PROGRAM, NFS\_VERSION, 0)]\mbox{}\\
The NFS server could not be registered with the internal RPC dispatcher.

\end{description}

\Subsection{Info messages}
\Amd\ generates information messages to record state changes.
These messages are selected by {\tt -x~info} on the command line.
When {\bf syslog}(3) is being used, they are logged with
level {\tt LOG\_INFO}.
The messages listed below can be generated
and are in a format suitable for simple statistical analysis.
``{\em mount-info}'' is the string that is displayed by \amq\ in its mount
information column and placed in the system mount table.
\begin{description}
\item[\tt mount of "\Var{path}" on \Var{fs} timed out]\mbox{}\\
Attempts to mount a filesystem for the given automount point have failed
to complete within 30 seconds.

\item[\tt "\Var{path}" forcibly timed out]\mbox{}\\
An automount point has been timed out by the \amq\ command.

\item[\tt restarting {\em mount-info} on \Var{fs}]\mbox{}\\
A pre-mounted file system has been noted.

\item[\tt "\Var{path}" has timed out]\mbox{}\\
No access to the automount point has been made within the timeout period.

\item[\tt file server \Var{rhost} is down - timeout of "\Var{path}" ignored]\mbox{}\\
An automount point has timed out, but the corresponding file server is known to be down.
This message is only produced once for each mount point for which the server is down.

\item[\tt Re-synchronizing cache for map \Var{map}]\mbox{}\\
The named map has been modified and the internal cache is being re-synchronized.

\item[\tt Filehandle denied for "\Var{rhost}:\Var{rfs}"]\mbox{}\\
The mount daemon refused to return a file handle for the requested filesystem.

\item[\tt Filehandle error for "\Var{rhost}:\Var{rfs}":\ {\em description}]\mbox{}\\
The mount daemon gave some other error for the requested filesystem.

\item[\tt file server \Var{rhost} type nfs starts up]\mbox{}\\
A new \NFS\ file server has been referenced and is known to be up.

\item[\tt file server \Var{rhost} type nfs starts down]\mbox{}\\
A new \NFS\ file server has been referenced and is known to be down.

\item[\tt file server \Var{rhost} type nfs is up]\mbox{}\\
An \NFS\ file server that was previously down is now up.

\item[\tt file server \Var{rhost} type nfs is down]\mbox{}\\
An \NFS\ file server that was previously up is now down.

\item[\tt Finishing with status {\em exit-status}]\mbox{}\\
\Amd\ is about to exit with the given exit status. 

\item[\tt {\em mount-info} mounted fstype \Var{type} on \Var{fs}]\mbox{}\\
A new file system has been mounted.

\item[\tt {\em mount-info} restarted fstype \Var{type} on \Var{fs}]\mbox{}\\
\Amd\ is using a pre-mounted filesystem to satisfy a mount request.

\item[\tt {\em mount-info} unmounted fstype \Var{type} from \Var{fs}]\mbox{}\\
A file system has been unmounted.

\item[\tt {\em mount-info} unmounted fstype \Var{type} from \Var{fs} link \Var{fs}/\Var{sublink}]\mbox{}\\
A file system of which only a sub-directory was in use has been unmounted.

\end{description}

\Chapter*{Acknowledgements \& Trademarks}
\addcontentsline{toc}{chapter}{Acknowledgements \& Trademarks}
Thanks to the Formal Methods Group at Imperial College for
suffering patiently while \amd\ was being developed on their machines.

Thanks to the many people who have helped with the development
of \amd\, especially Piete Brooks at the Cambridge University Computing Lab for
many hours of testing, experimentation and discussion.

\begin{trivlist}
\item[{\sf DEC}, {\sf VAX} and {\sf Ultrix}]
 are registered trademarks of Digital Equipment Corporation.
\item[{\sf IBM}]
is a registered trademark of International Business Machines Corporation.
\item[{\sf Sun}, {\sf NFS} and {\sf SunOS}]
are registered trademarks of Sun Microsystems, Inc.
\item[{\sf Unix}]
is a registered trademark of AT\&T Bell Laboratories in
the USA and other countries.
\item[{\sf UTX}]
is a registered trademark of Gould, Inc.
\end{trivlist}