# AltaVista Mail administration protocols

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.

# Contents

1. Administration protocols
2. Entities and attributes
   1. Syntaxes
   2. Entities
      1. Environment
      2. Server
      3. Mailbox
      4. Domain
      5. Log
      6. Message
3. Native administration protocol
   1. States
   2. Commands
   3. Responses
   4. Example session
4. HTTP/HTML administration protocol
   1. Server-parsed HTML
   2. Additional entities and attributes
      1. Mailbox
      2. Domain
      3. Log
      4. Event
   3. Form actions and result data
   4. URLs offered by AltaVista Mail

# Introduction

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.

# Entities and attributes

## Syntaxes

Syntaxes used in this section are:

- IP address: IP address in the form `[a.b.c.d]`.

- Domain name: DNS domain name, in the usual dotted notation. If the name is a hostname, an address in the form `[a.b.c.d]` is also acceptable.

- Natural: A non-negative integer.

- Interval: A number of seconds. A negative value means infinity, but not all uses of this syntax accept an infinite value.

- Client type: A colon-separated string giving a name and description for the kind of client program that serves a mailbox. Predefined client types supported by the AltaVista Mail server are:

  - "POP3: Post Office Protocol"

    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.

  - "IMAP: Internet Message Access Protocol"

    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.

  - "List: manually maintained mailing list"

    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).

- Message identifier: An opaque string giving an identifier for a stored message.

- String: Any string.

- Address: A user address in RFC 821 format (user@domain.name). Source routing format (@domain.name,...:user@domain.name) is not supported through the administration protocols, though AltaVista Mail respects it on message submission.

- Password: A colon-separated string giving an authentication method and password. Two authentication methods are currently defined, cleartext and MD5; the password "bad-password" with each method would be:

  - Clear: bad-password
  - MD5: bad-password

- Privilege: A string, one of:

  - Administration

    Administration privilege grants full administration rights.

  - Monitor

    Monitor privilege grants the right to view administration information but not to change anything, read mail, or write to any log.

  - ReadAllMail

    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

    WriteLog privilege grants the right to write to any log file.

- Username and redirection: A colon-separated string containing a username and an optional redirection address. The username may be a string, possibly quoted, or may be a full Address including a domain name. It may also contain a leading '*', denoting a wildcard; if it does, the first '*' in any redirection address will be replaced during redirection by whatever string was matched by the '*' in the username.

- Member: A colon-separated string containing an Address and optional client-specific data.

- Mailbox name: A name for a mailbox in the form `name`[`@superior-name`...]".

  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.

- Date and time: Timestamp in RFC 821 format:

  - [day`,` ]dd mon yyyy hh`:`mm`:`ss sHH`:`MM

  where:

  - day is one of: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`
  - dd is the one- or two-digit day
  - mon is one of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`
  - yyyy is the four-digit year
  - hh is the two-digit hour
  - mm is the two-digit minute
  - ss is the two-digit second
  - s is `+` or `-`
  - HH is the two-digit hour ahead of or behind UTC
  - MM is the two-digit minute ahead of or behind UTC.

- Set of type: Multiple values of type type, in no specific order.

- Sequence of type: Multiple values of type type, in some specific order.

## Entities

The managed entities are:

- Environment
- Server
- Mailbox[ mailbox-name]
- Domain[ domain-name]
- Log[ log-name]
- Message message-id.

### Environment

The Environment entity is a representation of the local host environment. Its attributes are:

- Hostname - String

  The short (not fully-qualified) name of the local host. If this can't be discovered, the attribute is not present.

- Domain - Domain name

  The local host's domain.

- FullyQualifiedDomainName - Domain name

  The local host's fully-qualified domain name.

- Addresses - Set of IP address

  The IP addresses of the local host.

- DnsAddresses - Set of IP address

  The addresses of the DNS servers used by the host. If these can't be discovered, the attribute is not present.

### Server

The Server entity is a representation of the AltaVista Mail server itself. Attributes of the server provide global configuration information.

Server attributes are:

- FirewallHost - Domain name

  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.

- MailServerHost - Domain name
- Aliases - Set of Domain name

  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.

- RouterMaximumHops - Natural

  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.)

- WorkPollInterval - Interval
- ConfigurationPollInterval - Interval
- CleanupInterval - Interval

  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.

- SenderMinimumRetryInterval - Interval
- SenderMaximumRetryInterval - Interval

  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.

- SmtpTimeoutInitial220 - Interval
- SmtpTimeoutMail250 - Interval
- SmtpTimeoutRcpt250 - Interval
- SmtpTimeoutData354 - Interval
- SmtpTimeoutDataWrite - Interval
- SmtpTimeoutDot250 - Interval
- SmtpTimeoutCommand - Interval
- SmtpTimeoutAck - Interval

  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.

