THE GRAPEVINE INTERFACE194.2Mail Server ProtocolsThe mail server responds with PUP type "iAmEcho" (type 2) to PUP's of type "echoMe" (type 1)and length no more than 128 bytes sent to it on socket 54B.Any Grapevine mail server will accept messages submitted to it by the following protocol, and willdeliver them to the specified recipients, according to the delivery semantics defined in section three.This mail submission protocol allows a sequence of commands on a Byte Stream Protocol connection.The mail server is usually willing to establish such a connection in response to an RFC packet sentto the mail server on socket 56B. The commands each consist of the client sending a wordrepresenting an operation, probably followed by some arguments, then the server generally sendssome results. Not all commands are allowed at any time. The restrictions on the order of thecommands are described in terms of the state of the stream; violation of these restrictions is aprotocol violation. The state may be idle, started, noItem, or inItem. The state is initially "idle".StartSend: operation = 20, arguments = [ sender name, password, return-to name, boolean ]This command is allowed only if the state is "idle". The password should be that of thesender. At present, the server ignores the password, but checks that the sender name wouldbe valid as a recipient name; we reserve the right to start checking the sender passwordsome time in the future, without notice. The server checks that the return-to name wouldbe valid as a recipient. The boolean should be TRUE iff the client wishes the server tovalidate the recipient names during the connection. The result is a byte, with the followingvalues. 0 means everything is ok. 1 means the sender password is incorrect (not checked atpresent). 2 means the sender name is invalid. 3 means the return-to name is invalid. 4means that the server could not validate some name because of communication problems.If this byte is 0, then the state of the connection becomes "started".AddRecipient: operation = 21, arguments = [ name ]This command is allowed only if the state is "started". The name is added to the list ofrecipients for this message; there is no result.CheckValidity: operation = 22, no arguments.This command is allowed only if the state is "started". If the boolean argument of theStartSend command was TRUE, then for each recipient which appears to be invalid theserver sends a number specifying which recipient it was (counting the calls of AddRecipient,from 1) followed by the name of the invalid recipient, and these recipients are removedfrom the recipient list of the message. Then (regardless of the value of the boolean) theserver sends the number 0 followed by a number indicating how many names remain in themessage's recipient list. The state of the stream becomes "noItem".StartItem: operation = 23, arguments = [ word ]If the state of the stream is "inItem", then the current message body item is terminated andits length calculated and the state of the stream becomes "noItem". The state of the streammust now be "noItem". The word specifies the type of a message body item, and the stateof the stream becomes "inItem". The acceptable types of message body item have beendescribed in section three, in connection with the message delivery semantics. There is noresult.!fpqpXqpqG?p br2 _pqpqp  ]K; ZCb XxC$ Vspsp  T6qp S&3 QN4sp! Osp1! M&sp4 K&spspspsp! Hs p EEQD'4BIB@~ M>/qp$< Q;L9T<7=5F 2s p&/8!-0 *s p').& qp$>&6"sP CBD  s p&8$9\nJ @ O & >ZDYTHE GRAPEVINE INTERFACE20AddToItem: operation = 24, arguments = [ number, sequence of bytes ]This command is allowed only if the state is "inItem". The number specifies how manybytes are in the sequence. The bytes are appended to the current message body item.There is no result.Send: operation = 26, no arguments.This command is allowed only if the state is "inItem". The current message body item isterminated (as in StartItem), and all the data associated with the message is recorded instable storage. The server commits to deliver the message. The result is an ack. The stateof the stream becomes "idle".Expand: operation = 27, argument = [ name ]This command is allowed at any time and does not affect the state of the stream. If thename would be treated by the mail servers as a distribution list during the deliveryalgorithm (including a foreign distribution list) then for each name in that list, the serversends a boolean TRUE followed by the name. Then a boolean FALSE is sent. Then a byteis sent. The value of this byte is: 0 if the name was treated as a distribution list, 1 if thename would be an invalid recipient, 2 if the name would be an individual recipient(including foreign mail system recipients), 3 if the mail server could not decide because ofcommunication failures. The intent of this command is to allow a client to show a user thepotential contents of a distribution list.The following protocols allow a client to inspect and modify the state of an in-box on a mail server.Mail arrives in an in-box as the major effect of the mail server delivery algorithm. Note that anindividual may have several in-boxes, defined by the individual's mailbox-list in the namingdatabase, and any mail retrieval package should arrange to inspect all of the individual's in-boxes.The in-box mechanism is complicated by facilities (TOC entries and deleted messages) which aredesigned to assist a dumb terminal system to provide a user with temporary access to mail in theuser's in-boxes. The intent is that a user should retrieve all messages from the in-box and flush thein-box when software with secondary storage is available to the user. Keeping substantial amountsof mail in an in-box for substantial periods of time will degrade the performance of the mailservers. The TOC mechanism allows a client to associate a TOC entry (represented by a remark, i.e. astring of up to 64 characters) with each message in an in-box. Provision is also made for a client todelete individual messages from an in-box; a deleted message still occupies a place in the in-boxuntil the in-box is flushed, but deleting the message frees the resources used by the message bodyand property list. No TOC entry may be associated with a deleted message. If there is no in-box onthis server for an individual, then the protocol provides the illusion that there is an in-boxcontaining no messages.The mail server accepts PUP's of type "mailCheckLaurel" (type 214B) and length no more than 128bytes on socket 54B. If the PUP contains the characters of a name, and this mail server has a non-empty in-box containing messages for a recipient of that name (even if they are all deletedmessages, see below), then the mail server replies with a PUP of type "mailIsNew" (type 211B);otherwise it replies with a PUP of type "mailNotNew" (type 212B). Note that the server does notrespond to PUP's of type "mailCheck" (type 210B). Note that the server does not check whether thenaming database presently indicates that this server is in the user's mailbox-list. This pollingprotocol is intended to allow a client to inspect the state of an individual's in-box without going to!fpqpXqpqG?p bs p;_,)]K)+[ XxspUp6"SHQ;"P Msp%J7!H6.&FkR Dqp'qpB&9A E?AJ=vD;* 6(50 4^02 20, 0 W .3tspsp -3"> +if )b '/. & qp*tsp! $>] "ssp6% sp. qp1 @ I Aqp"" vqpC 0+ qp! qp" L qp.& R 15\ p>\nTHE GRAPEVINE INTERFACE21the expense of establishing a Byte Stream Protocol connection.An in-box may be accessed after establishing a Byte Stream Protocol connection in response to anRFC packet sent to a mail server on socket 57B. The state of this stream is described as one of idle,open, or inMessage, and there are restrictions on which commands may be used depending on thestate. Violation of these restrictions is a violation of the protocol. The state is initially "idle". Eachcommand consists of the client sending a word representing an operation, possibly followed by somearguments, then the server sending some results. The commands allow the client to open amailbox, then sequentially inspect or modify the messages in it; the order of the messages isapproximately that in which they were sent, and the order does not change between sessions;messages are not added to an in-box while a client has it open; only one client may have aparticular in-box open at one time. A client, having opened an in-box, may flush it: this causesthe in-box to be empty. If a client wishes to close an in-box without flushing it, the client mustterminate the connection.A mail server may occasionally use a remote file server for storing contents of in-boxes; if this hasbeen done and the file server is unavailable, the mail server will close the client's mail retrievalconnection arbitrarily (sorry!). The location of such a remote file server is of no concern to a clientof the mail retrieval protocol, but has been described in section three.OpenInBox: operation = 0, arguments = [name, password]The state must be "idle". The result is a byte with the following values: 1 if the name isfor a group, 2 if the name is for an individual and the password is correct, 3 if the name isnot registered in the naming database, 4 if the name could not be checked because ofcommunication failures, 5 if the password is incorrect. If this byte has the value 2, then thestate becomes "open". The byte is followed by a word, which should be ignored.NextMessage: operation = 1, no arguments.If the state is "inMessage", it becomes "open". The state must now be "open". The resultis a sequence of three booleans. The first is TRUE iff there is another message in the in-box, and this becomes the current message; if this boolean is FALSE the others areundefined. The second is TRUE iff the message is archived; this is a hint to the client thataccess to the message may involve access to a remote file server; we recommend that youindicate this fact to your user. The third is TRUE iff the message is deleted. If the messageis not deleted, then the state becomes "inMessage".ReadTOC: operation = 2, no arguments.The state must be "inMessage". If there is a TOC entry associated with this message, theresult is a remark. Otherwise the result is an empty string.ReadMessage: operation = 3, no arguments.The state must be "inMessage". The result is a sequence of message body items,representing the message's property list followed by the message body. Each item has thefollowing format: a number, which is the item's type, followed by a long number, which isthe item's length, followed by that number of bytes, followed by an extra byte if the lengthwas odd (thus each item occupies an even number of bytes). The items sent are: an itemof type "postmark" (whose bytes are the timestamp of the message's property list), an itemof type "sender" (whose bytes are the sender name of the message's property list), an itemof type "return-to" (whose bytes are the return-to name of the message's property list), an!fpqpXqpqG?p b> _] ]KqpAsp [spsp: Y94 W:( V!D TVM RI P2( N[ M,>% Ka HY7. FS DK BH ?s p-< N;!<9TT7[5: 2s p/T-% qp(,6qp*Nqpsp#( J&/qp$$3 !sp.qp=  s pH9?nQN 2&Z DR yA 2=]\THE GRAPEVINE INTERFACE22item of type "recipients" (whose bytes are the recipient names of the message's propertylist), the items that constitute the message body in the order provided by the submittingclient, and an item of type 177777B. The item of type 177777B is of length 0. The itemsare followed by a Byte Stream Protocol mark byte. The value and meaning of the propertylist item types is given earlier in the description of the message delivery semantics.WriteTOC: operation = 4, argument = [remark]The state must be "inMessage". The remark is associated with the message as a TOC entry,(replacing any earlier TOC entry for this message); if the remark is the empty string, noTOC entry is associated. The result is an ack.DeleteMessage: operation = 5, no arguments.The state must be "inMessage". The current message is permanently deleted from this in-box (as is any associated TOC entry). The result is an ack. The state becomes "open".Flush: operation = 6, no arguments.The state must not be "idle". The in-box is emptied. The result is an ack. The state isnow "idle".!fpqpXqpqG?pb8`S,-^ K\'sp-ZV Wsp$T>qpSqp=QNqp, NFs pK>6"Is qp: FkspCcL A D AQ8&THE GRAPEVINE INTERFACE235.A Mesa Grapevine client interfaceThis section describes informally the interface provided to clients programming in Mesa by theCedar GrapevineUser package. The purpose of this section is not primarily to document thatpackage for its clients, but to indicate how the Grapevine naming database may be used to providean interface that makes transparent such network effects as the replication and distribution ofservices, and the failure of particular instances of services. If the reader is intending only to be aclient of the Cedar package, then this section should be read briefly; precise specification of thepackage is in the public definitions files for the package. If the reader intends to implement anequivalent package (in Mesa or another language), then I strongly recommend perusal of the sourcefiles of both the definitions and implementations of this package. All files concerned with thispackage are available on [Indigo]Grapevine>*.mesa and *.bcd.GrapevineUser provides several public interfaces. These are named GVNames, GVSend, andGVRetrieve. The GVNames interface provides access to most of the naming database enquiry andupdate operations; GVSend provides for submission of messages; GVRetrieve allows a client toread messages from in-boxes. The GVBasics interface defines some data types common to the otherinterfaces. Each of these interfaces uses the naming database to provide an interface that isindependent of particular computers or network addresses. A client of GrapevineUser never isconcerned with such things as host names.In the following descriptions, the precise declarations found in the definitions files are not repeated:the reader should look in the sources of those definitions files.The GVNames interface provides for database enquiries and updates. The results of theseoperations are a return code, represented by some subset of the enumerated type Outcome, and insome cases a list of names. Each operation may give a return code "allDown", to indicate thatbecause of communication failures the requested operation could not be performed; this indicatesthat after its best efforts to contact any of the multiple suitable registration servers, the package hadfailed. None of the operation raises a SIGNAL. The operations each have an obvious mapping intothe commands described in the registration server protocol.The transparency provided by the GVNames interface is achieved as follows. Generally, theGVNames implementation caches a stream to some registration server. When it is asked to performan enquiry about some name, the implementation uses the cached stream to attempt the enquiry. Ifthis stream fails (because that registration server is now unavailable), or if this enquiry gives a"WrongServer" return-code, then the implementation attempts to locate a suitable registrationserver. It does this by using a resource location interface (described below) to find a networkaddress of some server which knows about the name in question. That is, if the name in question isof the form x.reg, the implementation tries to locate a server in the group named reg.gv. If thissucceeds, such a server should be able to answer the enquiry; if this fails because reg.gv" is not agroup, then the name is invalid; if this fails because none of those servers is available then thereturn code given is "allDown".The GVSend interface implementation proceeds in a similar manner. Each of its procedures has astraightforward mapping into a command specified in the mail submission protocol. The GVSendimplementation attempts to cache the network address of a suitable mail server, but if this fails (orinitially) the implementation uses the resource location interface to locate a server in the group"MailDrop.ms". Only if this resource location fails is mail submission not possible.!fpqpXqpqG?p au2! ^pH ]s pH [:(9 Yo? WF! U!C T;' REZ Pz10 NC KCspsp Is p0# H@ FHsp6 D}M BZ @) ="F <A 9 R 7BPqp 5x/qp 3F 1V 0(qp1 .M; +E: ){D 'H %a $> "PB K  sp$sp Tsp &;' [ S#< G $A \ )U >Y)kTHE GRAPEVINE INTERFACE24The GVRetrieve interface is more complicated, because it provides a client with access to all of theclient's in-boxes. The implementation determines the sites of a client's in-boxes by using theExpand database enquiry. The interface also uses the single PUP polling protocol to obtain hintsabout the state of the in-boxes. When a client wishes to inspect mail, the implementationestablishes connections only to those in-boxes which have indicated they are non-empty during thepolling protocol; this is important to minimize the connection load on the mail servers, since aclient's secondary in-boxes will almost always be empty. The GVRetrieve interface will also provideclients with access to their mailbox on a foreign mail server (using the MTP protocol), and willfunction satisfactorily in an environment where there are no Grapevine servers, only IFS mailservers. To determine whether it is in a non-Grapevine environment, the GVRetrieveimplementation considers whether the client's registry is registered in the PUP Name Lookup Serverdatabase; if the registry is registered there and maps to precisely one network address, then theregistry is assumed to be implemented on an IFS mail server (at that network address) with no aidfrom Grapevine; otherwise the Grapevine servers are used.The GrapevineUser package uses the following algorithm to perform resource location. Theresource location interface is provided with the name of a group in the naming database. It readsthe members of this group, giving it a list of names of potential servers. For each of these, it readstheir connect-site from the database. The implementation then sends a PUP of type "echoMe" toeach of these servers. For each server which replies with an "iAmEcho" PUP, the implementationcalls back to its caller, offering the network address of that server. In this manner, the caller of thisinterface is provided with network addresses of potential instances of the service named by thegiven group, and the caller can attempt to establish a connection with these, in turn, until asatisfactory one is found. The "echoMe" mechanism is intended for efficiency: the servers aretried in order of their responsiveness, and each one tried is responding to PUP's, so an attempt toconnect will be resolved rapidly.There are several optimizations used within the GrapevineUser implementation, and the potentialimplementor is strongly recommended to inspect the GrapevineUser implementations.!fpqpXqpqG?p b V `S@ ^<qp! \(2 Za Y)_ W^\ U)qp S;qp Q; e = C ;AP 9wN 7Dqp 5! 2/0 1Q 0=7CTHE GRAPEVINE INTERFACE256.Administrative FacilitiesThe major administrative facility in Grapevine is the naming database. Most system administrationcan be done by performing updates to that database, and an interactive program, called Maintain, isavailable to perform these updates. Maintain is documented (partially, at the present time)elsewhere.In addition, there are some facilities provided by Grapevine to monitor and affect the state of thecomputers which constitute Grapevine. These facilities change from release to release of thesoftware, so this section is likely to be slightly incorrect at any time. These facilities are definedprecisely only by their implementation. The facilities in question are: a local terminal interface, anFTP server, a Telnet server, and a log file.The local display shows various statistics about the state of the servers. These statistics are the sameas those available through the Telnet server "Display Statistics" command. There is also a shorttypescript, which is of use only to wizards. When the local keyboard and mouse have not beentouched for a minute, the display reverts to plain white, with a cursor slowly traversing near the topof the screen; moving a key or the mouse causes the statistics to reappear.The local keyboard is used only when a server is initialized or restarted. When a server isinitialized for the first time, it will determine its own name, ask you to type its password, andarrange to fetch copies of the appropriate database entries. When a server is restarted, it will verifyits password (asking for it to be re-typed only if this verification fails), and if necessary will alter itsconnect-site in the naming database. Note that registration servers and mail servers cohabiting asingle machine must have distinct names (typically, the same simple-name, with registries "gv" and"ms"). The case of initializing the first server in the world is necessarily special - consult an expertfor details.Each Grapevine server provides an FTP server which allows access to files on the Grapevine server'slocal disk filing system. Clients of this FTP server must provide credentials corresponding to a validname and password of an individual in the Grapevine database. The files which support thenaming database and message buffering are not accessible. To be permitted to read the file"GV.log", the client must be a member of the group "LogReaders^.ms". To be permitted to accessother files, the client must be a member of the group "Transport^.ms". The FTP server supportsenumeration of files, with the string "*" meaning all files.The log file contains single-line entries recording various events as they occur in the server. Thefile is named "GV.log" and is 120 Alto pages long. The file is used as a circular buffer. Each cycleround this buffer may also be written to backing files on an IFS file server. For a server whose mailserver has a name of the form x.ms, the individual Log-x.ms should have a connect-site whose valueis a string of the form [host]. This will cause the log files to be written cyclically to 40 fileswith names of the form x-00!1 through x-39!1 on the file server host using the FTPprotocol. For example, if "Cabernet.ms" is a mail server and the individual "Log-Cabernet.ms"exists and has connect-site "[Ivy]Log>", then files such as "Log>Cabernet-09!1" willbe stored on the file server "Ivy". If the required Log-x.ms individual does not exist, no attemptwill be made to write the log files to a file server; the individual is examined only when the serveris restarting, and is not revisited during normal running.The Telnet server (known as the "Viticulturists' Entrance") provides various facilites to a remoteterminal user. Some of these facilities are privileged: they are allowed only to an individual whohas logged in, and who is a member of the group "Transport.ms" or whose name is "Wizard.gv"and they are only available after using the "Enable" command. Most commands can be stopped by!fpqpXqpqG?p au2 ^p5- ]:sp [:$8 Yo VgG T&7 RV QY O=qp) L5J JjJ HB FN E K BJ @7S >mX <D( :H 9 I 7B$E 5x 2p"qp# 0 !qp9 .R -L +EH ){ @qp '< $` "I !=qp H spsp' }s p3 s ps psp q p2, C S#sp& #C : J >& E V[ =]|THE GRAPEVINE INTERFACE26typing DEL. The facilities change frequently, but at present are as follows.Add-Registry:Interacts with the user to perform the steps needed to add a registry to a runningregistration server.Display Histograms:Types histograms of various events. At present only mail retrieval delays.Display Inboxes:Types a summary of the state of clients' in-boxes on this server.Display Other-Servers:Types this server's view of the availability of other servers that it knows about.Display Policy-Controls:Types information about the various internal server controls on operations. This includeswhether the operation is presently "allowed", how many instances of the operation areallowed simultaneously, the highest number that have occurred simultaneously, and the totalnumber that have occurred. See also the "Set Policy-Controls" command.Display Queues:Types a summary of the queues of not-yet-delivered messages maintained by the mailserver.Display Statistics:Types various statistics kept by the server, including server version and uptime.Display Time:Types the local time of day.Enable:Allows use of the privileged commands if the logged in user is "Wizard.gv" or is a memberof the group "Transport.ms".Force Archive:Forces transfer of the contents of an in-box to a backing file server. The choice of backingfile server is described below.Force Background-Process:Forces immediate activation of one of the periodic processes in the server. The "Archiver"process scans inboxes looking for ones which should be written out to a remote file server(this normally hapens about 11 p.m. each evening); the "ReadPending" process considersthose messages which are on the pending queue because there was nowhere to deliver them(this normally happens every 15 minutes); the "RegPurger" process scans the naming!fpqpXqpqG?p bM _s \pRZC W;sT3pK Q+sN#pA KsHpR E sBpZ@7@>m[<G 9s6p54 1s.pQ +s (p %s"p3&  s pG sp"93'LD J  R" p8\THE GRAPEVINE INTERFACE27database looking for information representing dead entries or removed members of listswhich is more than 14 days old and can be removed from the disk (this normally hapensabout 11 p.m. each the evening).Force MSMail-Login:Causes the process that reads mail server internal mail to login to GrapevineUser afresh,causing it to reconsider the location of its inboxes.Force RSMail-Login:Causes the process that reads registration server internal mail to login to GrapevineUserafresh, causing it to reconsider the location of its inboxes.Force Purge:Asks for an R-Name. If this R-Name corresponds to a dead entry in the naming database,removes that entry immediately (without waiting for the normal 14 day timeout). Thisallows immediate re-use of that name, but is incorrect unless all copies of the appropriateregistry throughout Grapevine know that the entry was dead.Login:Asks for name and password, and attempts to authenticate the name by use of the namingdatabase.Maintain:Enters the Maintain program, which allows maintenance of the naming database.Quit:Terminates this connection.Restart:Asks for an Alto executive command line to place in the local file "Rem.cm", asks for acomment to write in the log, asks for more confirmation, then stops the server (whichreturns to the Alto executive, which will execute the command line from "Rem.cm").Set Archive-Days:Alters the timeout used by the in-box archiver process. This alteration applies only to thenext run of the archiver, then the timeout reverts to its default 7 days.Set Policy-Control:Alters the state of various internal server controls from "allowed" to "not allowed", or viceversa. Setting the control to be "not allowed" prevents the operation in question frombeing started subsequently; it does not affect operations currently in progress. The controlsform a hierarchy; all appropriate levels in the hierarchy must be "allowed" for an operationto be permitted. The controls in question are:Work: must be allowed for any operation to be allowedConnection: controls incoming connections other than the Viticulturists' Entrance.ClientInput: controls mail submission connections!fpqpXqpqG?pbV`S H^ [sXxpCV5 SsPpK N= Ks Hp/(F3"E-O Cc; @[s=Sp I; 8s5xpM 2ps/hp ,_s)Wp L'>%G "spJI sp>s p3B^w>/(sp0 s p) Ms p%| 8]THE GRAPEVINE INTERFACE28ServerInput: controls mail forwarding connections from other Grapevine serversReadMail: controls mail retrieval connections.RegExpand: controls registration server enquiry connections.Lily: controls Telnet server connections to any local Lily server.MTP: controls MTP server connections from clients.FTP: controls FTP server connections from clients.Telnet: controls Viticulturists' Entrance connections.MainLine: controls the following four operations:ReadInput: controls processing messages queued for delivery.ReadPending: controls processing messages from the "pending" queue.ReadForward: controls forwarding message to other servers.Remailing: controls remailing of messages from inboxes.Background: controls the following operations:RSReadMail: controls reading registration server database update messagesMSReadMail: controls reading mail server in-box re-mail requests.Archiver: controls the transfer of in-boxes to remote file servers.RegPurger: controls the nightly clean-up of the naming database.Wait-until-idle:Waits until the only activity in the server is this Telnet connection. This wait may also beterminated by typing DEL.!fpqpXqpqG?pbs p 4`Ssp%^s p2\sp=Zsp qp!Y)sp qp!W^sp/Usp(Ss p2Qs p7P4s p.Nis p-Ls p#Js p>I s p6G?sp:Ets p6 Bls?dpL= =R8* TIMESROMAN  TIMESROMAN TIMESROMAN  TIMESROMAN  TIMESROMAN TIMESROMAN  x! +1 ;/@FlJj/M KInterface2.bravo Birrell.paNovember 7, 1983 1:50 PM