B. The Sockmap Protocol

Sockmap is a simple request/reply protocol over TCP or UNIX domain sockets. Both requests and replies are encoded in the following manner:

 
 len:text,

where text is the actual payload, and len is its length in bytes, as a decimal number in ASCII representation. The colon and comma are transmitted verbatim. For example, if text is the string ‘hello there’, then the socket map packet for transmitting it is:

 
11:hello there,

Sockmap requests consist of the map name and the actual lookup key, separated by a single space character.

Replies consist of the status code and optional data, separated by a single space character.

Below we describe status codes implemented by various programs. The bracketed parts in the ‘code’ field of the tables below indicate optional values. The brackets themselves are not required by the protocol.

B.1 Sendmail Status Codes

Status codes understood by Sendmail are:

Code Meaning
OK [result] the key was found; result contains the looked up value.
NOTFOUND the key was not found
TEMP [reason] a temporary failure occurred; optional reason field contains an explanatory message.
TIMEOUT [reason] same as ‘TEMP’.
PERM a permanent failure occurred

Table B.1: Sendmail Status Codes

B.2 MeTA1 Status Codes

MeTA1 further extends the protocol. The result codes it understands are:

Code Meaning
OK [result] the key was found; result contains the looked up value.
NOTFOUND the key was not found
NOMORE the key was not found, stop further search
TEMP [reason] a temporary failure occurred; optional reason field contains an explanatory message.
TIMEOUT [reason] same as ‘TEMP’.
PERM [reason] a permanent failure occurred; optional reason field contains an explanatory message.

Table B.2: MeTA1 Status Codes

The ‘NOMORE’ status indicates that the key has not been found and also instructs MTA(10) to stop any further searches using this key and its derivatives.

B.3 Mailfromd Status Codes

Mailfromd does not itself require any particular status codes. The allowed status codes depend entirely on your filter program.

Footnotes

(10)

To be precise, the smar, a component responsible for resolving various things for MeTA1.