- MessageExpiryInterval - Interval

  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.

- EventExpiryInterval - Interval

  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.

- ClientTypes - Set of Client type

  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.

- Messages - Set of Message identifier (read-only)

  This attribute lists the messages being routed, or waiting to be routed, by the AltaVista Mail server.

- Attributes - Set of String (read-only)

  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.

### Mailbox[ mailbox-name]

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:

- Password - Password (write-only)

  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.

- ReportTarget - Address

  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.

- Privileges - Set of 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.

- Usernames - Set of Username and redirection

  This attribute gives the usernames that the mailbox serves. A username is normally the local part of an RFC 821 address (local-part@domain), but it can be the whole address. This is useful when multiple domains are served (through MX records in DNS) by the local host: the same local part can be served by multiple mailboxes as long as the domain differs.

  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

  - `*%ccmail: *%cc@gwhost.some.domain`

  will cause mail sent to `Some.User%ccmail@local.host` to be redirected to `Some.User%cc@gwhost.some.domain`.

  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.

- DefaultRedirection - Address

  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.

- Members - Set of Member

  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.

- ClientType - Client type

  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.

- FinalDestination - Natural

  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.

- Pop3LockedOutUntil - Date and time (read-only)
- ImapLockedOutUntil - Date and time (read-only)
- AdministrationLockedOutUntil - Date and time (read-only)

  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.

- Messages - Set of Message identifier (read-only)

  This attribute lists the messages in the mailbox. Any messages present are waiting to be fetched by the client.

- Mailboxes - Set of Mailbox name (read-only)

  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.

- Attributes - Set of String (read-only)

  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.

### Domain[ domain-name]

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:

- RetryTime - Date and time (read-only)

  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.

- RetryInterval - Interval (read-only)

  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.

- Messages - Set of Message identifier (read-only)

  This attribute lists the messages waiting to be transferred to the domain.

- Domains - Set of Domain name (read-only)

  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.

- Attributes - Set of String (read-only)

  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.

### Log[ log-name]

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:

- AdministrationOperations: this records all administration operations that modify state.

- Errors: this records all errors encountered by AltaVista Mail and the client programs that use its API.

- ImapOperations: this records every IMAP connection and message operation. This log was added in version 2.0 of the AltaVista Mail software, and version 2 of the administration protocol.

- MessageOperations: this records every operation on messages.

- Pop3Operations: this records every POP3 connection and message operation.

- Security: this records all events relevant to security.

- SmtpOperations: this records every SMTP connection and message operation.

Log attributes are:

- Attributes - Set of String (read-only)

  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.

- Logs - Set of String (read-only)

  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.

### Message message-id

A Message entity is a representation of a message currently stored in the server. Attributes are:

- UpdateTime - Date and time (read-only)

  The time at which the message was last updated.

- Text - Sequence of String

  The full text of the message.

- ReportTarget - Address (read-only)

  The message's reverse path (normally the originator, but actually the destination for any non-delivery reports).

