RFC 993 Network Working Group David D. Clark (MIT) Request for Comments: 993 Mark L. Lambert (MIT) Obsoletes: RFC-984 December 1986 PCMAIL: A Distributed Mail System for Personal Computers 1. Status of this Document This document is a discussion of the Pcmail workstation-based distri- buted mail system. It is a revision of the design published in NIC RFC-984. The revision is based on discussion and comment from a variety of sources, as well as further research into the design of interactive Pcmail clients and the use of client code on machines other than IBM PCs. As this design may change, implementation of this document is not advised. Distribution of this memo is unlimit- ed. 2. Introduction Pcmail is a distributed mail system providing mail service to an ar- bitrary number of users, each of whom owns one or more workstations. Pcmail's motivation is to provide very flexible mail service to a wide variety of different workstations, ranging in power from small, resource-limited machines like IBM PCs to resource-rich (where "resources" are primarily processor speed and disk space) machines like Suns or Microvaxes. It attempts to provide limited service to resource-limited workstations while still providing full service to resource-rich machines. It is intended to work well with machines only infrequently connected to a network as well as machines per- manently connected to a network. It is also designed to offer disk- less workstations full mail service. The system is divided into two halves. The first consists of a sin- gle entity called the "repository". The repository is a storage center for incoming mail. Mail for a Pcmail user can arrive exter- nally from the Internet or internally from other repository users. The repository also maintains a stable copy of each user's mail state (this will hereafter be referred to as the user's "global mail state"). The repository is therefore typically a computer with a large amount of disk storage. The second half of Pcmail consists of one or more "clients". Each Pcmail user may have an arbitrary number of clients, typically single-user workstations. The clients provide a user with a friendly means of accessing the user's global mail state over a network. In order to make the interaction between the repository and a user's clients more efficient, each client maintains a local copy of its Clark & Lambert [Page 1] RFC 993 December 1986 user's global mail state, called the "local mail state". It is as- sumed that clients, possibly being small personal computers, may not always have access to a network (and therefore to the global mail state in the repository). This means that the local and global mail states may not be identical all the time, making synchronization between local and global mail states necessary. Clients communicate with the repository via the Distributed Mail Sys- tem Protocol (DMSP); the specification for this protocol appears in appendix A. The repository is therefore a DMSP server in addition to a mail end-site and storage facility. DMSP provides a complete set of mail manipulation operations ("send a message", "delete a mes- sage", "print a message", etc.). DMSP also provides special opera- tions to allow easy synchronization between a user's global mail state and his clients' local mail states. Particular attention has been paid to the way in which DMSP operations act on a user's mail state. All DMSP operations are failure-atomic (that is, they are guaranteed either to succeed completely, or leave the user's mail state unchanged ). A client can be abruptly disconnected from the repository without leaving inconsistent or damaged mail states. Pcmail's design has been directed by the characteristics of currently available workstations. Some workstations are fairly portable, and can be packed up and moved in the back seat of an automobile. A few are truly portable--about the size of a briefcase--and battery- powered. Some workstations have constant access to a high-speed local-area network; pcmail should allow for "on-line" mail delivery for these machines while at the same time providing "batch" mail delivery for other workstations that are not always connected to a network. Portable and semi-portable workstations tend to be resource-poor. A typical IBM PC has a small amount (typically less than one megabyte) of main memory and little in the way of mass storage (floppy-disk drives that can access perhaps 360 kilobytes of data). Pcmail must be able to provide machines like this with ade- quate mail service without hampering its performance on more resource-rich workstations. Finally, all workstations have some com- mon characteristics that Pcmail should take advantage of. For in- stance, workstations are fairly inexpensive compared to the various time-shared systems that most people use for mail service. This means that people may own more than one workstation, perhaps putting a Microvax in an office and an IBM PC at home. Pcmail's design reflects the differing characteristics of the various workstations. Since one person can own several workstations, Pcmail allows users multiple access points to their mail state. Each Pcmail user can have several client workstations, each of which can access the user's mail by communicating with the repository over a network. The clients all maintain local copies of the user's global mail state, and synchronize the local and global states using DMSP. It is also possible that some workstations will only infrequently be Clark & Lambert [Page 2] RFC 993 December 1986 connected to a network (and thus be able to communicate with the re- pository). The Pcmail design therefore allows two modes of communi- cation between repository and client. "Interactive mode" is used when the client is always connected to the network. Any changes to the client's local mail state are immediately also made to the repository's global mail state, and any incoming mail is immediately transmitted from repository to client. "Batch mode" is used by clients that have infrequent access to the repository. Users manipu- late the client's local mail state, queueing the changes locally. When the client is next connected to the repository, the changes are executed, and the client's local mail state is synchronized with the repository's global mail state. Finally, the Pcmail design minimizes the effect of using a resource- poor workstation as a client. Mail messages are split into two parts: a "descriptor" and a "body". The descriptor is a capsule mes- sage summary whose length (typically about 100 bytes) is independent of the actual message length. The body is the actual message text, including an RFC-822 standard message header. While the client may not have enough storage to hold a complete set of messages, it can usually hold a complete set of descriptors, thus providing the user with at least a summary of his mail state. For clients with extreme- ly limited resources, Pcmail allows the storage of partial sets of descriptors. Although this means the user does not have a complete local mail state, he can at least look at summaries of some messages. In the cases where the client cannot immediately store message bo- dies, it can always pull them over from the repository as storage be- comes available. The remainder of this document is broken up into sections discussing the following: - The repository architecture - DMSP, its operations, and motivation for its design - The client architecture - A typical DMSP session between the repository and a client - The current Pcmail implementation 3. Repository architecture A typical machine running repository code has a relatively powerful processor and a large amount of disk storage. It must also be a per- manent network site, for two reasons. First clients communicate with the repository over a network, and rely on the repository's being available at any time. Second, people sending mail to repository users rely on the repository's being available to receive mail at any Clark & Lambert [Page 3] RFC 993 December 1986 time. The repository must perform several tasks. First, and most impor- tantly, the repository must efficiently manage a potentially large number of users and their mail states. Mail must be reliably stored in a manner that makes it easy for multiple clients to access the global mail state and synchronize their local mail states with the global state. Since a large category of electronic mail is represented by bulletin boards (bboards), the repository should effi- ciently manage bboard mail, using a minimum of storage to store bboard messages in a manner that still allows any user subscribing to the bboard to read the mail. Second, the repository must be able to communicate efficiently with its clients. The protocol used to com- municate between repository and client must be reliable and must pro- vide operations that (1) allow typical mail manipulation, and (2) support Pcmail's distributed nature by allowing efficient synchroni- zation between local and global mail states. Third, the repository must be able to process mail from sources outside the repository's own user community (a primary outside source is the Internet). In- ternet mail will arrive with a NIC RFC-822 standard message header; the recipient names in the message must be properly translated from the RFC-822 namespace into the repository's namespace. 3.1. Management of user mail state Pcmail divides the world into a community of users. Each user is re- ferred to by a user object. A user object consists of a unique name, a password (which the user's clients use to authenticate themselves to the repository before manipulating a global mail state), a list of "client objects" describing those clients belonging to the user, and a list of "mailbox objects". A client object consists of a unique name and a status. A user has one client object for every client he owns; a client cannot communi- cate with the repository unless it has a corresponding client object in a user's client list. Client objects therefore serve as a means of identifying valid clients to the repository. Client objects also allow the repository to manage local and global mail state synchroni- zation; the repository associates with every global state change a list of client objects corresponding to those clients which have not recorded the global change locally. A client's status is either "active" or "inactive". The repository defines inactive clients as those clients which have not connected to the repository within a set time period (one week in the current re- pository implementation). When an inactive client does connect to the repository, the repository notifies the client that it has been "reset". The repository resets a client by marking all messages in the user's mail state as having changed since the client last logged in. When the client next synchronizes with the repository, it will receive a complete copy of the repository's global mail state. A Clark & Lambert [Page 4] RFC 993 December 1986 forced reset is performed on the assumption that enough global state changes occur in a week that the client would spend too much time performing an ordinary local state-global state synchronization. Messages are stored in mailboxes. Users can have an arbitrary number of mailboxes, which serve both to store and to categorize messages. A mailbox object both names a mailbox and describes its contents. Mailboxes are identified by a unique name; their contents are described by three numeric values. The first is the total number of messages in the mailbox, the second is the total number of unseen messages (messages that have never been seen by the user via any client) in the mailbox, and the third is the mailbox's next available message unique identifier (UID). The above information is stored in the mailbox object to allow clients to get a summary of a mailbox's contents without having to read all the messages within the mailbox. Some mailboxes are special, in that other users may read the messages stored in them. These mailboxes are called "bulletin board mail- boxes" or "bboard mailboxes". The repository uses bboard mailboxes to store bboard mail. Bboard mailboxes differ from ordinary mail- boxes in the following ways: - Their names are unique across the entire repository; for instance, only one bboard mailbox named "sf-lovers" may exist in the entire repository community. This does not preclude other users from having an ordinary mailbox named "sf-lovers". - Subscribers to the bboard are granted read-only access to the messages in the bboard mailbox. The bboard mailbox's owner (typically the system manager) has read/update/delete access to the mailbox. A bboard subscriber keeps track of the messages he has looked at via a bboard object. The bboard object contains the name of the bboard, its owner (the user who owns the bboard mailbox where all the mes- sages are stored), and the UID of the first message not yet seen by the subscriber . Users gain read-only access to a bboard by "subscribing" to it; they lose that access when they "unsubscribe" to it. Associated with each mailbox are an arbitrary number of message ob- jects. Each message is broken into two parts--a "descriptor", which contains a summary of useful information about the message, and a "body", which is the message text itself, including its NIC RFC-822 message header. Each message is assigned a monotonically increasing UID based on the owning mailbox's next available UID. Each mailbox has its own set of UIDs which, together with the mailbox name and user name, uniquely identify the message within the repository. Clark & Lambert [Page 5] RFC 993 December 1986 A descriptor holds the following information: the message UID, the message size in bytes and lines, four "useful" message header fields (the "date:", "to:", "from:", and "subject:" fields), and sixteen flags. These flags are given identifying numbers 0 through: 15. Eight of these flags are reserved for the repository's use. Some of these are actually used by the repository, while others are simply held for informational purposes. In the current repository implemen- tation these flags mark: - (#0) whether it has been deleted - (#1) whether the message has been seen - (#2) whether it has been forwarded to the user - (#3) whether it has been forwarded by the user - (#4) whether it has been filed (written to a text file outside the repository) - (#5) whether it has been printed (locally or remotely) - (#6) whether it has been replied to - (#7) whether it has been copied to another mailbox The remaining eight flags are reserved for future use. Descriptors serve as an efficient means for clients to get message information without having to waste time retrieving the message from the repository. 3.2. Repository-to-RFC-822 name translation "Address objects" provide the repository with a means for translating the RFC-822-style mail addresses in Internet messages into repository names. The repository provides its own namespace for message iden- tification. Any message is uniquely identified by the triple (user- name, mailbox-name, message-UID). Any mailbox is uniquely identified by the pair (user-name, mailbox-name). Thus to send a message between two repository users, a user would address the message to (user-name, mailbox-name). The repository would deliver the message to the named user and mailbox, and assign it a UID based on the re- quested mailbox's next available UID. In order to translate between RFC-822-style mail addresses and repo- sitory names, the repository maintains a list of address objects. Each address object is an association between an RFC-822-style ad- dress and a (user-name, mailbox-name) pair. When mail arrives from the Internet, the repository can use the address object list to translate the recipients into (user-name, mailbox-name) pairs and Clark & Lambert [Page 6] RFC 993 December 1986 route the message correctly. 4. Communication between repository and client: DMSP The Distributed Mail System Protocol (DMSP) is a block-stream proto- col that defines and manipulates the objects mentioned in the previ- ous section. It has been designed to work with Pcmail's single- repository/multiple-client model of the world. In addition to pro- viding typical mail manipulation functions, DMSP provides functions that allow easy synchronization of global and local mail states. DMSP is implemented on top of the Unified Stream Protocol (USP), specified in MIT-LCS RFC-272. USP provides a reliable virtual cir- cuit block-stream connection between two machines. It defines a basic set of data types ("strings", "integers", "booleans", etc.); instances of these data types are grouped in an application-defined order to form USP blocks. Each USP block is defined by a numeric "block type"; a USP application can thus interpret a block's contents based on knowledge of the block's type. DMSP consists of a set of operations, each of which is comprised of one or more different USP blocks that are sent between repository and client. A DMSP session proceeds as follows: a client begins the session with the repository by opening a USP connection to the repository's machine. The client then authenticates both itself and its user to the repository with a "login" operation. If the authentication is successful, the user performs an arbitrary number of DMSP operations before ending the session with a "logout" operation (at which time the connection is closed by the repository). Because DMSP can manipulate a pair of mail states (local and global) at once, it is extremely important that all DMSP operations are failure-atomic. Failure of any DMSP operation must leave both states in a consistent, known state. For this reason, a DMSP operation is defined to have failed unless an explicit acknowledgement is received by the operation initiator. This acknowledgement can take one of two basic forms, based on two broad categories that all DMSP operations fall into. First, an operation can be a request to perform some mail state modification, in which case the repository will acknowledge the request with either an "ok" or a "failure" (in which case the reason for the failure is also returned). Second, an operation can be a re- quest for information, in which case the request is acknowledged by the repository's providing the information to the client. Operations such as "delete a message" fall into the first category; operations like "send a list of mailboxes" fall into the second category. Following is a general discussion of all the DMSP operations. The operations are broken down by type: general operations, user opera- tions, client operations, mailbox operations, address operations, bboard operations, and message operations. Clark & Lambert [Page 7] RFC 993 December 1986 4.1. General operations The first group of DMSP operations perform general functions that operate on no one particular class of object. DMSP has two general operations, which provide the following services: In order to prevent protocol version skew between clients and the re- pository, DMSP provides a "send-version" operation. The client sup- plies its DMSP version number as an argument; the operation succeeds if the supplied version number matches the repository's DMSP version number. It fails if the two version numbers do not match. The ver- sion number is an unsigned quantity, like "100", "101", "200". The "send-version" operation should be the first that a client sends to the repository, since no other operation my work if the client and repository are using different versions of DMSP. Users can send mail to other users via the "send-message" operation. The message must have an Internet-style header as defined by NIC RFC-822. The repository takes the message and distributes it to the mailboxes specified on the "to:", "cc:", and "bcc:" fields of the message header. If one or more of the mailboxes exists outside the repository's user community, the repository is responsible for hand- ing the message to a local SMTP server. An OK is sent from the repository only if the entire message was suc- cessfully transmitted. If the message was destined for the Internet, the send-message operation is successful if the message was success- fully transmitted to the local SMTP server. 4.2. User operations The next series of DMSP operations manipulates user objects. The most common of these operations are "login" and "logout". A client must perform a login operation before being able to access a user's mail state. A DMSP login block contains five items: (1) the user's name, (2) the user's password, (3) the name of the client performing the login, (4) a flag telling the repository to create a client ob- ject for the client if one does not exist, and (5) a flag set to TRUE if the client wishes to operate in "batch mode" and FALSE if the client wishes to operate in "interactive" mode. The flag value al- lows the repository to tune internal parameters for either mode of operation. The repository can return either an OK block (indicating successful authentication), a FAILURE block (indicating failed authentication), or a FORCE-RESET block. This last is sent if the client logging in has been marked as "inactive" by the repository (clients are marked inactive if they have not connected to the repository in over a week). The FORCE-RESET block indicates that the client should erase its local mail state and pull over a complete version of the repository's mail state. This is done on the assumption that so many Clark & Lambert [Page 8] RFC 993 December 1986 mail state changes have been made in a week that it would be ineffi- cient to perform a normal synchronization. When a client has completed a session with the repository, it per- forms a logout operation. This allows the repository to perform any necessary cleanup before closing the USP connection. A user can change his password via the "set-password" operation. The operation works much the same as the UNIX change-password operation, taking as arguments the user's current password and a desired new password. If the current password given matches the user's current password, the user's current password is changed to the new password given. 4.3. Client operations DMSP provides four operations to manipulate client objects. The first, "list-clients", tells the repository to send the user's client list to the requesting client. The list takes the form of a series of (client-name, status) pairs. The status is either 0 (inactive) or 1 (active). The "create-client" operation allows a user to add a client object to his list of client objects. Although the login operation duplicates this functionality via the "create-this-client?" flag, the add-client operation is a useful means of creating a number of new client ob- jects while logged into the repository via an existing client. The create-client operation requires the name of the client to add. The "delete-client" operation removes an existing client object from a user's client list. The client being removed cannot be in use by anyone at the time. The last client operation, "reset-client", causes the repository to mark all messages in the user's mail state as having changed since the client last logged in. When a client next synchronizes with the repository, it will end up receiving a complete copy of the repository's global mail state. This is useful for two reasons. First, a client's local mail state could easily become lost or dam- aged, especially if it is stored on a floppy disk. Second, if a client has been marked as inactive by the repository, the reset- client operation provides a fast way of resynchronizing with the re- pository, assuming that so many differences exist between the local and global mail states that a normal synchronization would take far too much time. 4.4. Mailbox operations DMSP supports five operations that manipulate mailbox objects. First, "list-mailboxes" has the repository send to the requesting client information on each mailbox. This information consists of the Clark & Lambert [Page 9] RFC 993 December 1986 mailbox name, total message count, unseen message count, and "next available UID". This operation is useful in synchronizing local and global mail states, since it allows a client to compare the user's global mailbox list with a client's local mailbox list. The list of mailboxes also provides a quick summary of each mailbox's contents without having the contents present. The "create-mailbox" has the repository create a new mailbox and at- tach it to the user's list of mailboxes. An address object binding the (user-name, mailbox-name) pair to an RFC-822-style address is au- tomatically created and placed in the repository's list of address objects. This allows mail coming from the Internet to be correctly routed to the new mailbox. "Delete-mailbox" removes a mailbox from the user's list of mailboxes. All messages within the mailbox are also deleted and permanently re- moved from the system. Any address objects binding the mailbox name to RFC-822-style mailbox addresses are also removed from the system. "Reset-mailbox" causes the repository to mark all the messages in a named mailbox as having changed since the current client last saw them. When the client next synchronizes with the repository, it will receive a complete copy of the named mailbox's mail state. This operation is merely a more specific version of the reset-client operation (which allows the client to pull over a complete copy of the user's global mail state). Its primary use is for mailboxes whose contents have accidentally been destroyed locally. Finally, DMSP has an "expunge-mailbox" operation. Any message can be deleted and "undeleted" at will. Deletions are made permanent by performing an expunge-mailbox operation. The expunge operation causes the repository to look through a named mailbox, removing from the system any messages marked "deleted". 4.5. Address operations DMSP provides three operations that allow users to manipulate address objects. First, the "list-address" operation returns a list of ad- dress objects associated with a particular (user-name, mailbox-name) pair. The "create-address" operation adds a new address object that associ- ates a (user-name, mailbox-name) pair with a given RFC-822-style mailbox address. Finally, the "delete-address" operation destroys the address object binding the given RFC-822-style mail address and the given (user- name, mailbox-name) pair. Clark & Lambert [Page 10] RFC 993 December 1986 4.6. Bboard operations DMSP provides seven bulletin board operations. The first, "list- bboards", gives the user a list of the bboards he is currently sub- scribing to. The list contains an entry for each bboard that the user subscribes to. Each entry contains the following information: - The bulletin board's name - The UID of the first message the subscriber has not yet seen - The highest message UID in the bulletin board - The number of messages the subscriber has not yet seen "List-all-bboards" gives the user a list of all bboards he can sub- scribe to. "Create-bboard" allows a user to create a bboard mailbox. The name given must be unique across the entire repository user community. Once the bboard mailbox has been created, other users may subscribe to the bboard, using bboard objects to keep track of which messages they have read on which bboards. "Delete-bboard" allows a bboard's owner to delete a bboard mailbox. Subscribers who attempt to read from a bboard mailbox after it has been deleted are told that the bboard no longer exists. DMSP also provides operations to subscribe to, and unsubscribe from, any bboard. "Subscribe-bboard" adds a bboard object to the users bboard object list; "unsubscribe-bboard" removes a bboard object from the list. Note that this does not delete the bboard mailbox (obvi- ously only the bboard's owner can do that). It merely removes the user from the list of the bboard's subscribers. DMSP allows for the user to tell the repository which messages in a bboard he has seen. Every bboard object contains the UID of the first message the user has not yet seen; the "set-first-unread- message-UID" operation updates that number, insuring that the user sees a given bboard message only once. 4.7. Message operations The most commonly-manipulated Pcmail objects are messages; DMSP therefore provides special message operations to allow efficient syn- chronization, as well as a set of operations to perform standard message-manipulation functions. In the following paragraphs, the terms "message" and "descriptor" will be used interchangeably. A user may request a series of descriptors with the "get-descriptors" Clark & Lambert [Page 11] RFC 993 December 1986 operation. The series is identified by a pair of message UIDs, representing the lower and upper bounds of the list. Since UIDs are defined to be monotonically increasing numbers, a pair of UIDs is sufficient to completely identify the series of descriptors. If the lower bound UID does not exist, the repository starts the series with the first message with UID greater than the lower bound. Similarly, if the upper bound does not exist, the repository ends the series with the last message with UID less than the upper bound. If certain UIDs within the series no longer exist, the repository (obviously) does not send them. The repository returns the descriptors in a se- quence of "choices". Elements of the sequence can either be descrip- tors, in which case the choice is tagged as a descriptor, or they can be notification that the requested message has been expunged subse- quent to the client's last connection to the repository. A descrip- tor choice is a record containing the message's UID, flags, to, from, date, and subject fields, length in bytes, and length in lines. An expunged choice contains only the expunged message's UID. The "get-changed-descriptors" operation is intended for use during state synchronization. Whenever a descriptor changes state (is deleted, for example), the repository notes those clients which have not yet recorded the change locally. Get-changed-descriptors has the repository send to the client a given number of descriptors which have changed since the client's last synchronization. The list sent begins with the earliest-changed descriptor. Note that the list of descriptors is only guaranteed to be monotonically increasing for a given call to "get-changed-descriptors"; messages with lower UIDs may be changed by other clients in between calls to "get-changed- descriptors". Once the changed descriptors have been looked at, a user will want to inform the repository that the current client has recorded the change locally. The "reset-changed-descriptors" causes the repository to mark as "seen by current client" a given series of descriptors. The series is identified by a low UID and a high UID. UIDs within the series that no longer exist are not reset. Message bodies are transmitted from repository to user with the "get-message-text" operation. The separation of "get-descriptors" and "get-message-text" operations allows clients with small amounts of disk storage to obtain a small message summary (via "get- descriptors" or "get-changed-descriptors") without having to pull over the entire message. Frequently, a message may be too large for some clients to store lo- cally. Users can still look at the message contents via the "print- message" operation. This operation has the repository send a copy of the message to a named printer. The printer name need only have meaning to the particular repository implementation; DMSP transmits the name only as a means of identification. Clark & Lambert [Page 12] RFC 993 December 1986 Copying of one message into another mailbox is accomplished via the "copy-message" operation. A descriptor list of length one, contain- ing a descriptor for the copied message is returned if the copy operation is successful. This descriptor is required because the copied message acquires a UID different from the original message. The client cannot be expected to know which UID has been assigned the copy, hence the repository's sending a descriptor containing the UID. 5. Client Architecture Clients can be any of a number of different workstations; Pcmail's architecture must therefore take into account the range of charac- teristics of these workstations. First, most workstations are much more affordable than the large computers currently used for mail ser- vice. It is therefore possible that a user may well have more than one. Second, some workstations are portable and they are not expect- ed to be constantly tied into a network. Finally, many of the small- er workstations resource-poor, so they are not expected to be able to store a significant amount of state information locally. The follow- ing subsections describe the particular parts of Pcmail's client ar- chitecture that address these different characteristics. 5.1. Multiple clients The fact that Pcmail users may own more than one workstation forms the rationalization for the multiple client model that Pcmail uses. A Pcmail user may have one client at home, another at an office, and maybe even a third portable client. Each client maintains a separate copy of the user's mail state, hence Pcmail's distributed nature. The notion of separate clients allows Pcmail users to access mail state from several different locations. Pcmail places no restric- tions on a user's ability to communicate with the repository from several clients at the same time. Instead, the decision to allow several clients concurrent access to a user's mail state is made by the repository implementation. 5.2. Synchronization Some workstations tend to be small and fairly portable; the likeli- hood of their always being connected to a network is relatively small. This is another reason for each client's maintaining a local copy of a user's mail state. The user can then manipulate the local mail state while not connected to the network (and the repository). This immediately brings up the problem of synchronization between lo- cal and global mail states. The repository is continually in a posi- tion to receive global mail state updates, either in the form of in- coming mail, or in the form of changes from other clients. A client that is not always connected to the net cannot immediately receive the global changes. In addition, the client's user can make his own changes on the local mail state. Clark & Lambert [Page 13] RFC 993 December 1986 Pcmail's architecture allows fast synchronization between client lo- cal mail states and the repository's global mail state. Each client is identified in the repository by a client object attached to the user. This object forms the basis for synchronization between local and global mail states. Some of the less common state changes in- clude the adding and deleting of user mailboxes and the adding and deleting of address objects. Synchronization of these changes is performed via DMSP list operations, which allow clients to compare their local versions of mailbox and address object lists with the repository's global version and make any appropriate changes. The majority of possible changes to a user's mail state are in the form of changed descriptors. Since most users will have a large number of messages, and message states will change relatively often, special attention needs to be paid to message synchronization. An existing descriptor can be changed in one of two ways: first, one of its sixteen flags values can be changed (this encompasses reading an unseen message, deleting a message, and expunging a message). The second way to change a descriptor is via the arrival of incoming mail or the copying of a message from one mailbox to another. Both result in a new message being added to a mailbox. In both the above cases, synchronization is required between the re- pository and every client that has not previously noted a change. To keep track of which clients have noticed a global mail state change and changed their local states accordingly, each mailbox has associ- ated with it a list of active clients. Each client has a (potential- ly empty) "update list" of messages which have changed since that client last read them. When a client connects to the repository, it executes a DMSP "get- changed-descriptors" operation. This causes the repository to return a list of all descriptor objects on that client's update list As the client receives the changed descriptors, it can store them locally, thus updating the local mail state. After a changed descriptor has been recorded, the client uses the DMSP "reset-descriptors" operation to remove the message from its update list. That descriptor will now not be sent to the client unless (1) it is explicitly requested, or (2) it changes again. In this manner, a client can run through its user's mailboxes, get- ting all changed descriptors, incorporating them into the local mail state, and marking the change as recorded. 5.3. Batch operation versus interactive operation Because of the portable nature of some workstations, they may not al- ways be connected to a network (and able to communicate with the re- pository). Since each client maintains a local mail state, Pcmail users can manipulate the local state while not connected to the repo- sitory. This is known as "batch" operation, since all changes are Clark & Lambert [Page 14] RFC 993 December 1986 recorded by the client and made to the repository's global state in a batch, when the client next connects to the repository. Interactive operation occurs when a client is always connected to the repository. In interactive mode, changes made to the local mail state are also immediately made to the global state via DMSP operations. In batch mode, interaction between client and repository takes the following form: the client connects to the repository and sends over all the changes made by the user to the local mail state. The repo- sitory changes its global mail state accordingly. When all changes have been processed, the client begins synchronization, to incor- porate newly-arrived mail, as well as mail state changes by other clients, into the local state. In interactive mode, since local changes are immediately propagated to the repository, the first part of batch-type operation is elim- inated. The synchronization process also changes; although one syn- chronization is required when the client first opens a connection to the repository, subsequent synchronizations can be performed either at the user's request or automatically every so often by the client. 5.4. Message summaries Smaller workstations may have little in the way of disk storage. Clients running on these workstations may never have enough room for a complete local copy of a user's global mail state. This means that Pcmail's client architecture must allow user's to obtain a clear pic- ture of their mail state without having all their messages present. Descriptors provide message information without taking up large amounts of storage. Each descriptor contains a summary of informa- tion on a message. This information includes the message UID, its length in bytes and lines, its status (encoded in the eight system- defined and eight user-defined flags), and portions of its RFC-822 header (the "to:", "from:", "subject:" and "date:" fields). All of this information can be encoded in a small (around 100 bytes) data structure whose length is independent of the size of the message it describes. Most clients should be able to store a complete list of message descriptors with little problem. This allows a user to get a com- plete picture of his mail state without having all his messages present locally. If a client has extremely limited amounts of disk storage, it is also possible to get a subset of the descriptors from the repository. Short messages can reside on the client, along with the descriptors, and long messages can either be printed via the DMSP print-message operation, or specially pulled over via the fetch- message-text operation. Clark & Lambert [Page 15] RFC 993 December 1986 6. Typical interactive-style client-repository interaction The following example describes a typical communication session between the repository and a client. The client is one of three be- longing to user "Fred". Its name is "office-client", and since Fred uses the client regularly to access his mail, the client is marked as "active". Fred has two mailboxes: "main" is where all of his current mail is stored; "archive" is where messages of lasting importance are kept. The example will run through a simple synchronization opera- tion followed by a series of typical mail state manipulations. Typi- cally, the synchronization will be performed by an application pro- gram that connects to the repository, logs in, synchronizes, and logs out. For the example, all DMSP operations will be shown in a user-readable format. In reality, the operations would be sent as a stream of USP blocks consisting of a block-type number followed by a stream of bytes representing the block's components. In order to access his global mail state, the client software must authenticate Fred to the repository; this is done via the DMSP login operation: login ["fred", "fred-password", "office-client", F, F] This tells the repository that Fred is logging in via "office- client", and that "office-client" is identified by an existing client object attached to Fred's user object. The first component of the login block is Fred's repository user name. The second component is Fred's password. The third component is the name of the client com- municating with the repository. The fourth component tells the repo- sitory not to create "office-client" even if it cannot find its client object. The final component tells the repository that Fred's client is not operating in batch mode but rather in interactive mode. Fred's authentication checks out, so the repository logs him in, ack- nowledging the login request with an OK block. Now that Fred is logged in, the client performs an initial synchroni- zation. This process starts with the client's asking for an up-to- date list of mailboxes: list-mailboxes [] The repository replies with: mailbox-list [["main", 10, 1, 253], ["archive", 100, 0, 101]] This tells the client that there are two mailboxes, "main" and "ar- chive". "Main" has 10 messages, one of which is unseen. The next Clark & Lambert [Page 16] RFC 993 December 1986 incoming message will be assigned a UID of 253. "Archive", on the other hand, has 100 message, none of which are unseen. The next mes- sage sent to "archive" will be assigned the UID 101. There are no new mailboxes in the list (if there were, the client program would create them. On the other hand, if some mailboxes in the client's local list were not in the repository's list, the program would as- sume them deleted by another client and delete them locally as well). To synchronize the client need only look at each mailbox's contents to see if (1) any new mail has arrived, or (2) if Fred changed any messages on one of his other two clients subsequent to "office- client"'s last connection to the repository. The client asks for any changed descriptors via the "get-changed- descriptors" operation. It requests at most ten changed descriptors since storage is very limited on "office-client". get-changed-descriptors ["main", 10] The repository responds with: descriptor-list [[descriptor[ 6, [T T F F F F F F F F F F F F F F], "Fred@borax", "Joe@fab", "Wed, 23 Jan 86 11:11 EST", "tomorrow's meeting", 621, 10]] [descriptor[ 10, [F T F F F F F F F F F F F F F F], "Fred", "Freds-secretary", "Fri, 25 Jan 86 11:11 EST", "Monthly progress report", 13211, 350]] ] The first descriptor in the list is one which Fred deleted on another client yesterday. "Office-client" marks the local version of the message as deleted. The second descriptor in the list is a new one. "Office-client" adds the descriptor to its local list. Since both changes have now been recorded locally, the descriptors can be reset: reset-descriptors ["main", 6, 10] Clark & Lambert [Page 17] RFC 993 December 1986 The repository removes from "office-client"'s update list all mes- sages with UIDs between 6 and 10 (in this case just two messages) "Main" has now been synchronized. The client now turns to Fred's "archive" mailbox and asks for the first ten changed descriptors. get-changed-descriptors ["archive", 10] The repository responds with descriptor-list [] The zero-length list tells "office-client" that no descriptors have been changed in "archive" since its last synchronization. No new synchronization needs to be performed. Fred's client is now ready to pull over the new message. The message is 320 lines long; there might not be sufficient storage on "office- client" to hold the new message. The client tries anyway: fetch-message-text ["main", 10] The repository begins transmitting the message: message ["From: Fred's-secretary", "To: Fred", "Subject: Monthly progress report", "Date: Fri, 25 Jan 86 11:11 EST", "", "Dear Fred,", "Here is this month's progress report", ... ] Halfway through the message transmission, "office-client" runs out of disk space. Because all DMSP operations are defined to be failure- atomic, the portion of the message already transmitted is destroyed locally and the operation fails. "Office-client" informs Fred that the message cannot be pulled over because of a lack of disk space. The synchronization process is now finished and Fred can start read- ing his mail. The new message that was too big to fit on "office- client" will be marked "off line"; Fred can either remote-print it or delete other messages until he has enough space to store the new mes- sage. Since he is running in interactive mode, changes he makes to any mes- sages will immediately be transmitted into DMSP operations and sent to the repository. Depending on the client implementation, Fred will either have to execute a "synchronize" command periodically or the client will synchronize for him automatically every so often. Clark & Lambert [Page 18] RFC 993 December 1986 7. A current Pcmail implementation The following section briefly describes a current Pcmail system that services a small community of users. The Pcmail repository runs under UNIX on a DEC VAX-750 connected to the Internet. The clients run on IBM PCs, XTs, and ATs, as well as Sun workstations, Micro- vaxes, and VAX-750s. 7.1. IBM PC client code Client code for the IBM machines operates only in batch mode. Users make local state changes, which are queued until the client connects to the repository. At that time, the changes are performed and the local and global states synchronized. The client then disconnects from the repository. Users access and modify their local mail state via a user interface program. The program uses windows and a full-screen mode of opera- tion. Users are given a variety of commands to operate on individual messages as well as mailboxes. The interface allows use of any text editor to compose messages, and adds features of its own to make RFC-822-style header composition easier. Synchronization and the processing of queued changes is performed by a separate program, which the user runs whenever he wishes. The pro- gram takes any actions queued while operating the user interface, and converts them into DMSP operations. All queued changes are made be- fore any synchronization is performed. The limitation of IBM PC client operation to batch mode was made be- cause of development environment limitations. The user interface could not work with the network code inside it due to program size limitations. Since MS-DOS has no multi-processing facilities, the two programs could not run in tandem either. The only solution was to provide a two-part client, one part of which read the mail and one part of which interacted with the repository. 7.2. UNIX client code Client code for the Suns, Microvaxes, and VAX-750s runs on 4.2/4.3BSD UNIX. It is fully interactive, with a powerful user interface inside Richard Stallman's GNU-EMACS editor. Since UNIX-based workstations have a good deal of main memory and disk storage, no effort was made to lower local mail state size by keeping message descriptors rather than message text. The local mail state consists of a number of BABYL-format mailboxes. The interface is very similar to the RMAIL mail reader already present in GNU-EMACS. The user interface communicates with the repository through a DMSP Clark & Lambert [Page 19] RFC 993 December 1986 implementation built into the GNU-EMACS kernel. Changes to the local mail state are immediately made on the repository; the repository is fast enough that there is little noticeable delay in performing the operation over the network. There is no provision for automatic synchronization whenever new mail arrives or old mail is changed by another client. Instead, users must get any new mail explicitly. A simple "notification" program runs in the background and wakes up every minute to check for new mail; when mail arrives, the user executes a command to get the new mail, synchronizing the mailbox at the same time. 7.3. Repository code The repository is implemented in C on 4.2/4.3BSD UNIX. Currently it runs on DEC VAX-750s and Microvaxes, although other repositories will soon be running on IBM RT machines and Sun workstations. The reposi- tory code is designed to allow several clients belonging to a partic- ular user to "concurrently" modify the user's state. A mailbox lock- ing scheme prevents one client from modifying a mailbox while another client is modifying the same mailbox. 8. Conclusions Pcmail is now used by a small community of people at the MIT Labora- tory for Computer Science. The repository design works well, provid- ing an efficient means of storing and maintaining mail state for several users. Its performance is quite good when up to ten users are connected; it remains to be seen whether or not the repository will be efficient at managing the state of ten or a hundred times that many users. Given sufficient disk storage, it should be able to, since communication between different users' clients and the re- pository is likely to be very asynchronous and likely to occur in short bursts with long "quiet intervals" in between as users are busy doing other things. Members of another research group at LCS are currently working on a replicated, scalable version of the repository designed to support a very large community of users with high availability. This reposito- ry also uses DMSP and has successfully communicated with clients that use the current repository implementation. DMSP therefore seems to be usable over several flavors of repository design. The IBM PC clients are unfortunately very limited in the way of resources, making local mail state manipulation difficult at times. Synchronization is also relatively time consuming due to the low per- formance of the PCs. The "batch-mode" that the PCs use tends to be good for those PCs that spend a large percentage of their time un- plugged and away from a network. It is somewhat inconvenient for those PCs that are always connected to a network and could make good use of an "interactive-mode" state manipulation. Clark & Lambert [Page 20] RFC 993 December 1986 The UNIX-based clients are far easier to use than their PC counter- parts. Synchronization is much faster, and there is far more func- tionality in the user interface (having an interface that runs within GNU-EMACS helps a lot in this respect). Most of those people using the Pcmail system use the UNIX-based client code. APPENDIX A. DMSP Protocol Specification Following are a list of DMSP operations by object type, their block types and arguments, and their expected acknowledgement block types. Each DMSP block has a different number; the first digit of each block type defines the object being manipulated: Operations numbered 5xx are general, operations numbered 6xx are user operations, operations numbered 7xx are client operations, operations numbered 8xx are mail- box operations, operations numbered 9xx are address operations, operations numbered 10xx are bboard operations, and operations num- bered 11xx are message operations. Failure blocks contain two fields, a "code" and a "why". The "code" is an unsigned number placing the error in one of several broad categories (listed below). The "why" is a text string, possibly ex- plaining the error in greater detail. Error codes: - 1: network error while reading or writing data - 2: internal repository error. This can be due to lack of memory, a fatal bug, lack of disk space, etc. - 3: requested object already exists. For example, you tried to create a mailbox that already exists - 4: requested object not found. For example, you tried to delete a message or a mailbox that doesn't exist. - 5: protocol error. Typically DMSP protocol version skew. - 6: block argument error. For example, a "set-message-flag" operation was attempted on a bboard by someone other than the bboard's owner. - 7: data read error. The repository was unable to read the mail state information requested. Clark & Lambert [Page 21] RFC 993 December 1986 - 8: data write error. The repository was unable to write out changed mail state information, perhaps because the disk was full. - 9: operating system error: Should be reserved for things like fork or pipe call errors. - 10: unexpected or unknown block type received. For example, you sent a "delete-mailbox" block and received a "mailbox-list" block in response. Blocks marked "=>" flow from client to repository; blocks marked "<=" flow from repository to client. If more than one block can be sent, the choices are delimited by "or" ("|") characters. For clarity, each block type is put in a human-understandable form. The block number is followed by an operation name; this name is never transmitted as part of a USP block. Block arguments are identified by name and type, and enclosed in square brackets. "Record" data types are described by a list of "field-name:field-type" pairs con- tained in square brackets. "Choice" data types are described by a list of "tag-name:tag-type" pairs contained in square brackets. USP data types are defined as follows (the definitions are brief; refer to the USP specification for more detailed descriptions): A.1. Primitive data types string (S): a series of bytes, null-byte padded to even length and preceded by a 16-bit length specifier. Strings are sent in "net- ascii" format (newline sequence is carriage return followed by linefeed, single carriage returns to be followed by a null byte). - cardinal (C): a 16-bit unsigned number. - long-cardinal (LC): a 32-bit unsigned number. - integer (I): a 16-bit signed number. - long-integer (LI): a 32-bit signed number. - boolean (B): a 16-bit number with either a 1 or a 0 in the 16th bit. A.2. Compound data types - sequence (SEQ): A list of data items, all the same type and preceded by a 16-bit sequence length specifier. Clark & Lambert [Page 22] RFC 993 December 1986 - array (AR): A fixed-length list of data items, all the same type. A particular array's length is fixed by the application. - record (REC): A list of data items of any type. A particular record's format is fixed by the application. - choice (CH): One of a list of possible data types. The data type contained in the choice is identified by a 16-bit numeric tag. The application interprets the data item based on the tag value. A.3. DMSP Abstract Data Types Following are data types defined and used only by DMSP: - client: a record with the following format: REC[name:S, status:C] Status is either 1 (active) or 0 (inactive) - mailbox: a record with the following format: REC[name:S, next-uid:LC, #msgs:C, #new-msgs:C] - bboard: a record with the following format: REC[name:S, first-unread-message-UID:LC number-of-unseen-messages:C highest-UID:LC] - descriptor: a record with the following format: - REC[UID:LC, flags:SEQ[B], from, to, date, subject:S, #bytes:LC, #lines:LC] - desc-choice: a choice with the following format: CH[expunged-message-UID:LC, desc:descriptor] Descriptor tag number is 1. Expunged-message tag number is 0. A.4. General operations => 502 (send-version) [version:C] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 503 (send-message) [message:SEQ[S]] <= 500 (ok) [] | 501 (failure) [code:C, why:S] Clark & Lambert [Page 23] RFC 993 December 1986 A.5. User operations => 600 (login) [name:S, password:S, client:S, create-client-object?:B batch-mode?:B] <= 500 (ok) [] | 501 (failure) [code:C, why:S] | 705 (force-client-reset) [] => 601 (logout) [] <= 500 (ok) [] => 602 (set-password) [old:S, new:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] A.6. Client operations => 701 (list-clients) [] <= 700 (client-list) [client-list:SEQ[client]] => 702 (create-client) [client:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 703 (delete-client) [client:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 704 (reset-client) [client:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] A.7. Mailbox operations => 801 (list-mailboxes) [] <= 800 (mailbox-list) [mailbox-list:SEQ[mailbox]] => 802 (create-mailbox) [mailbox:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 803 (delete-mailbox) [mailbox:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] Clark & Lambert [Page 24] RFC 993 December 1986 => 804 (reset-mailbox) [mailbox:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 805 (expunge-mailbox) [mailbox:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S A.8. Address operations => 901 (list-addresses) [mailbox:S] <= 501 (failure) [code:C, why:S] | 900 (address-list) [address-list:SEQ[S]] => 902 (create-address) [mailbox:S, address:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 903 (delete-address) [mailbox:S, address:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] A.9. Bboard operations => 1001 (list-bboards) [] <= 1000 (bboard-list) [bboard-list:SEQ[bboard]] 501 (failure) [code:C, why:S] => 1002 (create-bboard) [name:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1003 (delete-bboard) [name:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1004 (subscribe-bboard) [name:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1005 (unsubscribe-bboard) [name:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] Clark & Lambert [Page 25] RFC 993 December 1986 => 1006 (set-bboard-first-unread) [name:S, UID:LC] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1007 (list-all-bboards) [] <= 1008 (bboard-name-list) [bboard-name-list:SEQ[S]] 501 (failure) [code:C, why:S] A.10. Message operations => 1102 (get-descriptors) [mailbox:S, low-uid:LC, high-uid:LC] <= 501 (failure) [code:C, why:S] | 1100 (desc-list) [desc-list:SEQ[desc-choice]] => 1103 (get-changed-descriptors) [mailbox:S, max-to-send:C] <= 501 (failure) [code:C, why:S] | 1100 (desc-list) [desc-list:SEQ[desc-choice]] => 1104 (reset-changed-descriptors) [ mailbox:S, start-uid:LC, end-uid:LC] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1105 (get-message-text) [mailbox:S, uid:LC] <= 501 (failure) [code:C, why:S] | 1101 (message) [message:SEQ[S]] => 1106 (print-message) [mailbox:S, uid:LC, printer-name:S] <= 500 (ok) [] | 501 (failure) [code:C, why:S] => 1107 copy-message[source-mailbox:S, target-mailbox:S, source-uid:LC] <= 501 (failure) [code:C, why:S] <= 501 (failure) [code:C, why:S] | 1100 (desc-list) [desc-list:SEQ[desc-choice]] Clark & Lambert [Page 26] RFC 993 December 1986 => 1108 (set-flag) [mailbox:S, uid:LC, flag-number:C, flag-setting:B] <= 500 (ok) [] | 501 (failure) [code:C, why:S] 30 DMSP block types by number General block types ok 500 failure 501 send-version 502 send-message 503 User operation block types login 600 logout 601 set-password 602 Client operation block types client-list 700 list-clients 701 create-client 702 delete-client 703 reset-client 704 force-client-reset 705 Mailbox operation block types mailbox-list 800 list-mailboxes 801 create-mailbox 802 delete-mailbox 803 reset-mailbox 804 expunge-mailbox 805 Address operation block types address-list 900 list-addresses 901 create-address 902 delete-address 903 Clark & Lambert [Page 27] RFC 993 December 1986 Bboard operation block types bboard-list 1000 list-bboards 1001 create-bboard 1002 delete-bboard 1003 subscribe-bboard 1004 unsubscribe-bboard 1005 set-bboard-first-unread 1006 get-n-new-bboard-descriptors 1007 list-all-bboards 1008 bboard-name-list 1009 Message operation block types descriptor-list 1100 message 1101 get-descriptors 1102 get-changed-descriptors 1103 reset-changed-descriptors 1104 get-message-text 1105 print-message 1106 copy-message 1107 set-flag 1108 Clark & Lambert [Page 28]