Digital (TM) Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the descriptions.
Possession, use, or copying of the AltaVista Mail software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.
Copyright © Digital Equipment Corporation 1996.
This document describes the administration protocols used by the AltaVista Mail server.
| Protocol versions: | 1, 2 |
| Software versions: | 1.0, 2.0 |
| Document revision number: | 2.0 |
| Document revision date: | 13 September 1996 |
If you intend to use this document to help in building an application to control AltaVista Mail, we strongly encourage you to contact the AltaVista Mail engineering support address, altavista-mail@digital.com, to discuss your requirements. We'll be happy to offer advice, example programs, and any updates to this reference information.
AltaVista Mail supports two separate administration protocols: a native protocol, and HTTP/HTML. The native protocol provides fine-grained control over every attribute of the system. The HTTP/HTML version is built on top of the native protocol and permits higher-level administration through the browser of user choice. It allows server-side user extension of administration functions by modifying the HTML pages supplied with AltaVista Mail.
Both protocols operate on a handful of managed entities and manipulate the attributes of those entities.
A mailbox with this client type is served by the built-in POP3 server. (The POP3 server will actually serve any client with a Password attribute, so this value is used primarily to document the intended use of the mailbox.) The different kinds of POP3 client - Eudora or E-Mail Connection, for example - need not be individually identified: they all share this type.
A mailbox with this client type is served by the built-in IMAP server. The different kinds of IMAP client - Embla or Simeon, for example - need not be individually identified: they all share this type.
This client type was added in version 2.0 of the AltaVista Mail software and version 2 of the administration protocol.
A mailbox with this client type is a mailing list. Mail delivered to the mailbox will be forwarded to the addresses in the mailbox's Members attribute. Other types of mailing list may be supported by clients added on to AltaVista Mail.
Other client types are added to AltaVista Mail by its clients (gateways, list servers, redirectors and some mail user agents).
Administration privilege grants full administration rights.
Monitor privilege grants the right to view administration information but not to change anything, read mail, or write to any log.
ReadAllMail privilege grants the right to read all mail in the system using the administration protocol (via the Show Message command or its HTTP/HTML equivalent).
WriteLog privilege grants the right to write to any log file.
Mailboxes are organized in a hierarchy, and mailbox names reflect this.
The arrangement of the hierarchy is not significant to AltaVista Mail itself: it simply allows huge numbers of mailboxes to be supported. If there are more than about a thousand mailboxes at a level, that level should probably be split to improve the performance of the underlying file system.
Otherwise, the hierarchy is arranged to suit the administrator; mailboxes should go where they'll be found easily.
where:
The managed entities are:
The Environment entity is a representation of the local host environment. Its attributes are:
The short (not fully-qualified) name of the local host. If this can't be discovered, the attribute is not present.
The local host's domain.
The local host's fully-qualified domain name.
The IP addresses of the local host.
The addresses of the DNS servers used by the host. If these can't be discovered, the attribute is not present.
The Server entity is a representation of the AltaVista Mail server itself. Attributes of the server provide global configuration information.
Server attributes are:
If the local network uses a firewall for outbound connections to the wider Internet, direct connections between the local host and hosts outside the organization will fail. Mail bound for the wider Internet must therefore be sent via the firewall.
This attribute gives the outbound firewall's name. It can be a hostname, or can be a domain name MX-served by one or more other hosts. Whenever mail cannot be sent to any of its target hosts, the firewall will be tried as an alternative destination.
A full SMTP service needs access to the Domain Name Service (DNS) to route mail. If the local host has no full-time access to DNS, for example because it has intermittent dialup access to the Internet, it can still run AltaVista Mail, but must have messages routed by a remote mail server. The MailServerHost attribute gives the mail server's name.
The Aliases attribute gives aliases for the local host. Aliases would normally be detected during DNS lookup processing, but if the local host is served by a mail server, it doesn't perform DNS lookups, and must be told its aliases using this attribute.
It is possible to set up routing, redirection and mailing list expansion loops, where messages circulate forever without making any progress. AltaVista Mail counts the number of hops a message has made, and non-delivers any that have exceeded a maximum value. This attribute gives the maximum value. (To give non-delivery reports the maximum chance of reaching their target, they are allowed twice as many hops.)
AltaVista Mail is constructed as a set of largely autonomous threads, each with a limited and well-defined purpose. When one finishes processing a message, it leaves it in an area where the next thread will find it. There is no notification path to inform a thread that new work has arrived; instead each thread looks at its input area at regular intervals. The WorkPollInterval attribute attribute gives the interval used.
Similarly, whenever the AltaVista Mail configuration changes, for example when a new mailbox is added, there is no direct path to tell it of the change. Instead it checks for new configuration information at regular intervals; ConfigurationPollInterval says how frequently.
Finally, the CleanupInterval attribute says how often AltaVista Mail should perform its housekeeping operations, for example deleting old temporary files and performing consistency checks.
When AltaVista Mail fails to make a connection to a remote host, it will not try again to connect to the same host until a retry interval has expired. If this is the first failure, the retry interval is given by the SenderMinimumRetryInterval attribute. On each subsequent failure, the retry interval is doubled, until the value reaches that given by the SenderMaximumRetryInterval attribute, when it stays at that value. If a connection succeeds, the retry interval used on any subsequent failure will be the minimum value.
These timeouts govern how long AltaVista Mail will wait for the individual SMTP protocol operations to complete before it decides that the remote system is not responding.
A message being processed by the server will normally be transferred or delivered within a reasonable time, normally minutes but possibly hours if a required remote host is inaccessible or if DNS is unavailable for a while.
Continuing unavailability of a gateway or remote host, or incorrect, inappropriate or inaccessible routing instructions in DNS, may mean messages cannot be processed no matter how long the server keeps trying. AltaVista Mail will therefore non-deliver any messages after they've been waiting to be routed or transferred for longer than the time given by the MessageExpiryInterval attribute.
AltaVista Mail logs all its operations and errors. The events that appear in the logs can be retrieved for some time after being logged. This attribute gives the time that any event is guaranteed to remain available for viewing after it's been logged; to make room for new events, it will be deleted at some point after this interval expires.
This attribute is a list of the kinds of client known to the server. It is set up by installation and deinstallation programs (of AltaVista Mail itself, and of its client programs), and is used by the administration user interface programs to determine what values to offer for a mailbox's ClientType attribute.
This attribute lists the messages being routed, or waiting to be routed, by the AltaVista Mail server.
This attribute gives a list of names of the attributes of the server - that is, this list. It is used by administration user interface programs to detect non-builtin attributes; that is, attributes the UI program doesn't understand but over which it may want to offer control.
A mailbox is a is a storage area for messages awaiting delivery to a client of the AltaVista Mail server, together with some information about that client.
Clients are typically mail user agents, gateways and mail redirectors, but administration programs are also clients. The primary use for an administration program's mailbox is to authenticate connections from the program, not to receive mail.
Mailbox attributes are:
A password is used by the POP3, IMAP and administration servers to authenticate inbound connections claiming administration privilege or the right to fetch messages from the mailbox. (A client doesn't need to authenticate itself with the server to submit mail, only to fetch it; SMTP offers no assurance of originator identity.)
A client program can write the password for the mailbox it's authenticated itself against: the mailbox does not need Administration privilege.
When a client expands a mailing list or redirects a recipient, this attribute will be used as a replacement value for the return path (the destination for any non-delivery reports generated by the new message) of the message being processed. This allows delivery problems with, say, mailing lists, to be reported to the owner of the list or to a client that will automatically edit the list to remove the offending addresses.
Non-delivery reports (messages with a null return path) will not have their return paths replaced. This prevents non-delivery loops, where reports circulate endlessly.
A client program can read and write the report target for the mailbox it's authenticated itself against: the mailbox does not need Administration privilege.
A client program making an administration connection and successfully authenticating with the mailbox will be granted these administration privileges.
A client program can read the privileges for the mailbox it's authenticated itself against: the mailbox does not need Administration or Monitor privilege.
This attribute gives the usernames that the mailbox
serves. A username is normally the local part of an
For each username, a redirection address can be provided. If delivery is made to the username, the message will not be left in the mailbox but will instead be redirected to the redirection address.
A username can start with a '*' character. This is a wildcard: it matches any leading string. If there's also a redirection address, the first '*' in that address will be replaced by the matching string. So, for example, the username and redirection record
will cause mail sent to
A client program can read (but not write) the usernames for the mailbox it's authenticated itself against: the mailbox does not need Administration or Monitor privilege.
Any mail delivered to the mailbox that doesn't undergo per-username redirection (see the Usernames attribute) will be redirected to the address given in this attribute if it's present.
A client program can read and write the default redirection for the mailbox it's authenticated itself against: the mailbox does not need Administration privilege.
The Members attribute constitutes a directory of users associated with the mailbox.
It is used by mailboxes that represent mailing lists, either the type built into AltaVista Mail or one implemented by an external client program. The Members attribute gives the members of the list: mail sent to the mailbox will be forwarded to all the addresses in the Members attribute.
Members may also be of use to other types of client, for example gateways: the members can give the list of addresses of users permitted to send mail through the gateway.
A client program can read and write the members for the mailbox it's authenticated itself against: the mailbox does not need Administration privilege.
This attribute gives the name and description of the kind of program that serves the client. If present, its value is drawn from the set given by the server's ClientTypes attribute.
A client program can read (but not write) the client type for the mailbox it's authenticated itself against: the mailbox does not need Administration or Monitor privilege.
This attribute describes whether the mailbox is a final destination for any messages delivered to it. If the attribute is missing or has a zero value, the mailbox is not a final destination. If it has a value of "1", the mailbox is a final destination.
AltaVista Mail does not allow messages in transit to stay in the server for a long time. Any message that has made no progress for the duration given by the server's Message Expiry Interval attribute is non-delivered to make sure the originator knows it hasn't got through. Also, if a message in transit is deleted using the Delete Message command, AltaVista Mail will return a report to the originator to say so: unexplained message loss would be a very serious problem.
Mailboxes used for transferring messages to gateways need to share this behaviour: if a message stays in a gateway's mailbox for a long time, it means that the gateway isn't working, or it isn't able to process that message. Either way, the message needs to be non-delivered because it's not making any progress. Such mailboxes are not final destinations; messages there are still in transit.
Mailboxes that are used for delivery to users' mail programs generally should not be treated in this way: it's entirely up to the user how frequently mail is fetched, and even after fetching mail the user may choose to leave it in the mailbox forever. Such mailboxes are final destinations.
These attributes, if present, indicate that the mailbox has suffered possible breakin attempts on their respective protocols: there have been several recent failures to authenticate against the mailbox, and the mailbox has locked itself out. Until the time given by the attribute, even login attempts that quote the correct credentials will be refused.
Lockouts affect only the attacker's address: a login attempt from a host that hasn't caused login failures will succeed. You cannot tell from this attribute alone which hosts are affected; read the Security log to find out.
A lockout can be cleared with the Reset Mailbox command.
This attribute lists the messages in the mailbox. Any messages present are waiting to be fetched by the client.
The Mailboxes attribute gives the names of the mailbox's subordinate mailboxes: for a mailbox called 'm', the subordinate mailboxes are all those whose names end with '@m'. To find the names of the topmost mailboxes (the ones that have no superior), read the Mailboxes attribute of the root mailbox: this is a mailbox with a null name.
This attribute gives a list of names of the attributes of the mailbox - normally this list, plus any client-specific attributes set up by the client program itself. It is used by administration user interface programs to detect non-builtin or client-specific attributes; that is, attributes the UI program doesn't understand but over which it may want to offer control.
A client program can read the attributes for the mailbox it's authenticated itself against: the mailbox does not need Administration or Monitor privilege.
A Domain entity is a representation of a remote domain, a target for messages. Note that a domain isn't necessarily a remote host; a domain name can represent some service rather than an actual host, and the server uses lookups of MX records in the DNS to find out which actual hosts serve the target domain.
A domain entity appears when a message is enqueued for the domain, and disappears during a regular cleanup operation.
Domain attributes are:
This appears only on domains which correspond to remote hosts. If present, it means that the latest connection attempt to the host failed, and the value is the time at which the server will consider making a new connection to the host.
This appears only on domains which correspond to remote hosts. If present, it means that the latest connection attempt to the host failed, and if the next attempt fails the value will be added to the time of that attempt to schedule the next connection attempt.
This attribute lists the messages waiting to be transferred to the domain.
The Domains attribute gives the names of the domain's known subordinate domains: for the domain 'com', the subordinates might be 'dec.com', 'mci.com' and so on. To find the names of the topmost known domains ('com', 'gov', the country codes etcetera), read the Domains attribute of the root domain: this is a domain with a null name.
This attribute gives a list of names of the attributes of the domain - normally this list. It is used by administration user interface programs to detect non-builtin attributes; that is, attributes the UI program doesn't understand but over which it may want to offer control.
A Log entity is an activity log. It records all AltaVista Mail operations. There are administration operations to read and write logs.
The builtin logs are:
Log attributes are:
This attribute gives a list of names of the attributes of the log - normally this list. It is used by administration user interface programs to detect non-builtin attributes; that is, attributes the UI program doesn't understand but over which it may want to offer control.
Although logs are not organized as a hierarchy, you can enumerate the names of the logs as though they were. That is, read the Logs attribute of the root log: this is a log with a null name.
A Message entity is a representation of a message currently stored in the server. Attributes are:
The time at which the message was last updated.
The full text of the message.
The message's reverse path (normally the originator, but actually the destination for any non-delivery reports).
The protocol has two major states: logged-out and logged-in; and three substates: command, attribute and data.
On initial connection, a session starts in logged-out/command state. The login command enters the logged-in/command state, and the logout command returns to the logged-out/command state.
Commands that manipulate attributes (Add, Remove, Set and Show) enter the attribute substate.
This allows multiple attributes and/or attribute values of the single entity identified in the command to be processed one after another.After the command's initial success response, the initiator sends lines consisting of an attribute name and any data required. These lines are treated as commands, and the responder returns a response for each one. The initiator returns to the previous (command) substate by sending a line containing a single '.'. This is also treated as a command, and so yields a response.
Commands that can cause the transfer of multiple lines of data (currently Help, Test, and each line of the attribute substate of Show) enter the data substate.
After the command's initial success response, the sender transmits all the lines of data, followed by a line containing a single '.'. The sender adds to any data line whose first character is a '.' an extra '.' at the beginning of the line, and the receiver strips this extra '.' before using the line.
After the data and the terminating '.', the sender transfers a response line, to report errors encountered during the transfer, and hence indicate whether the data is complete and usable. Note that this response is sent by the sender of the data, not necessarily the protocol's responder (though in this version of the protocol only the responder sends data). After this response the protocol returns to the previous (command or attribute) substate.
In logged-out/command state, the commands available to the initiator are:
Request a specific version of the administration protocol. This document describes protocol versions 1 and 2.
Indicate that the connection is working on behalf of a remote host. These commands are available only to initiators on the same host as the responder.
Identify the initiating client's mailbox and enter the logged-in/command state. The response to a successful login is always:
where mailbox-name is the name of the mailbox used - this is not necessarily the same as the username given in the method's parameters.
Supported methods and their parameters are:
where
Give help on the commands available in logged-out/command state. Enter the data substate to transfer the help text.
Disconnect the session.
Write event data to a log, if necessary creating it first. After a successful response, all data written by the initiator is logged: no more commands will be accepted and the session must be disconnected to finish. This command is available in logged-out state only for initiators on the same host as the responder.
Look up the name of a local user, and return the name of the mailbox serving the user.
A successful lookup results in a response of:
An unsuccessful lookup will yield a failure response. If the failure is because the user does not exist, the response is:
This command is available in logged-out state only for initiators on the same host as the responder.
In logged-in/command state, the commands available to the initiator are:
Indicate that the connection is working on behalf of a remote host. These commands are available only to initiators on the same host as the responder.
Enter logged-out state without disconnecting.
Give help on the commands available in logged-in/command state. Enter the data substate to transfer the help text.
Disconnect the session.
Test the server. Enter the data substate to transfer a test report, and after the data yield a success or failure response according to whether the test passed or failed.
Test SMTP access to the named domain. Enter the data substate to transfer a test report, and after the data yield a success or failure response according to whether the test passed or failed.
Create a mailbox, a place where mail can be delivered and an identity for a specific instance of a client program.
Delete a mailbox.
Add values to attributes of an entity. If successful, enter the attribute substate to accept lines of the form:
where:
Remove values from attributes of an entity. If successful, enter the attribute substate to accept lines of the form:
If no value is provided, remove all values. If no values remain, remove the attribute.
Assign or replace the values of attributes of an entity. If successful, enter the attribute substate to accept lines of the form:
If no value is provided, remove the attribute.
Show the values of attributes of an entity. Additional entity values are:
where:
To discover message-ids, show the Messages attribute of any entity that can store messages.
If successful, enter the attribute substate to accept lines of the form:
and for each line, enter the data substate to transfer values, one to each data line.
Read event data from a log, optionally starting at some point in the past. After a successful response, log data is written by the responder as it arrives and no data is accepted from the initiator: no more commands will be accepted and the session must be disconnected to finish.
Write event data to a log, if necessary creating it first. After a successful response, all data written by the initiator is logged: no more commands will be accepted and the session must be disconnected to finish.
Look up the name of a local user, and return the name of the mailbox serving the user.
A successful lookup results in a response of:
An unsuccessful lookup will yield a failure response. If the failure is because the user does not exist, the response is:
Reset a domain. That is, allow new connections to be made to the hosts that serve the domain; if the domain is itself a host, allow a new connection to be made to the host itself; and if the domain is an IP address, remove any record of breakin attacks from the domain so that inbound connections will be accepted.
Reset a mailbox, that is, remove any record of breakin attacks to the mailbox so that future connections will be accepted.
This converts its argument text to a form that can be used in a URL: any special characters are replaced by their numeric equivalents.
This performs a directory listing, returning a newline-separated list of files whose names match the expression passed. A '*' character in this expression works as a wildcard, matching any number of characters. The scope of the listing is limited to the HTTP server's directory and subdirectories, with an initial directory separator (the '/' character) requesting its root. Expressions containing the '../' construct match no files.
The AltaVista Mail HTTP/HTML administration system supports all the entities and attributes exposed by the native administration protocol, and also adds a few new ones to support access in a manner convenient to HTML page definition.
All data returned by AltaVista Mail entities is encoded in an HTML-safe manner. That is, any HTML special characters are escaped so they are displayed rather than being interpreted by the browser.
The Mailbox entity has a new attribute:
This is the name of the mailbox's superior. It is empty if the mailbox has no superior.
The Domain entity has a new attribute:
This is the name of the domain's superior. It is empty if the domain has no superior.
The Log entity has a new attribute:
A list of identifiers of all the events in the log. Each identifier is an opaque string; it is not intended for display, only for referring to specific events in the log.
When showing this attribute, two search qualifiers are respected:
The maximum number of seconds in the past to search for events. The server will purge very old events; it guarantees to keep an event only for as long as the value of the server's EventExpiryInterval attribute.
If this has the value "1", the server will wait indefinitely for new events to arrive once all the stored event identifiers have been shown. A Show command never terminates if the Forever qualifier is set.
The Event entity is a new entity subordinate to a Log entity. It represents a specific event in the log. Its attributes are the parameters to the event, which vary according to the specific event but always include:
The full text of the event.
The date and time at which the event was posted.
A unique identifier for the event. This identifier will never again be allocated by the host.
A list of the names of the parameters actually present in the event.
A form action is a program executed externally to an HTTP server. It accepts input arguments in the form of variable names and values, and in a normal HTTP server, it generates a page of HTML to pass back to the requesting client.
The AltaVista Mail HTTP server must allow full customization of the user interface simply by editing HTML pages, so its forms cannot work in this way. Instead, a form's Action attribute (the "something" in <form action="something">) is actually the name of the HTML page to display after the form has been submitted.
The form submission itself involves making zero or more calls to the various AltaVista Mail components. A separate Action variable gives a newline-separated list of URLs denoting the calls to make.
Input parameters to the calls are given an a separate Attributes variable: this is a newline-separated list of variable names. Any output parameters, plus any input parameters that haven't been overwritten by a call, are finally made available to the next page to display: they appear as arguments to the page's URL. The server-parsed HTML support in the HTTP server allows the appearance and function of this new page to vary with the values of the arguments passed to it.
A call name given in an Action variable is a URL. There is no important distinction between a URL used as a form call and one used to read data; when a form has been submitted, all its action's output arguments are made available to the next page displayed, and when reading data (for example using the $inline(url) construct), the output argument called 'Value' is used, and any other output arguments are ignored.
The URLs correspond largely to commands in the native administration protocol, and operate on the same entities.
| URL and input arguments | Output arguments | Comments |
|
/avmail/Login
?Hostname="hostname" &Username="username" &Method="method" &Password="password" &ProxyAddress="proxy-address" |
Sid
ErrorMessage |
Creates a session for further operations
|
|
/avmail/Logout
?Sid=sid |
Invalidates a session
| |
|
/avmail/Session/Invalid Value
?Sid=sid&ProxyAddress="proxy-address" | Value | Returns "1" if session is invalid, otherwise nothing |
|
/avmail/Session/Mailbox Value
?Sid=sid&ProxyAddress="proxy-address" | Value | Returns the mailbox name associated with the session, "" if session is invalid |
|
/avmail/Test/Server
?Sid=sid&ProxyAddress="proxy-address" [&Verbose=verbose] | Value |
Tests the server
|
|
/avmail/Test/Domain
?Sid=sid&ProxyAddress="proxy-address" &Domain=domain-name [&Verbose="1"] | Value |
Tests SMTP access to the dmain
|
|
/avmail/Create/Mailbox
?Sid=sid&ProxyAddress="proxy-address" &Mailbox=mailbox-name [Superior=mailbox-name] [Attributes="attribute-name+..." &attribute-name="value"...] | ErrorMessage |
Creates a mailbox
|
|
/avmail/Delete/Mailbox
?Sid=sid&ProxyAddress="proxy-address" &Mailbox=mailbox-name | ErrorMessage | Deletes a mailbox |
|
/avmail/Reset/Message
?Sid=sid&ProxyAddress="proxy-address" &Message=message-id | ErrorMessage |
Sends a message back for routing again
|
|
/avmail/Reset/Mailbox
?Sid=sid&ProxyAddress="proxy-address" &Mailbox=mailbox-name | ErrorMessage | Removes attack records from a mailbox |
|
/avmail/Reset/Domain
?Sid=sid&ProxyAddress="proxy-address" &Domain=domain-name | ErrorMessage | Enables new connection to a domain |
|
/avmail/Set/writable-entity
?Sid=sid&ProxyAddress="proxy-address" [&Attributes="attribute-name+..." &attribute-name="value"...] | ErrorMessage |
Sets attributes of a server, mailbox, domain, or log
|
|
/avmail/Add/writable-entity
?Sid=sid&ProxyAddress="proxy-address" [&Attributes="attribute-name+...]" &attribute-name="value"...] | ErrorMessage | Adds values to an attribute of a server, mailbox, domain or log |
|
/avmail/Remove/writable-entity
?Sid=sid&ProxyAddress="proxy-address" [&Attributes="attribute-name+..." &attribute-name="value"...] | ErrorMessage | Removes values from an attribute of a server, mailbox, domain or log |
|
/avmail/Show/readable-entity
?Sid=sid&ProxyAddress="proxy-address" [&Attributes="attribute-name+..."] [&Qualifiers="qualifier-name+..." &qualifier-name=qualifier-value...] | Value |
Reads values of an attribute of a server, mailbox,
domain, log, or event
|