- Recipients - Sequence of

  ## States

  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.

  ## Commands

  In logged-out/command state, the commands available to the initiator are:

  - version protocol-version
    protocol-version is a natural number denoting the version required

    Request a specific version of the administration protocol. This document describes protocol versions 1 and 2.

  - proxy address ip-address
  - proxy hostname hostname
    ip-address is an IP address in the form `[a.b.c.d]`

    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.

  - login method method-parameters
    method is a string denoting an authentication method
    method-parameters are space-separated parameters specific to the authentication method

    Identify the initiating client's mailbox and enter the logged-in/command state. The response to a successful login is always:

    - +OK mailbox-name

    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:

    - Clear username password
    - MD5 username MD5-hash

    where

    - username is one of the usernames served by the mailbox to be logged in to
    - password is the mailbox's cleartext password
    - MD5-hash is an MD5 hash of the mailbox's password followed by the challenge given the responder's initial greeting message (see the POP3 protocol definition for details)

  - help

    Give help on the commands available in logged-out/command state. Enter the data substate to transfer the help text.

  - quit

    Disconnect the session.

  - write log log-name
    log-name is the name of an event log

    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.

  - lookup username

    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:

    - +OK mailbox-name

    An unsuccessful lookup will yield a failure response. If the failure is because the user does not exist, the response is:

    - -NoSuchObject comment

    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:

  - proxy address ip-address
  - proxy hostname hostname
    ip-address is an IP address in the form `[a.b.c.d]`

    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.

  - logout

    Enter logged-out state without disconnecting.

  - help

    Give help on the commands available in logged-in/command state. Enter the data substate to transfer the help text.

  - quit

    Disconnect the session.

  - test server

    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 domain domain-name
    domain-name is a fully-qualified domain name denoting a remote mail target, or an address in the form `[a.b.c.d]`

    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 mailbox mailbox-name
    mailbox-name is a name for the mailbox

    Create a mailbox, a place where mail can be delivered and an identity for a specific instance of a client program.

  - delete mailbox mailbox-name

    Delete a mailbox.

  - add entity
    entity is one of:
    - mailbox mailbox-name
    - server
    - domain domain-name
    - log log-name

    Add values to attributes of an entity. If successful, enter the attribute substate to accept lines of the form:

    - attribute-name: attribute-value

    where:

    - attribute-name is the name of an attribute supported by the entity
    - attribute-value is a value for the attribute

  - remove entity

    Remove values from attributes of an entity. If successful, enter the attribute substate to accept lines of the form:

    - attribute-name[: attribute-value]

    If no value is provided, remove all values. If no values remain, remove the attribute.

  - set entity

    Assign or replace the values of attributes of an entity. If successful, enter the attribute substate to accept lines of the form:

    - attribute-name[: attribute-value]

    If no value is provided, remove the attribute.

  - show entity

    Show the values of attributes of an entity. Additional entity values are:

    - environment
    - message message-id

    where:

    - message-id is a message's identifier

    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:

    - attribute-name: maximum-values

    and for each line, enter the data substate to transfer values, one to each data line.

  - read log log-name [maximum-entry-age]
    maximum-entry-age is an interval in seconds

    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 log log-name

    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.

  - lookup username

    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:

    - +OK mailbox-name

    An unsuccessful lookup will yield a failure response. If the failure is because the user does not exist, the response is:

    - -NoSuchObject comment

  - reset message message-id Reprocess a message, that is, run it through the routing process again.

  - reset domain domain-name

    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 mailbox mailbox-name

    Reset a mailbox, that is, remove any record of breakin attacks to the mailbox so that future connections will be accepted.

  - delete glug 1
  - glug 2

- $url(text)

  This converts its argument text to a form that can be used in a URL: any special characters are replaced by their numeric equivalents.

- $directory(expression)

  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.

## Additional entities and attributes

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.

### Mailbox[?Mailbox=mailbox-name]

The Mailbox entity has a new attribute:

- Superior - String

  This is the name of the mailbox's superior. It is empty if the mailbox has no superior.

### Domain[?Domain=domain-name]

The Domain entity has a new attribute:

- Superior - String

  This is the name of the domain's superior. It is empty if the domain has no superior.

### Log[?Log=log-name]

The Log entity has a new attribute:

- Events - Sequence of String

  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:

  - MaximumAge - Interval

    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.

  - Forever - Natural

    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.

### Event?Log=log-name&Event=event-id

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:

- Text - Sequence of String (read-only)

  The full text of the event.

- Date - Date and time (read-only)

  The date and time at which the event was posted.

- Event-ID - String (read-only)

  A unique identifier for the event. This identifier will never again be allocated by the host.

- Attributes - Set of String (read-only)

  A list of the names of the parameters actually present in the event.

## Form actions and result data

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.

## URLs offered by AltaVista Mail

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 hostname is host to manage username is the administrator's username method is the authentication method, 'Clear' or 'MD5' password is the administrator's password proxy-address is the browser's IP address
/avmail/Logout ?Sid=sid |  | Invalidates a session sid is a session-id, avmail/Login's Sid output parameter
/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 verbose is 1 or empty; if 1, all text is returned. Otherwise, an empty string is returned on success and a non-empty summary on failure.
/avmail/Test/Domain ?Sid=sid&ProxyAddress="proxy-address" &Domain=domain-name [&Verbose="1"] | Value | Tests SMTP access to the dmain domain-name is a domain name, or a host address in the form `[a.b.c.d]`
/avmail/Create/Mailbox ?Sid=sid&ProxyAddress="proxy-address" &Mailbox=mailbox-name [Superior=mailbox-name] [Attributes="attribute-name+..." &attribute-name="value"...] | ErrorMessage | Creates a mailbox mailbox-name is a mailbox name attribute-name is any attribute name value is a value for that attribute
/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 message-id is a message-id, a value read from the Messages attribute of a server, mailbox, or domain
/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 writable-entity is 'Server', 'Mailbox[?Mailbox=mailbox-name]', 'Domain[?Domain=domain-name]', or 'Log[?Log=log-name]' attribute-name is any attribute name
/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 readable-entity is 'Server', 'Mailbox[?Mailbox=mailbox-name]', 'Domain[?Domain=domain-name]', 'Log[?Log=log-name]', 'Event?Log=log-name ?Event=event-id', or 'Message?Message=message-id event-id is an event-id, a value read from the Events attribute of a log qualifier-name is the name of an attribute that qualifies the search qualifier-value is its value