2448 lines
103 KiB
TeX
2448 lines
103 KiB
TeX
% If you somehow got this file without fullpage.sty, delete
|
|
% ``fullpage'' from the list of style options. It just pulls out the
|
|
% margins a bit.
|
|
\documentstyle[11pt,twoside,fullpage]{report}
|
|
% New commands
|
|
%-------------
|
|
|
|
% for meta-symbols
|
|
\newcommand{\meta}[1]{{\bf \mbox{\(<\)#1\(>\)}}}
|
|
% for literal tokens.
|
|
\newcommand{\lit}[1]{{\tt \mbox{#1}}}
|
|
%for attributes
|
|
\newcommand{\atr}[1]{\mbox{\sc #1}}
|
|
% for identifying text
|
|
\newcommand{\text}[1]{{\em #1}\/}
|
|
|
|
% Start and end of One or More
|
|
\newcommand{\ooms}{\([\,\)}
|
|
\newcommand{\oome}{\(\,]^+\)}
|
|
% start and end of zero or more
|
|
\newcommand{\zoms}{\([\,\)}
|
|
\newcommand{\zome}{\(\,]^*\)}
|
|
% Start and end of zero or one
|
|
\newcommand{\zoos}{\([\,\)}
|
|
\newcommand{\zooe}{\(\,]\)}
|
|
% start an OR
|
|
\newcommand{\ors}{{\bf (\,}}
|
|
\newcommand{\ore}{{\bf \,) }}
|
|
\newcommand{\metaor}{{\em \,or\, }}
|
|
\newcommand{\hexnum}[1]{\(\mbox{#1}_{16}\)}
|
|
\newcommand{\unix}{{\sc unix}}
|
|
\newcommand{\selectlines}{\zoms\meta{LF} \\ \lit{SELECT} \meta{applies-to}
|
|
\ors\lit{FIELD} \metaor \lit{INTRINSIC}
|
|
\metaor \lit{APPLICATION}\ore \meta{attribute-name}
|
|
\meta{attribute-value-type}\ore
|
|
\zoms\meta{value-tuple-element}\zome\zome}
|
|
\newenvironment{command}{\begin{verse}\sloppy}{\end{verse}}
|
|
\newcommand{\commandsize}{\large}
|
|
|
|
%\newtheorem{example}{Example}
|
|
% Uncomment this for almost-double spacing
|
|
%\renewcommand{\baselinestretch}{1.7}
|
|
%\newcommand{\hozline}{\rule{\textwidth}{0.3mm}}
|
|
%\newcommand{\hozline}{\makebox[\textwidth]{\hrulefill}}
|
|
%\newcommand{\bex}{\begin{example} \begin{rm}}
|
|
%\newcommand{\eex}{$\Box$ \end{rm} \end{example}}
|
|
%\newcommand{\cbs}{\chgbarbegin}
|
|
%\newcommand{\cbe}{\chgbarend}
|
|
%\newcommand{\cbs}{}
|
|
%\newcommand{\cbe}{}
|
|
|
|
%\newcommand{\ptag}{\begin{flushright} {\rm ($P$)} \end{flushright} }
|
|
|
|
|
|
\begin{document}
|
|
|
|
\pagenumbering{arabic}
|
|
\pagestyle{plain}
|
|
|
|
\renewcommand{\thepage}{\arabic{page}}
|
|
|
|
|
|
%\title{The Prospero Protocol, version 5\thanks{
|
|
% This research was supported in part by the National Science
|
|
% Foundation (Grant No. CCR-8619663), the Washington Technology Center,
|
|
% Digital Equipment Corporation, and the Defense Advanced Research
|
|
% Projects Agency under NASA Cooperative Agreement NCC-2-539}
|
|
%}
|
|
%
|
|
%\author{B. Clifford Neuman\thanks{
|
|
% To Contact the Authors: \protect\\
|
|
%Electronic Mail: \protect\mbox{\protect\verb"info-prospero@isi.edu"} \\
|
|
% Telephone: +1 (310) 822-1511 \protect\\
|
|
% Mail: USC Information Sciences Institute \\
|
|
% 4676 Admiralty Way \\
|
|
% Marina del Rey, California 90292--6695 U.S.A. }
|
|
% \and Steven Seger Augart
|
|
%\and Information Sciences Institute \\
|
|
% University of Southern California
|
|
%}
|
|
%%
|
|
%%
|
|
%\date{
|
|
|
|
%\maketitle
|
|
\begin{titlepage}
|
|
|
|
\renewcommand{\thefootnote}{}
|
|
\footnotetext{\hspace*{-21pt}
|
|
Digital copies of the latest revision of this document may be obtained
|
|
through Prospero as
|
|
\mbox{\verb"/papers/subjects/operating-systems/prospero/doc/protocol.PS.Z"},
|
|
in the \mbox{\tt \#/INET/EDU/ISI/swa} virtual system, or through
|
|
Anonymous FTP from \mbox{\tt PROSPERO.ISI.EDU} as
|
|
\mbox{\verb"/pub/prospero/doc/prospero-protocol.PS.Z"}
|
|
}
|
|
\footnotetext{\hspace*{-21pt}
|
|
This work was supported in part by the National Science
|
|
Foundation (Grant No. CCR-8619663), the Washington Technology Center,
|
|
Digital Equipment Corporation, and the Defense Advance Research
|
|
Projects Agency under NASA Cooperative Agreement NCC-2-539.
|
|
The views and conclusions contained in
|
|
this document are those of the authors and should not be interpreted as
|
|
representing the official policies, either expressed or implied, of
|
|
any of the funding agencies.
|
|
The authors may be reached
|
|
at USC/ISI, 4676 Admiralty Way, Marina del Rey, California\ \ 90292-6695, USA.
|
|
Telephone +1 (310) 822-1511, email \mbox{\verb"info-prospero@isi.edu"}. }
|
|
\renewcommand{\thefootnote}{\arabic{footnote}}
|
|
|
|
|
|
\vspace*{\fill}
|
|
\begin{center}
|
|
\LARGE The Prospero Protocol\\
|
|
\Large Version 5\\
|
|
\vskip 1.5em
|
|
{\large Draft of 12 June 1993} \\
|
|
{\large Document Revision No. 0.3} \\
|
|
\end{center}
|
|
\vspace{.5in}
|
|
|
|
\Large \hspace*{\fill} B. Clifford Neuman
|
|
%\footnotetext{\hspace*{-18pt}
|
|
% To Contact the Authors: \\
|
|
% Electronic Mail: \mbox{\verb"info-prospero@isi.edu"} \\
|
|
% Telephone: +1 (310) 822-1511 \\
|
|
% Mail: USC Information Sciences Institute, 4676 Admiralty Way,
|
|
% Marina del Rey, California 90292--6695\ \ U.S.A.
|
|
%}
|
|
\hfill Steven Seger Augart \hspace*{\fill} \\
|
|
\vspace{.2in}
|
|
\begin{center}
|
|
\Large Information Sciences Institute \\
|
|
University of Southern California
|
|
\end{center}
|
|
\vspace*{1.2in}
|
|
\vspace*{\fill}
|
|
\end{titlepage}
|
|
|
|
\tableofcontents
|
|
|
|
\chapter{Introduction}
|
|
|
|
This document describes version 5 of the Prospero protocol.
|
|
Communication with directory servers uses a reliable delivery protocol
|
|
described in Appendix~\ref{ardp}.
|
|
Requests and responses are human readable commands and multiple
|
|
commands may be sent in a single message.
|
|
|
|
Prospero is implemented on top of a message-based protocol to reduce the
|
|
overhead that would otherwise be incurred when establishing
|
|
connections to multiple directory servers. The decision to use a
|
|
message protocol directly, instead of through a higher level
|
|
mechanism such as remote procedure call, was made for reasons of
|
|
portability. We did not want Prospero to depend on another protocol,
|
|
software package, or other resource, unless that resource was almost
|
|
universally supported by every computer on the Internet.
|
|
|
|
The use of humanly readable commands in the protocol has several
|
|
advantages. It eliminates problems with byte ordering, and it makes
|
|
future changes or additions to the protocol easier to incorporate
|
|
while maintaining compatibility across versions; new commands or
|
|
additional options to existing commands can be easily added.
|
|
|
|
The ability to request multiple operations in a single message
|
|
improves performance, and it provides a simple way to request that a
|
|
collection of operations (on a single server) be performed atomically.
|
|
|
|
The concept of an ``attribute'' appears frequently in the following
|
|
command description. For a discussion of attributes, read
|
|
appendix~\ref{db} of this document.
|
|
|
|
\section{Additional Documents}
|
|
|
|
The Prospero documentation series will include the following:
|
|
\begin{description}
|
|
|
|
\item[Prospero Protocol Specification] You're reading it. Right now,
|
|
this is the most current document we have, but it will eventually be
|
|
re-targeted towards a more specialized audience when the other guides
|
|
in the series are written and revised.
|
|
|
|
\item[Prospero System User's Guide] This will describe the general
|
|
features of the Prospero system that will be common to almost all user
|
|
interfaces, such as ACL types and filters.
|
|
|
|
\item[Prospero Command-Line Client User's Guide] Describes the
|
|
command-line client package; this is the client that's been shipped
|
|
with all Prospero releases.
|
|
|
|
\item[Prospero Gopher Client User's Guide] This describes the
|
|
Gopher menu-based client package, which is in progress.
|
|
|
|
%\item[Prospero World-Wide Web Client User's Guide] This describes the
|
|
%World-Wide Web hypertext client package, which hasn't yet been written
|
|
%but is going to be done Real Soon Now.
|
|
|
|
\item[Prospero Programmer's Manual] This describes the \lit{pfs}
|
|
and \lit{pcompat} libraries, which Prospero applications programmers
|
|
use to interface with Prospero.
|
|
|
|
\end{description}
|
|
|
|
\chapter{Command Introduction}
|
|
|
|
\section{Spaces, quoting, and line-feeds}
|
|
|
|
Prospero messages are divided into lines. Lines are divided into
|
|
tokens. Commands and lines sent in response are separated by an
|
|
unquoted {\sc ASCII} \meta{LF} character.
|
|
|
|
Within a line, tokens are separated by unquoted horizontal whitespace
|
|
(one or more {\sc ASCII} spaces and/or tabs). Client and server
|
|
implementations are not required to accept lines which begin or end
|
|
with horizontal whitespace, but are encouraged to do so. Similarly,
|
|
implementations are encouraged to accept \meta{CR} or
|
|
\meta{CR}\meta{LF} as alternative acceptable line terminators, but are
|
|
not required to do so.
|
|
|
|
% ``Be conservative in what you send, generous
|
|
%in what you accept.'' (J. Postel)
|
|
|
|
Special characters within a command token, or null tokens, can be
|
|
quoted using single quotes (\lit{'}).
|
|
While inside quotes, a quote can be included by doubling it. The only
|
|
character that cannot be quoted is the ASCII null character
|
|
(character code zero; \verb"'\0'" for C programmers). This is really
|
|
a limitation of the server implementation, which passes Prospero
|
|
packets, commands, and tokens around internally as null-terminated
|
|
C strings.\footnote{If you wish to send binary data around, we
|
|
recommend that you
|
|
encode it into a null-less form using the \lit{pfs} library's
|
|
\lit{binencode()} and \lit{bindecode()} routines.}
|
|
|
|
Any token may be quoted (although most will not need quoting), except
|
|
for literal command tokens (\lit{VERSION}, \lit{ID}, etc.).
|
|
Also, the \meta{multi-component} token uses the quoting system in a
|
|
special way --- see the \lit{LIST} command for details.
|
|
|
|
\section{Options}
|
|
|
|
Many Prospero Protocol commands take options. If multiple options are
|
|
to be specified for a single command, the options are separated by a
|
|
``\lit{+}''. If no options are specified, then the null string should be
|
|
sent to indicate this. The null string will need to be quoted, like
|
|
so: \lit{'{}'}
|
|
|
|
\section{Metasyntax}
|
|
|
|
In this document, we will use some meta-syntactic features to describe
|
|
commands. Literal tokens (such as \lit{LITERAL-TOKEN}) appear in a
|
|
typewriter font. Non-terminals look like this: \meta{non-terminal}.
|
|
The line-feed, carriage-return, and space characters are represented
|
|
as \meta{LF}, \meta{CR}, and \meta{SPC}, respectively. Alternation
|
|
(choice among two or more possibilities) looks like:
|
|
\ors\meta{option1} \metaor \meta{option2} \ore
|
|
|
|
We also use
|
|
the following meta-syntactic constructs:
|
|
|
|
%\begin{table}[htb]
|
|
\begin{center}
|
|
\begin{tabular}{|c|c|l|} \hline
|
|
\multicolumn{3}{|c|}{Metasyntax used to describe commands} \\ \hline
|
|
Start & End & \multicolumn{1}{c|}{Meaning} \\ \hline
|
|
[ & ] & One or zero repetitions. \\ \hline
|
|
[ & \(]^*\) & Zero or more repetitions. \\ \hline
|
|
[ & \(]^+\) & One repetition or more. \\ \hline
|
|
\end{tabular}
|
|
\end{center}
|
|
%\end{table}
|
|
|
|
|
|
\section{Objects}
|
|
|
|
A Prospero object is anything to which a normal link (\meta{link-type} =
|
|
\lit{L}) can be made, except for \lit{EXTERNAL} objects.
|
|
|
|
\subsection{Base Type\label{base type}}
|
|
|
|
Every Prospero object has one or more base types associated with it.
|
|
All Prospero objects have a base type of OBJECT. This means that they
|
|
can have attributes attached to them. In addition, objects with a base
|
|
type of FILE can store data, and objects with a base type of DIRECTORY
|
|
can store directory information.
|
|
|
|
\begin{sloppypar}
|
|
The base type of a Prospero object is accessible
|
|
through the \atr{base-type} intrinsic attribute. The primitive
|
|
value for \atr{base-type} is \lit{OBJECT}. If an object's
|
|
\atr{base-type} attribute has a value of %\linebreak[3]
|
|
\lit{OBJECT+FILE+DIRECTORY},
|
|
then the object can have attributes attached to it, can contain data,
|
|
and can contain links. As a shorthand, since all objects have
|
|
\lit{OBJECT} as one of their base types, an object with more than one
|
|
base type can have the \lit{OBJECT} implied, so that the \atr{base-type}
|
|
value \lit{OBJECT+FILE+DIRECTORY} is equivalent to the value
|
|
\lit{FILE+DIRECTORY} and the value \lit{FILE} is equivalent to the
|
|
value \lit{FILE+OBJECT}. The order of values in the \atr{base-type}
|
|
attribute is unimportant, so \lit{DIRECTORY+FILE} is equivalent to
|
|
\lit{FILE+DIRECTORY}.
|
|
\end{sloppypar}
|
|
|
|
In the rest of this document, when
|
|
we say ``directory,'', we mean ``an object which has
|
|
\lit{DIRECTORY} as part of its \atr{base-type}.'' When we say ``file,''
|
|
we mean ``an object which has \lit{FILE} as part of its \atr{base-type}.''
|
|
|
|
One may use \lit{EDIT-OBJECT-INFO} to edit the \atr{base-type}
|
|
attribute to remove the \lit{FILE} type from it only if the file is
|
|
empty (zero length), and one may remove the \lit{DIRECTORY} type from
|
|
it only if the directory is empty (contains no links). To add a type
|
|
to the \atr{base-type}, one must use the \lit{ADD} option to
|
|
\lit{CREATE-OBJECT}.
|
|
|
|
\subsection{Host-Specific Object Names ({\sc hsoname}s)}
|
|
|
|
Every Prospero object has an
|
|
\meta{hsoname}. {\sc hsoname}s are not guaranteed to be unique across time; if
|
|
an object is deleted,
|
|
a new
|
|
object may be created that re-uses the old object's handle. However,
|
|
at any particular moment, two Prospero objects on the same server are
|
|
guaranteed to have unique hsonames, unless they are different versions
|
|
of the same object (i.e., unless their \atr{version-number} fields are
|
|
different.)
|
|
|
|
Two objects on different servers might have identical
|
|
hsonames.
|
|
In the current server implementation, the \meta{hsoname-type} is always
|
|
\lit{ASCII} and the \meta{hsoname} is almost always a full
|
|
(i.e., starting with a slash (\lit{/})) \unix\
|
|
filesystem pathname. See appendix~\ref{conventions} for more
|
|
discussion of this.
|
|
The \meta{hsoname-type} token exists because some special
|
|
filesystems may have non-\lit{ASCII} \meta{hsoname}s.
|
|
|
|
\subsection{Versions\label{object version numbers}}
|
|
|
|
We intend to allow versioned objects. All objects, including
|
|
directories, have a
|
|
\atr{version-number} field. In the current server
|
|
implementation, the \atr{version-number} field is always zero, which means
|
|
``unversioned''. It need not be in future server implementations.
|
|
|
|
In commands and responses, providing a zero value for the
|
|
\meta{object-version} token means to retrieve the current version of
|
|
the object. Specifying explicit values means that a particular
|
|
version of the object is required. Explicit object version numbers
|
|
(when they are established) will always be positive integers.
|
|
|
|
\subsection{Object \lit{ID} fields}
|
|
|
|
The \lit{ID} field is a unique (or nearly unique)
|
|
identifier for an object. If the underlying object changes (such as
|
|
by editing), then some types of \lit{ID}s will change and
|
|
others will not. If two
|
|
objects have the same \lit{ID}, then they are considered by Prospero
|
|
to be the same object. This is useful for distinguishing between two
|
|
cases: (a) two
|
|
links which happen to have the same \meta{name-component} but
|
|
different storage locations (a different host and handle pair), and which
|
|
do not actually represent the same object, and (b) two links which have the
|
|
same \meta{name-component} and same \lit{ID}, but possibly different storage
|
|
locations --- in case (b), the objects are replicas and the client
|
|
should access whichever one it
|
|
chooses to. (Code is currently under development to enable
|
|
servers to return a list of replicas in order of nearness to
|
|
the client.) Two links with the same \meta{name-component} and no
|
|
\lit{ID} specification are considered by Prospero to be different
|
|
objects, not replicas of one another.
|
|
|
|
A problem with the \lit{ID} field is that there is not an accepted
|
|
standard for universal document identifiers. An IETF working group has
|
|
been formed to consider such identifiers, and the \lit{ID}
|
|
field exists in anticipation of their eventual agreement upon a standard.
|
|
We expect that there will be more than one type of universal document
|
|
identifier; therefore, there will be more than one \meta{id-type}.
|
|
Prospero supports objects with several possible \lit{ID}s.%
|
|
\footnote{This will go into the user's manual when we revise it. The
|
|
user-level names for two links distinguished only by their \lit{ID}
|
|
fields are:
|
|
\begin{command}
|
|
\ors\meta{name-component}\lit{\#}\lit{\#}\(\mbox{\meta{id-type}}_1\)\lit{\#}\(\mbox{\meta{id-value-token}}_{1,1}\)\lit{\#}\(\mbox{\meta{id-value-token}}_{1,2}\)\ldots % permit a line break here
|
|
\lit{\#}\lit{\#}\(\mbox{\meta{id-type}}_2\)\lit{\#}\(\mbox{\meta{id-value-token}}_{2,1}\)\lit{\#}\(\mbox{\meta{id-value-token}}_{2,2}\)\ldots \\
|
|
\metaor \meta{name-component}\lit{\#}\(\mbox{\meta{id-value-token}}_1\)\lit{\#}\meta{id-value-token$_2$}\ldots \ore
|
|
\end{command}
|
|
|
|
The second form matches any \meta{id-type}. The first form is used to
|
|
explicitly specify one or more \meta{id-type}s.
|
|
|
|
}
|
|
|
|
For now, there are only two \meta{id-type}s defined. The \lit{REMOTE}
|
|
\meta{id-type} is used by the server when it has magic
|
|
knowledge (perhaps through a local database) that
|
|
two objects are the same. The \lit{REMOTE} id type is a single
|
|
element which is the printed decimal representation of a positive
|
|
integer. This positive integer should be able to be stored in a 32
|
|
bit integer. A \lit{REMOTE} id value of 0 means ``unspecified''.
|
|
The \lit{REMOTE}
|
|
\meta{id-type} cannot be sent across the network by clients in
|
|
queries.%
|
|
\footnote{The \meta{id-value} of the \lit{REMOTE} type
|
|
is the same as the \meta{magic-no} token specified in version 1 of the
|
|
Prospero protocol.} It is not guaranteed to be consistent across different
|
|
queries to the server, but server implementors are encouraged to make
|
|
the \meta{id-value} token consistent across queries.
|
|
|
|
Many clients will locally generate \lit{ID} fields to
|
|
help the human user differentiate between conflicting links. These
|
|
\lit{ID} fields will have an \meta{id-type} of \lit{LOCAL} and an
|
|
arbitrarily generated string as their \meta{id-value}. They may not be
|
|
sent over the network, and are not guaranteed to be unique from
|
|
directory read to directory read, although implementors are encouraged
|
|
to make them so. All available \lit{ID} fields will be returned with
|
|
every \lit{LIST} operation.
|
|
|
|
\chapter{Commands Reference}
|
|
|
|
All Prospero commands are listed below.
|
|
|
|
\section{VERSION}
|
|
|
|
\begin{command}
|
|
\commandsize \lit{VERSION} \meta{version-number}
|
|
\zoos\meta{software-identifier}\zooe
|
|
\end{command}
|
|
|
|
This command requests or specifies the protocol version number. If
|
|
the specified protocol version number is not supported, the response
|
|
will be:
|
|
|
|
\begin{command}
|
|
\lit{VERSION-NOT-SUPPORTED TRY} \meta{min-version-number}\lit{-}\meta{max-version-number}
|
|
\end{command}
|
|
or
|
|
\begin{command}
|
|
\lit{VERSION-NOT-SUPPORTED TRY} \meta{version-number}
|
|
\end{command}
|
|
|
|
|
|
|
|
Where \meta{version-number} or
|
|
\meta{min-version-number}\lit{-}\meta{max-version-number} are those
|
|
versions that are supported.
|
|
If no arguments are supplied (or if the argument is not a
|
|
number), then the \lit{VERSION} command will return the current
|
|
protocol version number being used by the server in the form:
|
|
|
|
\begin{command}
|
|
\lit{VERSION} \meta{version-number} \zoos\meta{software-identifier}\zooe
|
|
\end{command}
|
|
|
|
If the \meta{software-identifier} is specified, it identifies
|
|
the software and version of the software that is generating the
|
|
message.\footnote{Software developers wishing to obtain software
|
|
identifiers should send electronic mail to {\tt pfs-administrator@isi.edu}.}
|
|
|
|
\section{AUTHENTICATE}
|
|
|
|
\begin{command}
|
|
\commandsize \lit{AUTHENTICATE} \meta{options} \meta{authenticator-type}
|
|
\meta{authentication-data} \zoms\meta{principal-name}\zome
|
|
\end{command}
|
|
|
|
This command authenticates the principal making the request. The
|
|
\meta{authenticator-type} is the type of the authenticator. It might
|
|
be a password, a Kerberos
|
|
authenticator, or data used by an alternative authentication
|
|
mechanism. The currently supported values for
|
|
\meta{authenticator-type} are \lit{UNAUTHENTICATED}, \lit{KERBEROS},
|
|
and \lit{HANDLE}.
|
|
|
|
If the \meta{authenticator-type} is \lit{UNAUTHENTICATED}, this is
|
|
honored by the \lit{ASRTHOST} ACL type. It is also honored by the \lit{TRSTHOST} ACL
|
|
type if the client is
|
|
using a privileged port. If the \meta{authenticator-type} is
|
|
\lit{UNAUTHENTICATED}, then the \meta{authentication-data} should be
|
|
the username of the user running the client. This username is be the
|
|
principal referred to by the ACL.
|
|
|
|
If the \meta{authenticator-type} is \lit{KERBEROS}, then the
|
|
\meta{authentication-data} is a Kerberos authentication message
|
|
authenticating the
|
|
principal to the Prospero server. The ACL principal will be the same as the
|
|
Kerberos principal. The ACL type will be \lit{AUTHENT} \lit{KERBEROS}.
|
|
|
|
If the \meta{authenticator-type} is \lit{HANDLE}, then the
|
|
\meta{authentication-data} is a handle returned in response to a
|
|
previous \lit{AUTHENTICATE} command.
|
|
|
|
The optional \meta{principal-name}s are informational only for some
|
|
authentication types, and exist only for human convenience. The
|
|
server will extract the principal names from the
|
|
\meta{authentication-data}, but the names might be encrypted in the
|
|
\meta{authentication-data} or otherwise represented in a way that
|
|
humans cannot easily decipher them. (For instance, this is the case
|
|
with Kerberos version 5.) In the case of the \lit{P\_PASSWORD}
|
|
authentication type, the \meta{principal-name}s are not optional.
|
|
|
|
More than one \lit{AUTHENTICATE} command may be sent in a single
|
|
message. This can be used both to authenticate oneself as multiple
|
|
simultaneous principals and to authenticate oneself using several methods.
|
|
|
|
The response may take one of several forms. If the authentication
|
|
fails, then the response is:
|
|
\begin{command}
|
|
\lit{FAILURE} \lit{AUTHENTICATION-DATA} \zoos\text{explanatory text}\zooe
|
|
\end{command}
|
|
One might get this response if an authentication handle has expired.
|
|
|
|
If it is computationally expensive for the server to validate the
|
|
authentication data, it may want to cache the fact that the data has
|
|
been validated, and return a handle that the client may use in future
|
|
requests to the server:
|
|
\begin{command}
|
|
\lit{AUTHENTICATED} \zoos\meta{authentication-handle}
|
|
\zoos\meta{handle-expiration-time}\zooe \zooe
|
|
\end{command}
|
|
The \meta{handle-expiration-time}, if provided, is in ASN-TIME format.
|
|
|
|
The response may be another \lit {AUTHENTICATE} command if the server
|
|
needs to authenticate itself to the client.\footnote{XXX: Not
|
|
currently implemented.} The response may simply be:
|
|
\begin{command}
|
|
\lit{AUTHENTICATED}
|
|
\end{command}
|
|
to indicate that the authentication succeeded. If other commands are
|
|
included in the same packet as the \lit{AUTHENTICATE} request (this
|
|
will almost always be the case), then successful execution of theose
|
|
other commands implies that the authentication succeeded; in this case,
|
|
the server is not required to include the \lit{AUTHENTICATED} response.
|
|
|
|
Currently, no options are defined, so the \meta{options} token is
|
|
always the null string.
|
|
|
|
\section{DIRECTORY}
|
|
|
|
\begin{command}
|
|
\commandsize \lit{DIRECTORY} \meta{hsoname-type} \meta{hsoname}
|
|
\zoos\meta{object-version}\zooe \selectlines
|
|
\end{command}
|
|
|
|
|
|
This command specifies the directory to be read or modified by the
|
|
commands that follow as part of the same request. This command
|
|
does not generate a response unless the selected directory is not a
|
|
directory. In that case, the response:
|
|
\begin{command}
|
|
\lit{FAILURE NOT-A-DIRECTORY}
|
|
\end{command}
|
|
is returned, and the remainder of the request ignored.
|
|
|
|
\section{ATOMIC}
|
|
|
|
\begin{command}
|
|
\commandsize \lit{ATOMIC}
|
|
\end{command}
|
|
|
|
This command specifies that all commands that follow are to be
|
|
completed atomically. If one of the commands fails, then none of the
|
|
commands are to have an effect. This may require undoing the effects
|
|
of commands which have already completed. Note that this command works
|
|
only for requests issued in the same message, and all commands must
|
|
be executable on the single server to which the message was sent.
|
|
|
|
This command is not currently implemented.
|
|
|
|
\section{LIST}
|
|
|
|
\begin{command}
|
|
\commandsize \lit{LIST} \meta{options} \lit{COMPONENTS}
|
|
\zoms\meta{name-component}\zome\selectlines\meta{LF}\\
|
|
\lit{FILTER} ...
|
|
\end{command}
|
|
|
|
\lit{LIST} is used to look up information stored in a directory. It
|
|
must be preceded by a \lit{DIRECTORY} command in the same request. Each
|
|
optional \meta{name-component} is a component of a
|
|
multiple-component name relative to the directory specified in the
|
|
\lit{DIRECTORY} command. The last component may include wildcards. If no
|
|
\meta{name-component} is specified, the wildcard ``*'' is implied
|
|
(i.e., all listable components in the directory will be listed).\footnote{
|
|
The protocol is currently in transition. The old format was as
|
|
follows:
|
|
Multiple component names are allowed, and are specified as a single
|
|
token following the \meta{name-component}. The multiple components within
|
|
a single name are separated by the unquoted slash (\lit{/}). Servers
|
|
and clients for now are accepting both versions of the protocol
|
|
message, which means that the 1st component of a multiple-component
|
|
name must be quoted if it contains a slash.}
|
|
If the result of
|
|
the lookup of one component is another directory at the same storage
|
|
site, then the directory server will repeat the process and look up
|
|
the next component. When a lookup results in a dead-end, or a
|
|
directory at another site, the server will return an \lit{UNRESOLVED}
|
|
message, indicating which components remain to be resolved by the client.
|
|
|
|
If a space, tab, slash, or \meta{LF} is to be included in a component
|
|
of a single-component or multi-component name, the component must be
|
|
quoted. Quoting a slash in a single-component or multi-component name
|
|
means that the slash is not considered to separate components of a
|
|
multi-component name, but rather to be a part of a single component.
|
|
This somewhat awkward syntax allows us to have single components
|
|
which contain slashes or horizontal whitespace or \meta{LF}s.
|
|
|
|
\subsection{Wildcards}
|
|
|
|
The \meta{name} tokens in the \lit{LIST} command are the
|
|
only places in the Prospero protocol where components may be specified
|
|
with wildcards. There are two wildcard characters supported:
|
|
\begin{description}
|
|
\item[\lit{*}] Match zero or more characters.
|
|
\item[\lit{?}] Match exactly one character.
|
|
\end{description}
|
|
Wildcards may only be used to expand at a single-component level; by
|
|
this, we mean that the wildcarded \meta{name}
|
|
\lit{foo?bar} would match the single-component name whose name in
|
|
the current directory was \lit{foo-bar},
|
|
but would not match the object whose multiple-component name in the
|
|
current directory was \verb"foo/bar".
|
|
|
|
One may also wildcard a name by giving a full regular expression. To
|
|
do this, the regular expression should be enclosed within parentheses.
|
|
For instance, specifying (Anne.*) is equivalent to specifying the
|
|
wildcarded name 'Anne*'.
|
|
|
|
In addition to any wildcards specified, a literal match for the
|
|
wildcard will also happen.
|
|
|
|
\subsection{Options}
|
|
|
|
\meta{options} contains a (possibly empty) list of options to the
|
|
\lit{LIST} command. If no options are specified, an empty
|
|
list of options should be sent as
|
|
a null token (\lit{'{}'}.)
|
|
|
|
\subsubsection{Miscellaneous Options}
|
|
|
|
Among the options supported are \lit{EXPAND} which tells the remote directory
|
|
server to expand any union entries in the directory. By default, the
|
|
response will contain the names of union links to be included, and the
|
|
client must submit a new query. A directory server can ignore the
|
|
\lit{EXPAND} option to the list command if it so desires. The \lit{LEXPAND}
|
|
option is the same as \lit{EXPAND}, but indicates that the server should
|
|
only expand union entries for local directories. The \lit{LEXPAND} option
|
|
is implied if a multiple component name is being resolved.
|
|
|
|
The \lit{VERIFY} option tells the remote server that the purpose of the
|
|
query is to verify whether the remote directory exists and is a
|
|
directory. No components are to be returned; instead, the message
|
|
returned on success is \lit{NONE-FOUND}.
|
|
|
|
\subsubsection{\protect\lit{ATTRIBUTES} option}
|
|
|
|
The \lit{ATTRIBUTES} option indicates that the attributes associated with
|
|
the link are to be returned. (If the object is on the same host as
|
|
the directory, then the server may ignore CACHED attributes and return
|
|
OBJECT attributes instead.
|
|
|
|
\lit{ATTRIBUTES} is optionally immediately
|
|
followed by an argument list, which is a parenthesized \mbox{\lit{+}-se}para\-ted
|
|
list of attributes to be
|
|
returned. If the \lit{ATTRIBUTES} option is specified without any
|
|
attributes requested, then it is just the same as if one had specified
|
|
\lit{ATTRIBUTES(\#INTERESTING)}. Note that union links do not
|
|
normally have any interesting attributes attached to them, except
|
|
for \lit{FILTER}.
|
|
|
|
\lit{ATTRIBUTES(ID+FILTER)} is always implied. For \lit{EXTERNAL}
|
|
links, \lit{ATTRIBUTES(ACCESS-METHOD)} is always implied.\footnote{
|
|
This restriction seems odd, but it makes certain details of
|
|
programming the client libraries much easier.}
|
|
|
|
There are some special arguments to the
|
|
\lit{ATTRIBUTES} option. It is not a good idea for application-defined
|
|
attributes to have names that conflict with these special arguments; if
|
|
there are such application-defined attributes, you may have to use the
|
|
\lit{\#ALL} special argument to look at their values. More than one
|
|
special argument may be specified, and one may mix special and
|
|
non-special arguments. Also, note that it is never erroneous
|
|
for a server to return more attributes
|
|
than were asked for, nor is it erroneous for a server to return
|
|
attribute information even if no \lit{ATTRIBUTES} option was specified
|
|
to the \lit{LIST} command. A server that always behaved as if the
|
|
\lit{ATTRIBUTES(\#ALL)} option were specified would be behaving
|
|
legally, although it would not be terribly efficient.
|
|
|
|
\begin{description}
|
|
\item[\lit{\#INTERESTING}] Return only interesting attributes. What
|
|
constitutes an ``interesting'' attribute is server-dependent.
|
|
This allows one to use Prospero for special applications.
|
|
\item[\lit{\#ALL}] If this argument is specified, and the object resides
|
|
on the same host as
|
|
the link, then the attributes stored with the object referenced by the
|
|
link will be returned in addition to those stored with the link, and
|
|
no cached attributes will be returned (they would be irrelevant). If
|
|
the object resides on a host different from the link, then all
|
|
attributes stored with the link are returned, but not those stored
|
|
with the object referenced by the link.
|
|
\item[\lit{\#CACHED}] Return all attributes of type \lit{CACHED}.
|
|
If you specify \lit{\#CACHED} with \lit{\#ALL}, the server will return cached
|
|
attributes in addition to those that would be returned if you'd just
|
|
specified \lit{\#ALL}. It is not clear how useful this behavior is.
|
|
\item[\lit{\#OBJECT}] Return all attributes of type \lit{OBJECT}. Note that
|
|
this will not work if the object does not reside on the same host as
|
|
the link.
|
|
\item[\lit{\#ADDITIONAL}] Return all \lit{ADDITIONAL} attributes
|
|
\item[\lit{\#REPLACEMENT}] Return all \lit{REPLACEMENT} attributes.
|
|
\item[\lit{\#LINK}] Return all \lit{LINK} attributes.
|
|
\item[\lit{\#FIELD}] Return all fields (all system-defined standard
|
|
attributes), except for ones that have already been returned as part of
|
|
the \lit{LINK} response, such as \atr{host}, \atr{handle}, and
|
|
\atr{dest-exp}.
|
|
\item[\lit{\#\#FIELD}] Return all fields. (This option will be
|
|
rarely used.)
|
|
\item[\lit{\#APPLICATION}] Return all application-defined
|
|
attributes.
|
|
\end{description}
|
|
|
|
\subsubsection{\protect\lit{FILTER} option}
|
|
|
|
If the \lit{FILTER} option is specified, the \lit{LIST} command will
|
|
be followed by one or more lines representing one or more
|
|
\lit{PREDEFINED} filters to
|
|
be applied at the server.
|
|
|
|
The filters are applied in the order in which they follow the
|
|
\lit{LIST} command. Their format is just like that of
|
|
\lit{FILTER} information returned from the \lit{LIST} command (see
|
|
subsection~\ref{filter}), except that the \meta{execution-location} field must always
|
|
be \lit{SERVER}, and the first four tokens (``\lit{ATTRIBUTE LINK
|
|
FIELD FILTER}'') are omitted. The format is:
|
|
\begin{command}
|
|
\lit{FILTER} \meta{filter-type} \lit{SERVER} \meta{pre-or-post}
|
|
\lit{PREDEFINED} \meta{filter-name} \\
|
|
\zoos \lit{ARGS} \zoms\meta{filter-arg}\zome \zooe
|
|
\end{command}
|
|
The server will know that there are no more filter-specifying lines
|
|
either when the end of the message is reached or it encounters a line
|
|
that does not begin with the token \lit{FILTER}.
|
|
|
|
\subsection{Returned Information}
|
|
|
|
On failure, a standard error response will be returned. On success,
|
|
the response will be a sequence of entries containing information
|
|
about the requested files.
|
|
|
|
\subsubsection{Links}
|
|
|
|
\begin{command}
|
|
\lit{LINK} \meta{link-type} \meta{target} \meta{name-component} \meta{host-type} \meta{host-name}
|
|
\meta{hsoname-type} \meta{hsoname} \meta{object-version}
|
|
[ \lit{DEST-EXP} \meta{dest-expiration} ]
|
|
\end{command}
|
|
|
|
In the case of links to objects, \meta{dest-expiration} is the value
|
|
of the object's \atr{dest-exp} field.
|
|
|
|
The \meta{link-type}
|
|
token is defined as follows:
|
|
\begin{description}
|
|
\item[\lit{L}] Normal link (Symbolic link, link to a Prospero object,
|
|
or link to an external object)
|
|
\item[\lit{U}] Union link to a directory
|
|
\end{description}
|
|
|
|
The \meta{target} token is defined as follows: \label{target-token}(Also see
|
|
the discussion of this in section~\ref{target-attribute}.
|
|
A link may be a link to an object. In this case, the value of the
|
|
\meta{target} token will be the same as the value of the
|
|
object's \atr{base-type} attribute\footnote{For an explanation, see
|
|
section~\ref{base type}.}
|
|
(that is, \lit{OBJECT}, \lit{FILE},
|
|
\lit{DIRECTORY}, or \lit{DIRECTORY+FILE}.) Other values for
|
|
\meta{target} are:
|
|
\begin{description}
|
|
\item[\lit{SYMBOLIC}] Symbolic link. The \meta{host-type} token will be
|
|
\lit{VIRTUAL-SYSTEM}, the \meta{host-name} token will be the name of
|
|
the virtual system being linked to (specified as a path within the
|
|
current virtual system --- we usually use the conventional ugly-name of
|
|
the virtual system), the \meta{hsoname-type} will be \lit{ASCII},
|
|
and the \meta{hsoname} will be
|
|
the full pathname of the object being linked to within the virtual
|
|
system.
|
|
|
|
\item[\lit{EXTERNAL}] This is a link to an object which is not stored on a
|
|
host running Prospero. Unlike other types of links, \lit{EXTERNAL}
|
|
links have an \atr{access-method}%
|
|
\footnote{See
|
|
section~\ref{access-method} for a description of the
|
|
\atr{access-method} field.}
|
|
attribute which is returned as a cached attribute.
|
|
This is because \lit{EXTERNAL} links
|
|
cannot have any object attributes. Therefore, if one wishes to add
|
|
attributes to an \lit{EXTERNAL} link that would normally be object
|
|
attributes, one must specify them as \lit{CACHED}, \lit{ADDITIONAL}, or
|
|
\lit{REPLACEMENT} attributes.
|
|
\end{description}
|
|
|
|
|
|
If the principal requesting the listing has no read access to a link,
|
|
all fields in the link except for \meta{name-component} will be
|
|
returned with the token \lit{NULL}, which is not otherwise valid in a
|
|
returned link.
|
|
|
|
\subsubsection{Link Attributes\label{Link Attributes}}
|
|
|
|
If attributes were requested, the link will be followed by lines that
|
|
specify the values of the requested attributes. The form of the
|
|
response will depend on whether the attribute is associated with the
|
|
link, or with the actual object. If the attribute is associated with
|
|
the link, the \meta{applies-to} token indicates whether it applies to the
|
|
\lit{LINK} or the object, and if the object whether it is a \lit{CACHED}
|
|
attribute, a \lit{REPLACEMENT} attribute, or an \lit{ADDITIONAL} attribute. In
|
|
case of conflicts between attributes associated with the link and
|
|
those associated with the object, a cached attribute is superseded, a
|
|
replacement attribute takes precedence, and an additional attributes
|
|
leaves both intact.
|
|
|
|
Attributes may sometimes be returned even if they were not explicitly
|
|
requested. As a case of this, the \atr{ACCESS-METHOD} attribute is
|
|
always returned for \lit{EXTERNAL} links.
|
|
|
|
\begin{command}
|
|
\ors \lit{ATTRIBUTE} \meta{applies-to}
|
|
\lit{FIELD} \meta{attribute-name}
|
|
\ooms\meta{value-tuple-element}\oome%
|
|
\\
|
|
\metaor \\
|
|
\lit{ATTRIBUTE} \meta{applies-to}
|
|
\ors \lit{APPLICATION} \metaor \lit{INTRINSIC} \ore
|
|
\meta{attribute-name} \meta{attribute-value-type}
|
|
\ooms\meta{value-tuple-element}\oome \ore
|
|
\end{command}
|
|
\footnote{{\bf CHANGE IN FORMAT}: It used to be the case that the
|
|
line returned for FIELD attributes did not include an
|
|
\meta{attribute-type} token. This has been changed. The older
|
|
format will continue to work until all Prospero applications before
|
|
Alpha.5.1 are gone.
|
|
}
|
|
|
|
Attributes may have multiple values, in which case one \lit{ATTRIBUTE}
|
|
line is returned for each value. In the case of multiple values, the
|
|
order in which attributes is returned may be significant to the
|
|
application. The Prospero server will maintain the order
|
|
of attributes.
|
|
|
|
\meta{attribute-value-type}s are \lit{SEQUENCE},
|
|
\lit{LINK}, and \lit{FILTER}. \lit{SEQUENCE} is the most general
|
|
\meta{attribute-value-type}. It is a sequence of zero or more ASCII
|
|
strings, and all other attribute value types are subtypes of it.
|
|
Since application attributes are, by definition, application-specific,
|
|
we are not constraining the form of a sequence. However, if an
|
|
application wishes to use application-specific subtypes of
|
|
\lit{SEQUENCE}, we encourage application authors to use the first
|
|
element of the attribute's value as a keyword describing the particular
|
|
subtype of \lit{SEQUENCE}.
|
|
|
|
One possible \meta{attribute-value-type} is \lit{LINK}. The
|
|
\meta{value-tuple-element} tokens returned in this case are the same as
|
|
the \lit{LINK} response to the \lit{LIST} command.
|
|
In that
|
|
case, the \meta{name-component} token will be ignored, and will usually be
|
|
a zero-length string (\lit{'{}'}).) The return format would be:
|
|
|
|
\begin{command}
|
|
\lit{ATTRIBUTE} \meta{applies-to} \lit{APPLICATION} \meta{attribute-name}
|
|
\lit{LINK} \ors \lit{L} \metaor \lit{U}\ore \meta{target} \meta{name-component} \meta{host-type} \meta{host-name}
|
|
\meta{hsoname-type} \meta{hsoname} \meta{object-version}
|
|
\zoos \lit{DEST-EXP} \meta{dest-expiration} \zooe
|
|
\end{command}
|
|
|
|
|
|
If the value of an attribute is a link, the link might itself have
|
|
attributes. When such sub-attributes are returned, the word
|
|
\lit{ATTRIBUTE} is immediately followed by \lit{>} signs to the
|
|
appropriate nexting level. If a link attribute has sub-attributes,
|
|
they will all be sent with the link.
|
|
|
|
All available \lit{ID} fields will always be returned with
|
|
every \lit{LIST} operation, using the \lit{ID} return
|
|
format.\footnote{Please note again that ID fields have not been
|
|
fully implemented, in the absence of an appropriate standard; comments about them in this document are subject to
|
|
change.}
|
|
|
|
|
|
\subsubsection{Filters\label{filter}}
|
|
|
|
User-defined attributes and the field \atr{filter} may have the
|
|
\meta{attribute-value-type} of \lit{FILTER}.\footnote{
|
|
XXX: This should go into the attribute documentation
|
|
} If a link has one or more filters attached to it, they are
|
|
specified as one or more instances of the link's \atr{filter} field.
|
|
One \lit{ATTRIBUTE} line will always be returned for each
|
|
filter. The
|
|
lines are returned in the same order in which the filters will be
|
|
applied to the link. The return format is:
|
|
|
|
\begin{command}
|
|
\lit{ATTRIBUTE}\zoms\lit{>}\zome \lit{LINK FIELD FILTER} \meta{filter-type}
|
|
\meta{execution-location} \meta{pre-or-post} \\
|
|
\ors\lit{PREDEFINED} \meta{filter-name} \\
|
|
\metaor\
|
|
\lit{LINK} \lit{L} \meta{target} \meta{name-component} \meta{host-type} \meta{host-name}
|
|
\meta{hsoname-type} \meta{hsoname} \meta{object-version}
|
|
\zoos \lit{DEST-EXP} \meta{dest-expiration} \zooe \ore
|
|
\zoms\lit{ID} \meta{id} \meta{info}\zome \\
|
|
\zoos \lit{ARGS} \zoms\meta{filter-arg}\zome \zooe
|
|
\end{command}
|
|
|
|
The values for \meta{filter-type} are: \lit{DIRECTORY}, filter is
|
|
applied to the
|
|
current directory; \lit{HIERARCHY}, filter is applied to all directories
|
|
reachable through the filtered link; \lit{OBJECT} filter is applied to an
|
|
object other than a directory; \lit{UPDATE}, filter is applied when
|
|
updating the directory.
|
|
|
|
\meta{execution-location} refers to where the filter will be executed.
|
|
Filters are usually executed on the \lit{CLIENT}, but may be executed
|
|
on the \lit{SERVER}.
|
|
|
|
\meta{pre-or-post} is \lit{PRE} if the filter is to be applied before
|
|
union links are expanded and \lit{POST} if the filter is to be applied
|
|
after union links are expanded. \lit{POST} is the common case for
|
|
client filters. Server filters must be \lit{PRE} at this time, since
|
|
the server does not yet perform remote expansion of union links.
|
|
|
|
Filters may be \lit{PREDEFINED}, which means that it is expected that
|
|
the appropriate client or server will understand the predefined name, or
|
|
they may be \lit{LOADABLE}, which means that they are object
|
|
code that will be dynamically linked with the client or
|
|
server.\footnote{
|
|
The security issues with loadable filters have
|
|
not yet been fully addressed. Partly because of this, right now, all
|
|
implementations except for the VAX implementation will only support
|
|
\lit{PREDEFINED} filters, and even the VAX implementation is not
|
|
configured to support loadable filters unless you specially compile it
|
|
to do so.
|
|
}
|
|
There may also be server-specific \lit{PREDEFINED} filters
|
|
for special applications (such as Archie). Their
|
|
\meta{execution-location} will always be \lit{SERVER}.
|
|
|
|
One may specify zero or more arguments to the filter, following the
|
|
\lit{ARGS} keyword.
|
|
|
|
\subsubsection{Unresolved Components}
|
|
|
|
An \lit{UNRESOLVED} response lists the components of the name that must be
|
|
further resolved relative to the immediately preceding \lit{LINK}
|
|
response or responses, and is used when not all components of a
|
|
multiple-component name were resolved.
|
|
|
|
\begin{command}
|
|
\lit{UNRESOLVED} \meta{components}
|
|
\end{command}
|
|
|
|
The text of the \meta{components} must be a proper suffix of
|
|
multiple-component name sent across as an argument to the \lit{LIST}
|
|
command. For instance, to the command
|
|
|
|
\begin{command}
|
|
\lit{LIST '' COMPONENTS ulink-test2/murali/ROOT}
|
|
\end{command}
|
|
|
|
the only two legal \lit{UNRESOLVED} responses are
|
|
\begin{command}
|
|
\lit{UNRESOLVED} \lit{murali/ROOT}
|
|
\lit{UNRESOLVED} \lit{ROOT}
|
|
\end{command}
|
|
|
|
\subsubsection{No files found}
|
|
|
|
If no files are found, the reply will be:
|
|
|
|
\begin{command}
|
|
\lit{NONE-FOUND}
|
|
\end{command}
|
|
|
|
\section{LIST-ACL}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{LIST-ACL} \meta{options} \zoos\meta{name-component}\zooe\selectlines
|
|
\end{command}
|
|
|
|
This request is used to list the access control list for the directory
|
|
specified in the previous \lit{DIRECTORY} command, or for a link within the
|
|
directory. The optional component is required only if requesting the
|
|
\lit{ACL} for a link within the directory (option = \lit{LINK}). It is to be left
|
|
out when requesting the \lit{ACL} for the directory itself
|
|
(option = \lit{DIRECTORY}).
|
|
|
|
The response will be zero or more lines of the form:
|
|
|
|
\begin{command}
|
|
\lit{ACL} \meta{entry-type} \zoos\meta{authentication-type}
|
|
\zoos\meta{rights} \zoms\meta{principal-name}\zome\zooe\zooe
|
|
\end{command}
|
|
|
|
If no \lit{ACL} entries are listed, then the response is \lit{SUCCESS}.
|
|
Fields inappropriate to a particular \meta{entry-type} need not be
|
|
sent, but if they are sent, they should be sent as a zero-length
|
|
string. For instance, the \lit{DEFAULT}, \lit{SYSTEM}, and
|
|
\lit{DIRECTORY} ACL types do not use the \meta{authentication-type},
|
|
\meta{rights}, and \meta{principal-name} fields.
|
|
|
|
If the ACL's permissions state that it cannot be viewed (\lit{v} or
|
|
\lit{V} permission), then the
|
|
response is
|
|
\begin{command}
|
|
\lit{FAILURE} \lit{NOT-AUTHORIZED} \zoos\text{optional multi-token explanatory text.}\zooe
|
|
\end{command}
|
|
|
|
Possible values for \meta{entry-type} include \lit{NONE} (allows
|
|
access to no principals; in other words, it's a no-op), \lit{ANY}
|
|
(grants access to all
|
|
principals), \lit{OWNER} (grants access to the principal specified by
|
|
the link or object's \atr{owner} field; i.e., the one who owns the
|
|
link or object),
|
|
\lit{NAMED}, %(formerly called \lit{LGROUP}),
|
|
\lit{GROUP} (In this case, the \meta{authentication-type} token
|
|
represents the group certification method),
|
|
\lit{DIRECTORY}, \lit{DEFAULT}, \lit{SYSTEM}, \lit{AUTHENT} (means
|
|
that an
|
|
authentication method is used; the \meta{authentication-type} token
|
|
specifies the
|
|
authentication method. The only currently supported value for
|
|
\meta{authentication-type} is \lit{KERBEROS}.), \lit{ASRTHOST}, and
|
|
\lit{TRSTHOST}. An example:
|
|
\begin{command}
|
|
\tt
|
|
ACL ANY '{}' rlvY \\
|
|
ACL ASRTHOST '{}' ALRMDI prospero \\
|
|
ACL AUTHENT KERBEROS ALRMDI swa@ISI.EDU bcn@ISI.EDU \\
|
|
ACL DEFAULT '{}' '{}' \\
|
|
ACL SYSTEM '{}' '{}' \\
|
|
\end{command}
|
|
|
|
We interpret a null link ACL as the \lit{DIRECTORY} ACL.
|
|
We interpret a null directory ACL as the \lit{DEFAULT} ACL.
|
|
|
|
See the Prospero User's Manual for a discussion of the order of
|
|
evaluation of ACLs.
|
|
|
|
If we want to find out the value of a \lit{NAMED} ACL (named ACLs are
|
|
shorthand for longer lists, and are local to the server) (\lit{XXX} this
|
|
should go into the user's manual), then we use
|
|
the \lit{NAMED} option, and the
|
|
\meta{name-component} is replaced with the (possibly quoted) name
|
|
of the named ACL. Note that named ACLs are not currently supported.
|
|
|
|
If we want to find out the value of an included ACL (Currently, the
|
|
only included ACLs are \lit{SYSTEM}, \lit{DEFAULT}, and \lit{OVERRIDE}. \lit{DIRECTORY} is
|
|
also an included ACL for the purposes of the protocol, but the value
|
|
of the \lit{DIRECTORY} ACL will change from directory to directory, and
|
|
therefore it is not a server-wide stable name.) \footnote{XXX: this
|
|
information will go into the user's manual when we revise it}, then we use
|
|
the \lit{INCLUDED} option, and the
|
|
\meta{name-component} is replaced with the name
|
|
of the included ACL. Note that retrieval of included ACLs is not
|
|
currently supported.
|
|
|
|
If we want the ACL for a filesystem object (instead of for a link or
|
|
directory), then we use the \lit{OBJECT} option, and the
|
|
\meta{name-component} is replaced with \meta{hsoname-type}
|
|
\meta{hsoname} \zoos\meta{object-version}\zooe. Object ACLs are not currently implemented, because
|
|
they wouldn't do anything useful --- we currently do not have an
|
|
access method which understands Prospero ACLs.
|
|
|
|
Within the Prospero protocol, the quoting mechanism works on principal
|
|
names, and works recursively for distinguishing components of
|
|
principal names. (This is currently only used by Kerberos, but may also
|
|
be needed by other authentication mechanisms.)
|
|
|
|
See the Prospero User's manual for a further discussion of ACLs.
|
|
|
|
\section{GET-OBJECT-INFO}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{GET-OBJECT-INFO} \meta{requested-attributes}
|
|
\meta{hsoname-type} \meta{hsoname}
|
|
\meta{object-version}\selectlines
|
|
\end{command}
|
|
|
|
This command requests information about an object.
|
|
\meta{requested-attributes} is a list of those attributes
|
|
that are desired. Multiple attributes may be separated by ``\lit{+}'' signs
|
|
(with no intervening white space), just as options lists are
|
|
separated.
|
|
|
|
Special attribute names may be specified, just as they may be for the
|
|
\lit{LIST} command. The special names are: \lit{\#OBJECT} (synonymous
|
|
with \lit{\#ALL}), \lit{\#FIELD}, \lit{\#INTERESTING}, \lit{\#ALL}, and
|
|
\lit{\#APPLICATION}.
|
|
|
|
The response can be multiple lines, each containing a value for an
|
|
attribute. The response will be the same as for the \lit{ATTRIBUTE}
|
|
option to the \lit{LIST} command. However, the \meta{applies-to}
|
|
field will always be \lit{OBJECT}
|
|
|
|
An object that has migrated to another host may have its
|
|
\atr{forwarding-pointer} attribute queried with \lit{GET-OBJECT-INFO},
|
|
but attempts to retrieve any other attributes will return a
|
|
\lit{FORWARDED} message.
|
|
|
|
If no matching attributes for the object were found, the response is
|
|
\lit{NONE-FOUND}.
|
|
|
|
\section{EDIT-OBJECT-INFO}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{EDIT-OBJECT-INFO} \meta{modification-request}
|
|
\meta{hsoname-type} \meta{hsoname}
|
|
\end{command}
|
|
|
|
This command is used to change the attributes of a Prospero object.
|
|
It is followed by an arbitrary (zero or more) number of
|
|
\lit{ATTRIBUTE} specification lines. See the
|
|
\lit{LIST} command for a definition of these lines. The
|
|
\meta{applies-to} will always be \lit{OBJECT}.
|
|
|
|
In the command, one may request to add a new instance of an attribute, delete
|
|
an instance, delete all instances, or replace all instances. The
|
|
\meta{modification-request} will be \lit{ADD}, \lit{DELETE},
|
|
\lit{DELETE-ALL}, or \lit{REPLACE}. If you want to do more than one
|
|
thing to an object in
|
|
the same request (e.g., if you want to add one attribute instance and
|
|
replace another), and you want to avoid letting the object exist in an
|
|
intermediate and possibly inconsistent state, then you can send two
|
|
\lit{EDIT-OBJECT-INFO} commands in the same message, along with the
|
|
\lit{ATOMIC} command.
|
|
|
|
If you are deleting all instances of an attribute, then the
|
|
\meta{attribute-value} you specify in your \lit{ATTRIBUTE}
|
|
specification lines will be ignored, and will usually just be the null
|
|
string. \lit{DELETE-ALL} just checks for matches on the attribute
|
|
name and the attribute namespace (\lit{APPLICATION}, \lit{FIELD}, or
|
|
\lit{INTRINSIC}).
|
|
|
|
\lit{DELETE}, on the other hand, checks for an exact match on the
|
|
attribute name, namespace, type, and value. (The current
|
|
implementation does not check for sub-attributes of a value of type
|
|
link.
|
|
|
|
\lit{REPLACE} may
|
|
be specified even if the attribute does not yet have any instances
|
|
specified for it.
|
|
|
|
One may use \lit{EDIT-OBJECT-INFO} to edit the \atr{base-type}
|
|
attribute to remove the \lit{FILE} type from it only if the file is
|
|
empty (zero length), and one may remove the \lit{DIRECTORY} type from
|
|
it only if the directory is empty (contains no links).
|
|
|
|
|
|
\section{CREATE-LINK}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{CREATE-LINK} \meta{options} \ors \lit{L} \metaor \lit{U} \ore
|
|
\meta{name-component}
|
|
\meta{target} \meta{host-type} \meta{host-name} \meta{hsoname-type}
|
|
\meta{hsoname} \meta{object-version}
|
|
\zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe
|
|
\end{command}
|
|
|
|
This command creates a new link in the current directory. The
|
|
\meta{name-component} may not be null, even if the link is a union link.
|
|
If filters
|
|
or other information must be added, the \lit{EDIT-LINK-INFO} command should be
|
|
used once the link has been created.
|
|
|
|
The \meta{options} may include \lit{REPLICA} to add
|
|
a link to a directory that already contains a link with the same
|
|
\meta{name-component}. \lit{REPLICA} indicates that the new link
|
|
and the existing link or links with which it conflicts are replicas.
|
|
Normally, if one attempts to add a link with a conflicting
|
|
\meta{name-component}, the response is:
|
|
\begin{command}
|
|
\lit{FAILURE ALREADY-EXISTS}
|
|
\end{command}
|
|
if the new link duplicates an existing link (if all of the arguments
|
|
to it are the same as those of an existing link), and
|
|
\begin{command}
|
|
\lit{FAILURE NAME-CONFLICT}
|
|
\end{command}
|
|
if the new link has information which conflicts with an existing link.
|
|
|
|
If \lit{CONFLICT} is among the options, then conflicting links will be
|
|
inserted into the directory anyway.
|
|
|
|
For directories whose \atr{directory-ordering} is \lit{UNSORTED},
|
|
one of these three additional options may be specified:
|
|
\begin{description}
|
|
\item[\lit{BEFORE}] The \lit{CREATE-LINK} command is immediately
|
|
followed by a \lit{LINK} line, describing the link before which the
|
|
new link is to be inserted in the directory listing.
|
|
\item[\lit{AFTER}] Same as above, but the new link is inserted after the
|
|
specified link rather than before it.
|
|
\item[\lit{LAST}] This is the default. The new link will be the last
|
|
item in the directory.
|
|
\end{description}
|
|
|
|
\section{DELETE-LINK}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{DELETE-LINK} \meta{options} \meta{name-component} \selectlines
|
|
\end{command}
|
|
|
|
This command is used to remove an entry from a directory. The options
|
|
are currently blank.
|
|
|
|
If the \lit{SELECT} lines are not specified and there are multiple
|
|
links with the same \meta{name-component}, the first one matching will
|
|
be deleted.
|
|
|
|
\section{EDIT-LINK-INFO}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{EDIT-LINK-INFO} \meta{modification-request} \meta{name-component}
|
|
\zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe
|
|
\end{command}
|
|
|
|
\begin{sloppypar}
|
|
This command modifies information associated with a link.
|
|
The interpretation of the %\ \linebreak[3]
|
|
\meta{modification-request} and of
|
|
subsequent lines is exactly the same as in the \lit{EDIT-OBJECT-INFO} command.
|
|
\end{sloppypar}
|
|
|
|
%\vspace{-.1in}
|
|
|
|
\section{EDIT-ACL}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{EDIT-ACL}
|
|
\ors \lit{LINK+}\meta{options} \meta{name-component} \\
|
|
\hspace{.6in} \metaor \lit{OBJECT+}\meta{options}
|
|
\meta{hsoname-type} \meta{hsoname} \\
|
|
\hspace{.6in} \metaor \lit{DIRECTORY+}\meta{options}
|
|
\ore \\
|
|
\zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe \meta{LF} \\
|
|
\lit{ACL} \meta{entry-type} \meta{authentication-type} \meta{rights}
|
|
\meta{principal}
|
|
\end{command}
|
|
|
|
This command is used to modify an access control list for a directory,
|
|
for a link within a directory, or for an object. If modifying the ACL
|
|
for a directory or for a link within a directory, the directory is
|
|
specified in the previous \lit{DIRECTORY} command.
|
|
Another option indicates the operations to be
|
|
performed (one of \lit{ADD}, \lit{SUBTRACT}, \lit{INSERT}, \lit{DELETE}, \lit{SET} or \lit{DEFAULT}), and
|
|
whether to override the automatic inclusion of the system
|
|
ACL (\lit{NOSYSTEM}), or limited administer access for the client
|
|
(\lit{NOSELF}).
|
|
|
|
The server will return \lit{SUCCESS}, \lit{FAILURE}, or
|
|
\lit{FORWARDED}, as appropriate.
|
|
|
|
\section{CREATE-OBJECT}
|
|
|
|
\begin{command}
|
|
\commandsize \ors\lit{CREATE-OBJECT} \lit{PHYSICAL+}\meta{options}
|
|
\zoos\meta{hsoname-type} \meta{hsoname}\zooe \\
|
|
\metaor \lit{CREATE-OBJECT} \lit{ADD+}\meta{options}
|
|
\zoos\meta{hsoname-type} \meta{hsoname}\zooe \\
|
|
\metaor \lit{CREATE-OBJECT} \lit{VIRTUAL+}\meta{options}
|
|
\meta{name-component}\ore \meta{LF} \\
|
|
\zoms\lit{ATTRIBUTE}
|
|
\meta{attribute-specifying-tokens}\meta{LF}\zome \\
|
|
\zoms\lit{ACL} \meta{ACL-specifying-tokens}\meta{LF}\zome
|
|
\end{command}
|
|
|
|
This command will create an object with the specified
|
|
\meta{name-component} and will
|
|
return the identifier that can be used to open it. The
|
|
\meta{options} may include any or all of
|
|
\lit{DIRECTORY}, \lit{FILE}, and \lit{OBJECT}.
|
|
If the \lit{FILE} option is specified, the new file is
|
|
created empty. If the \lit{DIRECTORY} option is specified, the
|
|
new directory is created empty (i.e., not containing any links.).
|
|
|
|
The object will be created with whatever attributes present that are
|
|
specified in the \lit{ATTRIBUTE} lines.
|
|
|
|
If \meta{options} includes \lit{VIRTUAL}, then
|
|
\meta{name-component} is a name relative to the current directory, and a
|
|
link to the new object is added to the current directory.
|
|
|
|
If the \lit{ADD} option is specified, then one is adding a base type to
|
|
an already created object. Exactly one of the \lit{ADD},
|
|
\lit{VIRTUAL}, and \lit{PHYSICAL} options must be specified.
|
|
|
|
\begin{sloppypar}
|
|
If the \lit{PHYSICAL} option and a \meta{hsoname-type}
|
|
\meta{hsoname} pair are specified, then the server will attempt to create an object with that
|
|
\meta{hsoname-type} \meta{handle-pair}. If the \lit{PHYSICAL} option
|
|
without a following pair is
|
|
specified
|
|
then the server will choose a free \meta{hsoname-type}
|
|
\meta{hsoname} pair.
|
|
\end{sloppypar}
|
|
|
|
Upon success, the server will return:
|
|
\begin{command}
|
|
\lit{CREATED} \meta{hsoname-type} \meta{hsoname}
|
|
\end{command}
|
|
It is up to the application to create a link to the new object.
|
|
|
|
\subsection{Specifying Attributes}
|
|
|
|
The new object's fields will be set to system defaults, but
|
|
specifying a following series of \lit{ATTRIBUTE} descriptions allows
|
|
the creator of a file to override those defaults, and to specify any
|
|
application-defined attributes. The form for each \lit{ATTRIBUTE} line is
|
|
the same as that returned by the
|
|
\lit{LIST} command.
|
|
|
|
\subsection{ACLs}
|
|
|
|
If creating an object with the \lit{VIRTUAL} option, the access
|
|
control list for the new object will initially be a copy of the access control
|
|
list for its containing directory. If creating an object with the
|
|
\lit{PHYSICAL} option, the access control list for the new object will
|
|
contain the \lit{DEFAULT} ACL and the \lit{SYSTEM} ACL.
|
|
In addition,
|
|
for both options, one or more entries will be automatically added to the ACL
|
|
granting its creator all rights. The entry authentication type or types
|
|
will be appropriate for whatever the user used to authenticate himself
|
|
or herself. (Either \lit{AUTHENT} \lit{KERBEROS} or \lit{ASRTHOST} or
|
|
\lit{TRSTHOST}.)
|
|
|
|
If the \lit{LPRIV} option is
|
|
specified for a directory, instead of this entry, only those rights needed to
|
|
allow the creator to set up the directory (list, read, insert, and
|
|
administer) will be added, and (if \lit{VIRTUAL} was specified), only
|
|
if the creator does not already have such rights through the ACL that
|
|
was included from the parent directory.\footnote{If you really want to shoot yourself in the foot, you can
|
|
then call \lit{EDIT-ACL} to remove these few rights. We will let you
|
|
do this, but we are not making it easy for you.}
|
|
|
|
If \lit{VIRTUAL} was specified, the ACL for the new link will
|
|
by default be empty, which means that the default rights for the
|
|
directory will apply to the link.
|
|
|
|
After the ACL entries mentioned above are installed, the ACL
|
|
entries specified as part of the \lit{CREATE-OBJECT} command will
|
|
be added to the front of the list.
|
|
|
|
\subsection{Some Error Conditions}
|
|
|
|
If the user attempted to set a
|
|
field whose name the server does not recognize, or to set a
|
|
application-defined attribute to a type that the server does not recognize,
|
|
or to set the value of any attribute with a string that the server
|
|
cannot convert into the data type the server expects (e.g., too few
|
|
tokens when setting an attribute of type \lit{LINK}), or to set an
|
|
unrecognized ACL type,
|
|
the response is:
|
|
\begin{command}
|
|
\lit{ERROR} \text{explanatory text}
|
|
\end{command}
|
|
If the user specified an explicit \meta{hsoname-type} and
|
|
\meta{hsoname} with the \lit{PHYSICAL} option, but they were
|
|
already in use, or if the user specified a component with
|
|
\lit{VIRTUAL}, but the component is already in use, the error message is:
|
|
\begin{command}
|
|
\lit{FAILURE} \lit{NAME-CONFLICT} \zoos\text{explanatory text}\zooe
|
|
\end{command}
|
|
|
|
|
|
\subsection{No \protect\lit{DELETE-OBJECT} command}
|
|
|
|
Although there is a \lit{DELETE-LINK} command, there is {\em no \/}
|
|
\lit{DELETE-OBJECT} command. That's because Prospero objects will have
|
|
their storage reclaimed when their TTL expires (when no link to them
|
|
is refreshed before their expiration date). At the moment, this
|
|
storage reclamation feature is not implemented.) \footnote{XXX: This
|
|
feature must be specified. In addition, we must specify methods for
|
|
refreshing links, garbage collection, and notification of the
|
|
impending demise of objects.}
|
|
|
|
\section{UPDATE}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\lit{UPDATE} \meta{options} \lit{COMPONENTS} \zoms\meta{name-component}\zome
|
|
\end{command}
|
|
|
|
This command tells the server to check each of the named components in
|
|
the current directory for forwarding pointers. If the referenced
|
|
object has moved, the link will be updated. The server will send
|
|
Prospero protocol messages across the network to the targets of links
|
|
to Prospero objects in order to check whether the target of a link has
|
|
moved. (External links and symbolic links will not be checked.) If
|
|
no components were specified, all components in the
|
|
directory will be checked. Each \meta{name-component} may contain
|
|
wild cards.
|
|
|
|
On success, the \lit{UPDATE} command returns the
|
|
number of links that were modified.
|
|
|
|
\begin{command}
|
|
\lit{UPDATED} \meta{number} \lit{LINKS}
|
|
\end{command}
|
|
|
|
On failure, the \lit{UPDATE} command returns the number of links it
|
|
was unable to update.\footnote{
|
|
This error message may change in response to future needs.}
|
|
|
|
\begin{command}
|
|
\lit{FAILED TO UPDATE} \meta{number} \lit{LINKS}
|
|
\end{command}
|
|
Wildcards
|
|
|
|
\section{STATUS}
|
|
|
|
This command requests the current status of the server. A humanly
|
|
readable multiple line response is returned. The response may be
|
|
presented to the user without additional processing. The response
|
|
must conform to the following requirements so that it may be read by a
|
|
program if desired.
|
|
|
|
The first line must include the server's software version
|
|
identification enclosed in parenthesis, and the host name of the
|
|
server. The name of the host should be the name that appears on local
|
|
links generated by the server; it might not be the primary name of the
|
|
host. The version identifier must be the first string that appears in
|
|
parenthesis, and the host name must be the string that immediately
|
|
follows the version identifier.
|
|
|
|
If a line contains a colon (:), the string preceding the colon
|
|
identifies the meaning of the text that follows the colon. Reserved
|
|
identifiers include \lit{Contact}, \lit{Started}, \lit{Memory},
|
|
\lit{Data}, \lit{Root}, \lit{AFTP}, \lit{AFS}, and \lit{DB}. The
|
|
identifiers are case insensitive. If present, \lit{AFTP}
|
|
identifies the part of the file system accessible by anonymous \lit{FTP}.
|
|
|
|
More than one \lit{DB} line may be present. A \lit{DB} line may
|
|
contain more than
|
|
one item on it; if it does, the items must be separated by spaces.
|
|
Each item on a \lit{DB} line is an initial prefix which this particular
|
|
server recognizes to mean that, if this server receives a system-level
|
|
name with this prefix followed by a slash, the remaining contents of
|
|
the line are fed to a database program which translates it into a
|
|
reference to a virtual directory.
|
|
|
|
Other than for the first line of the response, implementations are
|
|
free to add or modify lines that do not contain a colons. A sample
|
|
status response follows:
|
|
|
|
\begin{verbatim}
|
|
Prospero server (Beta.4.2B) JUNE.CS.WASHINGTON.EDU
|
|
Requests since startup 4096 (3609+377+2 67+29+0 9 0+0+0 0 3) OF
|
|
Started: 26-Aug-91 15:14:56 UTC
|
|
Contact: bcn@cs.washington.edu
|
|
Memory: 0(118)vl 0(4)at 0(5)acl 0(1)fi 1(1)pr 2(2)pt 0(711)str
|
|
Data: /u1/vfs/pfsdat
|
|
Root: /
|
|
DB: ARCHIE GOPHER(70) GOPHERGW WAIS
|
|
AFTP: /homes/june/ftp
|
|
\end{verbatim}
|
|
|
|
Since the responses to this command are so free in form, it is
|
|
unlikely you would want to send additional requests to the Prospero
|
|
server along with the \lit{STATUS} request, since it would not be easy for a
|
|
program to separate the replies to them from the free-form text.
|
|
|
|
\chapter{Standard Responses}
|
|
|
|
\section{SUCCESS}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\protect\lit{SUCCESS} \zoos\protect\text{identifying-info}\zooe
|
|
\end{command}
|
|
|
|
A command that does not generate any output returns this response if
|
|
successful.
|
|
|
|
\section{FORWARDED}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\protect\lit{FORWARDED} \protect\meta{host-type} \protect\meta{host-name}
|
|
\protect\meta{hsoname-type} \protect\meta{hsoname}
|
|
\protect\meta{version} [ \lit{DEST-EXP} \meta{dest-expiration} ] \\
|
|
\protect\zoms \protect\lit{ID} \protect\meta{id-type} \protect\meta{id-value}\protect\zome
|
|
\end{command}
|
|
|
|
This response is returned when the object that is the target of an
|
|
operation has moved. The client can retry the response using the
|
|
corrected information.
|
|
|
|
\section{ERROR}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\protect\lit{ERROR} \protect\text{text}
|
|
\end{command}
|
|
|
|
This response is returned to indicate an error encountered when
|
|
parsing the request. The error might be a protocol error, or it might
|
|
be the result of the server's inability to recognize a keyword or data
|
|
type. \text{text} describes the error.
|
|
|
|
\section{FAILURE}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\protect\lit{FAILURE} \protect\meta{identifying-info}
|
|
\zoos\protect\text{optional text} \zooe
|
|
\end{command}
|
|
|
|
This response is returned when an operation can not be performed. The
|
|
defined values for \meta{identifying-info} appear below.
|
|
If present, the \text{optional text} provides additional information
|
|
about the failure.
|
|
|
|
\begin{command}
|
|
\lit{NOT-FOUND} \ors\lit{FILE} \metaor \lit{ACL} \metaor
|
|
\lit{OBJECT} \metaor \lit{FILTER} \metaor \lit{PARAMETER} \metaor
|
|
\lit{ATTRIBUTE} \ore \\
|
|
\lit{ALREADY-EXISTS} \\
|
|
\lit{NAME-CONFLICT} \\
|
|
\lit{AUTHENTICATION-REQUIRED} \\
|
|
\lit{NOT-A-DIRECTORY} \\
|
|
\lit{NOT-AUTHORIZED} \\
|
|
\lit{AUTHENTICATION-DATA} \\
|
|
\lit{SERVER-FAILED}\footnote{This is used in the following
|
|
situations, among others: if
|
|
an internal table in the server fills up, or if the server cannot
|
|
allocate enough memory to handle the request, or if the server detects
|
|
an internal inconsistency in its database, or if the server
|
|
has not implemented a command specified in the protocol.}\\
|
|
\lit{AMBIGUOUS} \\
|
|
\lit{BAD-VALUE} \\
|
|
\lit{FILTER-APPLICATION} \\
|
|
\end{command}
|
|
|
|
\section{WARNING}
|
|
|
|
\begin{command}
|
|
\commandsize
|
|
\protect\lit{WARNING} \protect\meta{identifying-info}
|
|
\zoos\protect\text{optional text}\zooe
|
|
\end{command}
|
|
|
|
This response is returned to indicate a warning condition which does
|
|
not affect the correctness of the response. This message can be used
|
|
to indicate that the client is using an old version of the protocol
|
|
that, while supported, should be phased out. It can also be used to
|
|
inform the client of future changes on the server or scheduled
|
|
downtime. The defined values for \meta{identifying-info} appear
|
|
below. \text{optional text} is optional text that provides additional
|
|
information about the warning.
|
|
|
|
\begin{command}
|
|
\lit{OUT-OF-DATE} \\
|
|
\lit{MESSAGE} \\
|
|
{\em Any \meta{identifying-info} that can follow a \lit{FAILURE} message}
|
|
\end{command}
|
|
Prospero clients are strongly encouraged to present warnings to the user.
|
|
|
|
|
|
\appendix
|
|
|
|
\chapter{Directory, Link, and Object Attributes\label{db}}
|
|
|
|
This appendix describes the object and directory information
|
|
maintained by the Prospero file system.
|
|
|
|
{\bf \large Please note that this appendix is in very rough
|
|
form. Many of the attribute definitions have not yet been properly
|
|
written. A lot of the attribute documentation can be found in
|
|
section~\ref{Link Attributes} of this document.}
|
|
|
|
Attributes have three namespaces
|
|
associated with them: \lit{APPLICATION} attributes, \lit{INTRINSIC}
|
|
attributes, and \lit{FIELD}s.
|
|
Attributes in the \lit{FIELD} namespace have a registered meaning, and
|
|
are understood by all clients and servers that use them.
|
|
\lit{APPICATION} attributes are defined by users and application
|
|
programs and are unrestricted. Intrinsic attributes have special
|
|
registered meanings, providing prossibly transient or derived
|
|
information. The server has flexibility about whether it allows you
|
|
to change these things. Modifying them may have special implications
|
|
--- for instance, setting the \atr{SIZE} of a file to
|
|
``\lit{0 bytes}'' will truncate the file. \lit{INTRINSIC} attributes
|
|
gare either not modifiable, or else the server uses special mechanisms
|
|
to modify them.
|
|
|
|
In addition, there is a fourth namespace used internally by routines
|
|
running on the Prospero server. \lit{INTERNAL} attributes are never
|
|
sent across the network; they cannot be read with GET-OBJECT-INFO or
|
|
LIST and cannot be modified with EDIT-OBJECT-INFO. However, they do
|
|
appear in the server's data files.
|
|
|
|
\section{Objects}
|
|
|
|
\subsection{Attributes\label{access-method}}
|
|
|
|
Valid attributes include {\sc access-method,
|
|
closure, description, forwarding-pointer, keywords, last-referenced,
|
|
last-writer, locks, owner, replicas, size, storage-location, ttl,
|
|
ttl-expires. version-number, virt-sys, well-known-names,} and {\sc
|
|
write-date}.
|
|
|
|
Prospero maintains the following system defined attributes for each
|
|
Prospero object:
|
|
|
|
\begin{description}
|
|
\item[\atr{base-type}] See section~\ref{base type} for a description of
|
|
this attribute.
|
|
|
|
\footnotetext{
|
|
{\bf RATIONALE}: Under the version 1 protocol, the means of obtaining the
|
|
access method information for \lit{EXTERNAL} and \lit{FILE} links was
|
|
different; this made the code more complicated than it needed to be.
|
|
|
|
The reader may well ask why the host should be specified in
|
|
the value of the \atr{access-method} field. Isn't the host name
|
|
already specified in the \atr{host} field? Including the host
|
|
name as part of the attribute's value has some advantages:
|
|
\begin{itemize}
|
|
\item The value of the \atr{access-method} field is all one needs in
|
|
order to retrieve the file.
|
|
|
|
|
|
\item One might have a Prospero server running on only one host in a
|
|
cluster, where the objects themselves are actually stored on another
|
|
fileserver. Then, one would want to be able to have the
|
|
\atr{access-method} host be different from the host which is listed
|
|
as the one having the final word on the status of the object.
|
|
|
|
\item This system also allows us to have a gateway server, which is able to
|
|
translate directory formats from other distributed file systems (e.g.,
|
|
gopher), but directs the client to retrieve the files themselves from
|
|
a host that is not the gateway server.
|
|
|
|
\end{itemize}
|
|
}
|
|
|
|
\item[\atr{access-method}\footnotemark]
|
|
|
|
This is a tuple of at least 5 elements. The first element is the name
|
|
of the access method. Currently supported values are \lit{AFTP}, \lit{GOPHER},
|
|
\lit{AFS}, \lit{NFS}, \lit{FTP}, \lit{WAIS}, and \lit{LOCAL}.
|
|
The next 2 elements are the \meta{host-type} and \meta{host-name} of
|
|
the host to which the access method should connect in order to
|
|
retrieve the object. A port number may be included as part of the
|
|
hostname, if relevant. If they are zero-length tokens (\lit{'{}'}), then
|
|
they default to the \meta{host-type} and \meta{host-name} specified in
|
|
the link. The next 2 elements are the \meta{hsoname-type} and
|
|
\meta{hsoname} which the access method will use to retrieve the
|
|
object. If they are zero-length tokens, then they default to the
|
|
\meta{hsoname-type} and \meta{hsoname} specified in the link.
|
|
This constraint on format applies to all access methods. If a
|
|
particular type of access method doesn't need one of these fields,
|
|
then it still must be specified, but the access method is free to ignore it. The whole
|
|
point of the \lit{'{}'} shorthand is merely to save bytes in the
|
|
protocol messages. It is always appropriate to send them fully
|
|
expanded, and not use the \lit{'{}'} shorthand.
|
|
|
|
The sixth and subsequent elements are dependent upon the particular
|
|
access method. For \lit{AFTP} and \lit{FTP}, the sixth element will be
|
|
\lit{BINARY} or \lit{TEXT}. For \lit{NFS}, the sixth
|
|
element will be the name of the filesystem on the remote host.
|
|
\lit{LOCAL}, and \lit{AFS} have only five-element names.
|
|
|
|
The \lit{GOPHER} access method may have five or six elements in the
|
|
name. The actual protocol used to retrieve a document or object
|
|
through Gopher varies depending on its Gopher item-type. (See
|
|
Internet RFC 1436 for details on the interpretation of the Gopher
|
|
item-type characters.). This item type is usually the 1st character
|
|
of a Gopher document or object's selector string (the \meta{hsoname}
|
|
element of the access method). However, the protocol does not require
|
|
that this be the case. If a sixth token is present in a \lit{GOPHER}
|
|
access method, it will be treated as the Gopher item-type character;
|
|
otherwise, the item-type will be taken from the 1st character of the
|
|
\meta{hsoname} element.
|
|
|
|
|
|
|
|
Some examples:
|
|
|
|
\begin{command}
|
|
\tt \sloppy ATTRIBUTE FIELD ACCESS-METHOD GOPHER
|
|
%\linebreak[2]
|
|
INTERNET-D~MERMAID.MICRO.UMN.EDU(150)
|
|
ASCII~\mbox{'1/Fun Stuff/Pyrotechnics/PyroGuide\ 1'}%
|
|
\footnote{This file recently
|
|
disappeared from the server. If you have a copy, please send it to
|
|
\verb"swa@isi.edu".}
|
|
|
|
{\rm \par This access method could also be displayed in the six-token
|
|
format as:}
|
|
|
|
\tt \sloppy ATTRIBUTE FIELD ACCESS-METHOD GOPHER
|
|
%\linebreak[2]
|
|
INTERNET-D~MERMAID.MICRO.UMN.EDU(150)
|
|
ASCII~\mbox{'1/Fun Stuff/Pyrotechnics/PyroGuide\ 1'}~1%
|
|
\footnote{This file recently
|
|
disappeared from the server. If you have a copy, please send it to
|
|
\verb"swa@isi.edu".}
|
|
|
|
{\rm \par Andrew File System names are the same irrespective of what host
|
|
one is using them from. Therefore, the \meta{host-name} token in the
|
|
access method is irrelevant and is ignored by the client.}
|
|
|
|
ATTRIBUTE FIELD ACCESS-METHOD AFS DUMMY DUMMY
|
|
ASCII~\mbox{/grand.central.org/doc/afs/dce/usenix90/README}
|
|
|
|
{\rm \par This file can be retrieved by NFS mounting the {\tt /auto/gum/gum}
|
|
filesystem on the host PROSPERO.ISI.EDU. Note that the server is
|
|
responsible for knowing which client machines it will allow to NFS
|
|
mount that filesystem.}
|
|
|
|
ATTRIBUTE FIELD ACCESS-METHOD NFS INTERNET-D~PROSPERO.ISI.EDU
|
|
ASCII~\mbox{ftp/pub/prospero/README-prospero-documents}
|
|
\mbox{/auto/gum/gum}
|
|
|
|
{\rm \par \meta{hsoname} tokens in the \lit{FTP} access method are full
|
|
local hostname paths that one would give when using full FTP to the host.}
|
|
|
|
ATTRIBUTE FIELD ACCESS-METHOD FTP INTERNET-D~PROSPERO.ISI.EDU
|
|
ASCII~\mbox{/ftp/pub/prospero/README-prospero-documents} TEXT
|
|
|
|
{\rm \par \meta{hsoname} tokens in the \lit{AFTP} access method are
|
|
pathnames relative to the root of the anonymous FTP area.}
|
|
|
|
ATTRIBUTE FIELD ACCESS-METHOD AFTP INTERNET-D~PROSPERO.ISI.EDU
|
|
ASCII~\mbox{/pub/prospero/README-prospero-documents} TEXT
|
|
|
|
{\rm If one is querying from a host which has a file accessible via
|
|
the local filesystem, and if the server has knowledge of this fact, a
|
|
\lit{LOCAL} access method will also be returned for a file. For the
|
|
\lit{LOCAL} access method, the \meta{host-name} token in the access
|
|
method is ignored.}
|
|
|
|
ATTRIBUTE FIELD ACCESS-METHOD LOCAL '' ''
|
|
ASCII~\mbox{/auto/gum/gum/ftp/pub/prospero/README-prospero-documents}
|
|
|
|
\end{command}
|
|
|
|
|
|
\item[\atr{closure}] The \meta{attribute-type} of thie attribute is
|
|
\lit{LINK}. It is a link to the virtual system to be
|
|
used when resolving names embedded in the object. The link's
|
|
\meta{name-component} will be ignored, but by convention it is the
|
|
ugly-name of the virtual system.
|
|
|
|
\item[\atr{owning-virtual-system}] The \meta{attribute-type} of this
|
|
attribute is \lit{LINK}. It is a link to the description of the
|
|
virtual system which is considered to own the object. (Every virtual
|
|
system, by convention, has a link to its description named
|
|
\lit{/VS-DESCRIPTION}. For directories, if you are logged into
|
|
the directory's \atr{owning-virtual-system}, then if you try to change
|
|
the directory, your client will assume that you really want to try to
|
|
change the directory. If you are logged into a different virtual
|
|
system from the directory's \atr{owning-virtual-system}, then if you
|
|
try to change the directory, your client will assume that you really
|
|
want to customize your own virtual system, but not affect the master
|
|
directory. Your intentions are completely distinct from whether you
|
|
actually have write permission on the directory. If you try to change
|
|
a directory that you can't write to (if its \atr{owning-virtual-system} is
|
|
the same as the virtual system you're logged into, but you don't have
|
|
permission to write to it), then the current clients will all give you
|
|
a ``permission denied'' error message, and the nice ones will suggest
|
|
that you might want to change virtual systems and customize instead.
|
|
The link's \meta{name-component} will be ignored, but by convention it is the
|
|
ugly-name of the virtual system.
|
|
|
|
\item[\atr{version-number}] The \meta{attribute-type} of this
|
|
attribute is \lit{SEQUENCE}. It is represented in the protocol as a
|
|
decimal number. It is currently always zero; see section~\ref{object
|
|
version numbers} for further details.
|
|
|
|
\item[\atr{owner}] The principal responsible for the object. The
|
|
\meta{attribute-type} of this attribute is \lit{SEQUENCE}. It is a tuple
|
|
of three or more elements. The first element is an ACL
|
|
\meta{entry-type} and the second element is an ACL
|
|
\meta{authentication-type}. The third and subsequent elements are
|
|
\meta{principal-name}s. The first two elements are needed because
|
|
they indicate the namespace in which the \meta{principal-name}s are to
|
|
be resolved. There may be multiple instances of the \atr{owner}
|
|
field, if the owner wants to be registered according to several
|
|
authentication systems. For instance, one of the authors of this
|
|
document uses an \atr{owner} field that looks like this:
|
|
\begin{command}
|
|
\lit{ATTRIBUTE FIELD OWNER ASRTHOST '' swa@128.9.*.*} \\
|
|
\lit{ATTRIBUTE FIELD OWNER AUTHENT KERBEROS swa@ISI.EDU swa/padmin@ISI.EDU} \\
|
|
\end{command}
|
|
Although the \atr{owner} field may be referred to with the \lit{OWNER}
|
|
ACL type, we don't really encourage people to use it as a shorthand
|
|
for granting access rights. Its primary purpose is informational.
|
|
|
|
\item[\atr{forwarding-pointer}] This attribute has type \lit{LINK}.
|
|
The link's \meta{target} is \lit{FP}. It is set for objects that
|
|
have migrated to another host. The target of its value is the new
|
|
location of the object. If an object has moved to a new host,
|
|
its \atr{forwarding-pointer} will be returned in a \lit{FORWARD}
|
|
protocol message in response to any attempts to access it.
|
|
|
|
\item[Last writer, write date, etc.]
|
|
|
|
\item[Version info] (optional). Number of versions to keep,
|
|
version number, etc.
|
|
|
|
\item[Attributes or keywords] (optional). User specified.
|
|
|
|
\item[Short description] (optional).
|
|
|
|
\item[Locks] (optional).
|
|
|
|
\item[List of replicas] (optional).
|
|
|
|
\item[Replication type] (optional).
|
|
|
|
\item[Other replication information] (optional).
|
|
|
|
\item[Time to live]. The lifetime for newly created or refreshed
|
|
links to the object.
|
|
|
|
\item[\atr{ttl-expires}] This is the \atr{ttl} plus the
|
|
time that a link to the object was last created or refreshed.
|
|
|
|
\item[Back links]. A possibly incomplete list of directories
|
|
with links to the object.
|
|
\end{description}
|
|
|
|
Note that the object's name is not one of its attributes. The
|
|
object's name is the concatenation of the name components starting from the
|
|
active virtual system. An object may have different names in
|
|
different virtual systems, or even multiple names within a single
|
|
virtual system\footnote{Despite this, well known names from agreed
|
|
upon starting points might be entered as application-defined attributes for
|
|
objects.}.
|
|
|
|
\subsection{Objects stored on \unix}
|
|
|
|
Objects stored on \unix\ servers have the following attributes defined
|
|
for them. These are all \lit{INTRINSIC}:
|
|
|
|
\begin{description}
|
|
|
|
\item[\atr{size}] A single-element \lit{SEQUENCE} specifying the
|
|
number of bytes used to store the object. Its format is
|
|
``\meta{number} \lit{bytes}''. Note the embedded space.
|
|
|
|
\item[\atr{native-owner}] A single-element \lit{SEQUENCE}. The
|
|
\unix\ username on the server of the user who owns this file.
|
|
|
|
\item[\atr{native-owner}] A single-element \lit{SEQUENCE}. The
|
|
\unix\ group name on the server of the group associated with this
|
|
file.
|
|
|
|
\item[\atr{last-modified}] A single-element \lit{SEQUENCE}. The
|
|
ASN-TIME representation of the last modified time of this object.
|
|
|
|
\item[\atr{unix-modes}] A single element \lit{SEQUENCE} consisting of
|
|
a ten character string. The first character is ``\lit{l}'' for
|
|
symbolic links, and ``\lit{-}'' otherwise. The remaining 9 characters
|
|
are the user, group, and other protection bits in the standard format
|
|
returned by ``\lit{ls -l}''.
|
|
|
|
\end{description}
|
|
|
|
\subsection{Persistence}
|
|
|
|
An object continues to exist until the last non-expired link
|
|
referencing the object is removed. If a user wishes to recover the
|
|
storage space for an object, it is flagged for removal. When links to
|
|
the object are refreshed, notification is sent that the object is
|
|
about to disappear, and anyone wanting to maintain their reference
|
|
must copy the object elsewhere. Subsequent users have the option of
|
|
making their own copy, or updating their link to refer to one of the
|
|
new copies.
|
|
|
|
\subsection{Mobility}
|
|
|
|
Objects may move from one site to another. If they do, a forwarding
|
|
pointer must remain at the old location until the time-to-live
|
|
expires. This enables anyone with a non-expired link to the object to
|
|
refresh the link and record the object's new location.\footnote{To
|
|
place a forwarding pointer, set the old object's
|
|
\atr{FORWARDING-POINTER} atribute. It must be manually moved to the
|
|
new server at this time.}
|
|
|
|
\section{Directories}
|
|
|
|
A directory is an object and as such, everything that applies to
|
|
objects also applies to directories. The physical representation of
|
|
a directory is interpreted by the Prospero server on the system
|
|
storing the directory. The Prospero protocol defines the interface
|
|
through which a directory is accessed.
|
|
|
|
\subsection{Directory Attributes}
|
|
|
|
The following attributes are defined for directories:
|
|
|
|
\begin{description}
|
|
\item[\atr{directory-ordering} (not yet implemented)] This attribute
|
|
is a 3-tuple. The
|
|
default value is
|
|
\begin{command}
|
|
\lit{SORTED NAME-COMPONENT INCREASING}
|
|
\end{command}
|
|
which means that, by default, directory entries are sorted in increasing
|
|
order according to the value of their \atr{name-component}
|
|
attribute.
|
|
|
|
The first element of the tuple is \lit{SORTED} or \lit{UNSORTED}. If
|
|
\lit{UNSORTED}, the next two elements must be null. If \lit{SORTED},
|
|
the second field specifies an attribute which is the sort key. The
|
|
third element is either \lit{INCREASING} or \lit{DECREASING}, meaning
|
|
the order of sorting.%
|
|
\footnote{In the current implmentation, the only sort keys
|
|
that may be specified must have an \meta{attribute-type} of
|
|
\lit{ASCII}.}
|
|
|
|
If the \atr{include-native} attribute is set to any value other than
|
|
\lit{NONATIVE}, then the \atr{directory-ordering} cannot be
|
|
\lit{UNSORTED}.
|
|
|
|
|
|
|
|
\item[\atr{include-native} (not yet implemented)] Whether to include
|
|
information from the native filesystem in the directory. If files are
|
|
included, they will be included from the real directory on the server
|
|
with the same \meta{hsoname} as the Prospero directory. Its
|
|
\meta{attribute-type} is a single-element \lit{SEQUENCE}.
|
|
Values are:
|
|
\begin{description}
|
|
\item[\lit{NONATIVE}] Do not include files from native directory.
|
|
\item[\lit{INCLNATIVE}] Include all files from native directory.
|
|
\item[\lit{INCLREAL}] Smae as above, but (for the \unix\ server) do not
|
|
include ``\lit{.}'' and ``\lit{..}''.
|
|
\item[\lit{NATIVEONLY}] All entries in directory are from native dir;
|
|
no links have been added. For the \unix\ server, ``\lit{.}'' and
|
|
``\lit{..}'' are NOT included.
|
|
\item[\lit{PSEUDO}] Directory is not real. This is set for all
|
|
directories returned from filters and by Archie and Gopher.
|
|
\end{description}
|
|
|
|
\end{description}
|
|
|
|
\subsection{Link Attributes\label{target-attribute}}
|
|
|
|
Prospero directories contain links to the objects that are included in
|
|
the directory. The following information is maintained for each link.
|
|
|
|
\begin{description}
|
|
|
|
\item[\atr{name-component}] This is the single component of the
|
|
object's path relative to the current directory. Its
|
|
\meta{attribute-type} is \lit{SEQUENCE}.
|
|
|
|
\item[Short description of link] (Optional).
|
|
|
|
\item[\atr{link-type}]. The type of a link can be either
|
|
normal [L] or union [U]. In the case of a normal link, an entry for
|
|
the link is visible when the directory is listed. In the case of a
|
|
union link, which can only be made to another directory, the links
|
|
from the target directory appear as part of the directory from which
|
|
the union link originates when the originating directory is listed.
|
|
If multiple objects have the same name, the order in which the union
|
|
links appear determines which object is visible.
|
|
|
|
Two types of links which may appear locally (either in the server, or
|
|
on the client) are [-] deleted, and [N] native. It is not legal for
|
|
these codes to be sent across the network. Type [N] links are
|
|
converted to [L] and type [-] are skipped entirely.
|
|
|
|
\item[\atr{target}] Target of link: For links in a directory that
|
|
don't point to objects, could be \lit{SYMBOLIC} or \lit{EXTERNAL}. For a
|
|
forwarding pointer it is \lit{FP}. Links to objects will have a target
|
|
field indicating the cached value of the object's \atr{BASE-TYPE}
|
|
attribute. When stored on a vlink structure, it may have exactly one
|
|
of the following forms: \lit{OBJECT}, \lit{FILE}, \lit{DIRECTORY},
|
|
\lit{DIRECTORY+FILE}. There is no guarantee that the type of the target
|
|
has not changed. Thus, this field is the cached value of the object's
|
|
base type. For union links, this field is always \lit{DIRECTORY} or
|
|
\lit{DIRECTORY+FILE}. See section~\ref{target-token} for a further
|
|
discussion of this.
|
|
|
|
|
|
\item[Hidden/Not-Hidden/Externally-Hidden\footnote{Not yet implemented}]
|
|
By default, a hidden
|
|
link is not displayed when a directory is listed. It is, however,
|
|
returned by the directory server, and is traversed if the actual name
|
|
is specified in a pathname. An Externally-Hidden link is a hidden
|
|
link that will be displayed if the current virtual system is the same
|
|
as the owning virtual system for the directory containing the link.
|
|
The user may override the hidden option, causing hidden links to be
|
|
listed. Note that it is also possible to hide a link by
|
|
specifying its protection as non-listable. Such links will {\bf only}
|
|
be returned by the directory server when the actual name of the link
|
|
has been specified.
|
|
|
|
\item[\atr{filter}] Multiple filters
|
|
allowed. The filter attribute is a pointer to a program that can be
|
|
used to filter the contents of directories to which links are made.
|
|
{\it data} is the set of optional arguments passed to the filter
|
|
program. In addition to the linked directory and arguments, the
|
|
filter has access to all other information available from the current
|
|
directory.
|
|
|
|
Filters come in several types. By default, a filter is a directory
|
|
filter, and is applied when searching directories. A hierarchy filter
|
|
is similar to a directory filter. The difference is that a directory
|
|
filter is applied to a single directory, while a hierarchy filter is
|
|
applied to the entire hierarchy (including subdirectories) reached
|
|
through a link. Directory and hierarchy filters come in two types.
|
|
The default is post-expansion. The filter is applied after all union
|
|
links have been expanded. A pre-expansion filter is applied before
|
|
union links are expanded. An object filter is applied when accessing
|
|
an object other than a directory, and might be used, for example, to
|
|
cause some operation to be performed on the object before it is
|
|
accessed. Note, however, that all types of filters are associated
|
|
with links.
|
|
|
|
Filters are applied to a directory in the order of pre-or post
|
|
expansion, decreasing depth of the links to which they are attached
|
|
(for hierarchy filters), and finally in the order that the filters are
|
|
specified on the traversed links.
|
|
|
|
\item {\bf Attributes} (optional). Application attributes to be
|
|
associated with the link. This allows a user or application to add
|
|
(or override) attributes to the linked object (which might be owned by
|
|
someone else, and thus not modifiable).
|
|
|
|
\item[\atr{host}] The name of the host on which the
|
|
object can be found.
|
|
|
|
\item[\atr{host-type}] The type of
|
|
the hostname. In particular, whether the hostname is an Internet
|
|
address, a domain style name, or a name in some other naming system.
|
|
|
|
Note that a symbolic link is a link where the destination host is a
|
|
virtual system, and the destination object name is a name relative to
|
|
that virtual system.
|
|
|
|
\item[\atr{hsoname}] Host-specific object name. The name of the object
|
|
relative to the destination system.
|
|
|
|
\item[\atr{hsoname-type}] The
|
|
type of \atr{hsoname}. Different types of names include numerical file IDs,
|
|
names relative to the root of the local file system, etc. Right now,
|
|
only pathnames are implemented, and their type is \lit{ASCII}.
|
|
|
|
\item[\atr{object-version}] By specifying a version number
|
|
in a directory link, the link is made to a specific version of the
|
|
object, and changes to the object will not be visible through the
|
|
link.
|
|
|
|
\item {\bf Access control info} (optional). Allows restrictions on who can
|
|
read or modify individual directory entries. These are really
|
|
attributes, though they are in fact retrieved and modified with LIST-ACL and
|
|
EDIT-ACL, and do not appear on the normal attribute listings.
|
|
|
|
\item[\atr{dest-exp}] {\bf Destination expiration date and time}. Its
|
|
implied type is a single-element {\tt SEQUENCE}, in ASN-TIME format.\footnote{
|
|
Implementers should use the {\tt asntotime()} function in the
|
|
{\tt pfs} library in order to convert an ASN-TIME string into a
|
|
\unix\ timestamp, and the {\tt timetoasn()} function to perform the
|
|
reverse conversion. Applications writers are encouraged to use
|
|
ASN-TIME format to represent all timestamps sent across the network.
|
|
}
|
|
This entry indicates how long
|
|
the information in the link should be considered valid. When an
|
|
object is accessed through a link, the destination expiration date
|
|
should be set to the current time plus the destination time-to-live.
|
|
|
|
Note that expired directory entries do not disappear. Typically they
|
|
remain valid. The expiration means that there is no longer a
|
|
guarantee that the object originally referenced can still be found.
|
|
|
|
\item {\bf ID}. When a new object is created, a unique
|
|
object identifier may be assigned. This identifier can be included in
|
|
links, and used to further verify that the named object is the one
|
|
that is actually desired. It allows one to reference objects after
|
|
their expiration dates with the guarantee that if these identifiers
|
|
match, it is the same object. In the prototype, the object identifier
|
|
is a random number of type REMOTE. Other types of object identifiers
|
|
will be defined after more work is done by an IETF working group.
|
|
|
|
\item {\bf Valid-till} (optional). If a link is a cached value, then
|
|
this field indicates how long the entry should be considered valid.
|
|
For example, a symbolic link may have a corresponding cached hard
|
|
link. Until its expiration a cache entry may be used instead of
|
|
searching based on the symbolic link. If this field is 0, then the
|
|
link is not a cached entry.
|
|
|
|
\item {\bf Last-update} (optional). This is the time the link was
|
|
last updated. Its expected use is for resolving conflicting updates
|
|
in replicated directories.
|
|
|
|
\end{description}
|
|
|
|
\subsection{Replication}
|
|
|
|
When support for replication is added to Prospero, a directory might
|
|
include multiple links with the same name for the same object. Not all
|
|
replicas need be listed, however, because each replica will maintain
|
|
its own list of siblings. Multiple entries are important to increase
|
|
reliability and availability.
|
|
|
|
\chapter{Asynchronous Reliable Delivery Protocol\label{ardp}}
|
|
|
|
This appendix describes the asynchronous reliable delivery protocol
|
|
(ARDP) used by Prospero. As used by Prospero, this protocol is
|
|
layered on top of the Internet User Datagram Protocol.
|
|
% \cite{udp}.
|
|
|
|
Prospero implements its own ARDP because at the time of initial
|
|
development we were unable to find any that were suitable for general
|
|
use. Most systems that use any sort of reliably delivered message
|
|
protocol implement their own around the specific needs of their
|
|
application. Like these other systems, early versions of the Prospero
|
|
protocol defined the mechanisms needed for retries and packet
|
|
sequencing. As these mechanisms were refined, the functionality was
|
|
moved to a separate protocol layer (and is implemented as a separate
|
|
library) to improve modularity, and in hope that this general and
|
|
simple ARDP can be used for other purposes.
|
|
|
|
The ARDP protocol is designed for a request/response style of
|
|
interaction, where a client sends a request message to a server in one
|
|
fell swoop and receives a reply message from the server. The server
|
|
can send the packets composing the reply message slowly, as data
|
|
becomes available, while it is still processing the rest of a reply.
|
|
In the current implementation, each request message sent by a machine
|
|
from a particular port has its own connection id.
|
|
|
|
ARDP was designed so that in the common case, the additional overhead
|
|
of guaranteeing reliability is as small as possible. Unless special
|
|
processing is required, the header is kept small, and unless a packet
|
|
is lost, no additional packets are sent. If a field is not specified,
|
|
the default value is used in its place. All fields up to and
|
|
including the last field specified must be filled in, but the header
|
|
may be truncated at any point, after which all remaining fields take
|
|
on their default values. The ARDP header contains the following
|
|
fields:
|
|
|
|
\begin{description}
|
|
\item[Octet 0] Version and header length: High order two bits are ARDP
|
|
version number mod 4 (this is version 0). Low order six bits are the
|
|
header length including octet 0.\footnote{The length of the total
|
|
packet, including data, is available via the UDP layer, as are the
|
|
port and IP address of the sending host.}
|
|
|
|
\item[Octets 1--2] Connection ID: Defaults to zero. It must be
|
|
specified in the response to any request that specified a non-zero
|
|
connection ID.
|
|
|
|
\item[Octets 3--4] Packet number: Defaults to 1 if not specified. A specified
|
|
value of 0 indicates an unsequenced control packet which should not
|
|
be passed to the application. Note that unsequenced control packets
|
|
cannot request acknowledgements, nor is there any way for the sender
|
|
of such a packet to be sure that they have arrived.
|
|
|
|
\item[Octets 5--6] Total number of packets in this message: Defaults
|
|
to 0 if not known, or retains current value if it was provided in any
|
|
earlier messages. If the packet number was also not specified, then
|
|
it defaults to 1. A specified value of 0 means use the default.
|
|
|
|
\item[Octets 7--8] Received through: Sequence number through which
|
|
all packets have been received by the sender of this packet. Defaults
|
|
to current value if specified in previous message. Defaults to 0
|
|
otherwise. The recipient's count of packets received through is
|
|
normally monotonically increasing; this keeps the count from being set
|
|
backwards in case an out-of-order packet is received. However, if the
|
|
``reset received through'' option (option 2) is specified in octet 12, then it
|
|
means reset to 0 (i.e. it forgot or lost the earlier messages). More
|
|
generally, specifying any explicit value for this field along with the
|
|
``reset received through'' option resets the peer's count, possibly
|
|
backwards. The recipient should not set its internal value of this
|
|
field backwards unless the ``reset received through'' option is set.
|
|
|
|
\item[Octets 9--10] Wait (expected time till response): Defaults to
|
|
current value. Specified value of 0 means revert to client-specified
|
|
backoff algorithm. Specifying a non-zero value lets the
|
|
client know that a request might not be processed for some time and
|
|
that the client should not retry the request until the specified time.
|
|
The client may retry sooner if it believes
|
|
messages are available which have been missed (e.g., gaps in the list
|
|
of received packets). This is an unsigned
|
|
quantity, measured in seconds, in network octet order (i.e., octet 9 is
|
|
more significant than octet 10). A specified value of 65,535
|
|
(\(\mbox{FFFF}_{16}\);
|
|
all bits turned on) means greater than or equal to 65,535 seconds
|
|
until the next packet. (We do not expect that this value will ever be
|
|
used, but it is defined for the sake of completeness.)
|
|
|
|
\item[Octet 11] Flags: Octet 11 is a bit vector specifying option flags.
|
|
The flags may themselves require additional
|
|
fields specific to the flag. These fields appear at the end of the
|
|
header in the order they are needed when reading flags from the low
|
|
order bit to the high order bit, followed by any extra fields needed
|
|
by the flag specified by the 12th octet.
|
|
|
|
%%
|
|
%% It does not appear to be possible to start a \lit{MINIPAGE} inside
|
|
%% a \lit{TABULAR} environment. LaTeX is really awful about not permitting
|
|
%% recursive application of its constructs. I wish there were
|
|
%% something better out there. --swa
|
|
%%
|
|
%% & \begin{minipage}
|
|
\end{description}
|
|
|
|
%\begin{table}[h]
|
|
\begin{center}
|
|
\begin{tabular}{|l|p{3.5in}|p{2.0in}|}
|
|
\multicolumn{3}{c}{Value of flags for octet 11} \\ \hline
|
|
Bit No. & Meaning & Additional Fields \\ \hline
|
|
0 (low order) & Additional Address Information Follows &
|
|
Variable length (see below)\\ \hline
|
|
1 & Priority Follows & 2 octets (see below)\\ \hline
|
|
2 & A Protocol ID for a higher-level protocol follows &
|
|
2 octets (see below) \\ \hline
|
|
3--5 & Unused & \\ \hline
|
|
6 & This packet is a sequenced control packet only; it should
|
|
not be returned to the application by the ARDP library. & None \\ \hline
|
|
7 (high order) & Please Acknowledge this Packet & None \\ \hline
|
|
\end{tabular}
|
|
\end{center}
|
|
%\end{table}
|
|
|
|
|
|
\begin{description}
|
|
\item[Octet 12] More Options: Octet 12 specifies exactly one (1)
|
|
of up to 256 other options. The options may themselves require additional
|
|
fields specific to the options. (See discussion at Octet 11).
|
|
\end{description}
|
|
|
|
%\begin{table}[h]
|
|
\begin{center}
|
|
\begin{tabular}{|l|p{3.0in}|p{3.0in}|}
|
|
\multicolumn{3}{c}{Value of options for octet 12} \\ \hline
|
|
Value & Meaning & Additional Fields \\ \hline
|
|
0 & No Option Specified & None \\ \hline
|
|
1 & Client to server: Cancel Request. Server to client:
|
|
Connection refused. & None \\ \hline
|
|
2 & Reset peer's received-through count.
|
|
& Specified in octets 7--8 \\ \hline
|
|
3 & Packets received beyond received-through
|
|
& The rest of the
|
|
header after additional data for octet 11 flags is an arbitrary
|
|
number of octets. These are bit-vectors specifying which packets
|
|
beyond the received-through specified in this packet have been
|
|
received by the sender of this packet. For example, if the
|
|
received-through is set to 43, then we know that packet 44 has not
|
|
been received. The low order bit of the first octet of the additional
|
|
field will be turned on if packet 45 has been received, and off if it
|
|
has not. The high-order bit will be turned on if packet 52 has been
|
|
received, and off if it has not. Similarly, the low-order bit of the
|
|
second octet of additional information will be turned on if packet 53
|
|
h as been received, and so on. The recipient of this information may
|
|
choose to ignore it and use a simpler resend strategy. Similarly,
|
|
this information is never required to be sent. \\ \hline
|
|
4 & Redirect (used by servers): The client should send any
|
|
unacknowledged packets
|
|
already sent and all subsequent packets in this message to a new
|
|
addresss. This is designed to be used as a load-shedding device. In
|
|
one common case, this will be the entire response a server gives to a request,
|
|
and the client will resend the entire request to a new server; in
|
|
the other common case, this will be used in conjunction with option 6
|
|
or 7.
|
|
& 6 octets. The first 4 octets are the IP address of the new server,
|
|
in network byte order. The next 2 octets are the UDP port to which
|
|
the request should be sent, also in network byte order. \\ \hline
|
|
5 & Redirect and notify (used by servers). Like option 4, but
|
|
the client's network layer should also notify its caller that all
|
|
subsequent requests intended for the old server should be sent to the
|
|
new server instead. & Same as option 4. \\ \hline
|
|
6 & Forwarded: This request was received from a
|
|
client, and the sender is a server forwarding it to the recipient for
|
|
processing. The recipient should pretend that it received this
|
|
message from the sender indicated by the additional fields, not from
|
|
the real sender of this message. (If implemented, this request should be accepted only
|
|
from one of a group of trusted hosts.) This option is intended to be
|
|
used by a central server which distributes requests to several subsidiary
|
|
servers which do the actual work of processing the request, but which
|
|
use the central server as a contact point. Presumably, it is cheaper
|
|
for the central server to forward the request to the subsidiary
|
|
servers over a local area network rather than for the client (who may
|
|
be quite far away) to retransmit it. The central server has done
|
|
the job of notifying the original client (through option 4 or 5) that
|
|
further requests and retransmissions should go to the new server.
|
|
& 6 octets: The IP address and port of the original sender of
|
|
this message, as in number 4. \\ \hline
|
|
\end{tabular}
|
|
|
|
\begin{tabular}{|l|p{3.0in}|p{3.0in}|}
|
|
\multicolumn{3}{c}{Value of options for octet 12} \\ \hline
|
|
7 & Forwarded; Please notify: Like option 6, but the receiving
|
|
server should notify the client of the switch (through option 4 or 5).%
|
|
\footnotemark
|
|
& 6 octets: The IP address and port of the original sender of
|
|
this message, as in number 4. \\ \hline
|
|
8-252 & Undefined & Undefined \\ \hline
|
|
253 & Request Queue Status & 1 octet. If bit 0 (low order) is
|
|
set, the position in the queue is requested. If bit 1 is set, the
|
|
estimated time until this request will be completed is requested. The
|
|
recipient may ignore this option. \\ \hline
|
|
254 & Response to 253. & 1 octet of flags, followed by 1 or 2 additional
|
|
fields. If bit 0 (low order) of the flags is set, the position in the
|
|
queue is returned as a 2 octet network byte order representation of an
|
|
unsigned quantity. A value of \hexnum{FFFF} (all bits turned on) means
|
|
a queue position of \hexnum{FFFF} or further. (We do not expect this
|
|
value to ever be used, but it is included for the sake of
|
|
completeness.) If bit 1 of the flags is set, the estimated
|
|
time until this request will be completed is returned as a 4-octet
|
|
network byte order unsigned value, representing a time in seconds. A
|
|
value of \hexnum{FFFFFFFF} (all bits turned on) means a time of
|
|
\hexnum{FFFFFFFF} seconds or more. (We do not expect this to ever be
|
|
used). \\ \hline
|
|
255 & Reserved for future expansion & Undefined \\ \hline
|
|
\end{tabular}
|
|
\end{center}
|
|
\footnotetext{You might think that the recipient needs to worry
|
|
about the IP address of the FORWARD message it sends to the original
|
|
client being different from that of the original server (the sender of
|
|
this message). However, this is not the case. The existence of
|
|
multi-homed hosts means that the sender of a message cannot assume
|
|
that the IP address of a reply (as recorded in the UDP packet
|
|
encapsulating the response it receives) is the same as the address the
|
|
packet was sent to. The sender must use the connection ID to match up
|
|
sent messages and received replies.}
|
|
%\end{table}
|
|
|
|
\begin{description}
|
|
\item[Octets 13 and above] Fields specific to particular flags and options.
|
|
|
|
First, additional data fields specific to the flags in octet 11
|
|
should be specified.
|
|
|
|
\item[Next Octets] Additional Address Information (if Additional
|
|
Address Information flag specified): The first octet specifies the
|
|
type of additional address information. The next octet specifies the
|
|
length of the address information, from 0 to 255 octets.\footnote{The
|
|
entire 255 octets are not available for address information, since they
|
|
are part of the header, and the maximum header length header is
|
|
limited to 64 octets.}
|
|
Its length
|
|
does not include the two octets that specify type and length. The following
|
|
octets contain the address information itself, and its format is
|
|
dependent upon the type of address information.
|
|
|
|
\item[Next 2 octets] Priority (if Priority flag specified):
|
|
These octets are a signed integer representing the priority of the
|
|
request. Not all implementations understand this message, and many
|
|
that do will not honor requests for expedited handling. Negative
|
|
numbers indicate expedited handling while higher numbers indicate
|
|
greater delays. A priority of 0 is normal.
|
|
|
|
\item[Next 2 octets] Protocol ID (if Protocol ID flag specified):
|
|
These octets identify the interpretation of the data carried in the
|
|
packet. The default, or an explicitly specified value of 0, mean
|
|
that it is not specified, but has been agreed upon externally (i.e.
|
|
the applications will know).
|
|
|
|
\item[Next octets] Any data specific to the option set by octet 12
|
|
should be specified. This is the data specified in the ``additional
|
|
fields'' column of the table ``Value of flags for octet 12.''
|
|
|
|
\end{description}
|
|
|
|
\chapter{Prospero Conventions\label{conventions}}
|
|
|
|
\section{\protect\meta{hsoname}s}
|
|
|
|
There are some special \meta{hsoname}s that the current Prospero
|
|
server may recognize, if it has been configured appropriately. If an
|
|
\meta{hsoname} begins with the string \lit{AFTP/}, it is interpreted
|
|
as a path relative to the anonymous FTP directory on that server. If
|
|
an \meta{hsoname} begins with the string
|
|
\lit{GOPHER}\zoos\lit{(}\meta{gopher-port-number}\lit{)}\zooe, it is
|
|
interpreted to refer to GOPHER data files on that host . If an
|
|
\meta{hsoname} begins with the string \lit{GOPHER-GW}, it refers
|
|
to GOPHER data files on another host. If an \meta{hsoname}
|
|
begins with the string \lit{ARCHIE/}, it represents an Archie database
|
|
query.
|
|
|
|
|
|
\chapter{Prospero Protocol Changes from Version 1 to Version 5}
|
|
|
|
Versions 2, 3, and 4 of the Prospero protocol were not used. The
|
|
protocol number jumped from version 1 to version 5 to keep the
|
|
software number and version number consistent; the first version of
|
|
the server to implement version 5 protocol had a software version
|
|
number of 5.
|
|
|
|
For now, all Prospero servers continue to accept Version 1 of the
|
|
protocol.
|
|
|
|
Not all of the protocol changes are listed here.
|
|
|
|
In version 1, the \lit{EDIT-LINK-INFO} command was called \lit{MODIFY-LINK}.
|
|
The syntax of the arguments has also been changed.
|
|
|
|
The method of specifying attributes to \lit{LIST} has changed. The
|
|
lines returned from \lit{LIST} are also in a new format.
|
|
|
|
The quoting mechanism has been formalized, and extended to apply to
|
|
multiple-component directory names. Therefore, the \lit{ONECOMP}
|
|
option to \lit{LIST} is now officially dead (it was never implemented
|
|
in any server anyway). Note that no Version 1 server ever implemented
|
|
quoting properly anyway. Therefore, if a client speaks Version 1
|
|
Protocol, it will not be able to access filenames with spaces in them.
|
|
|
|
|
|
The \meta{magic-no} field has been replaced with zero or more
|
|
occurrences of the sequence \lit{ID} \meta{id-type} \meta{id-value}.
|
|
\lit{GET-OBJECT-INFO} used to have the reserved keyword \lit{ID}, but
|
|
this has been flushed.
|
|
|
|
The syntax of the arguments of
|
|
\lit{EDIT-OBJECT-INFO} has been changed, in order to avoid a syntactic
|
|
amgiguity.
|
|
|
|
Many changes have occurred to the arguments of commands.
|
|
|
|
Filter syntax has changed drastically.
|
|
|
|
Separate principals are now sent as separate protocol tokens in ACL
|
|
and attribute definitions.
|
|
|
|
The \atr{target} field used to have a possible value of
|
|
\lit{SYM-LINK}. This has been changed to \lit{SYMBOLIC}. The
|
|
\atr{base-type} field has been introduced.
|
|
|
|
The syntax of a \meta{target} of \lit{EXTERNAL} has changed
|
|
radically. EXTERNAL links now look a lot more like conventional links.
|
|
The meaning of the \atr{access-method} attribute has changed radically;
|
|
it's now a lot more flexible.
|
|
|
|
Support for Kerberos has been specified.
|
|
|
|
\end{document}
|