Amanda Protocol

When communicating over a Security API connection, the initiator makes requests of the target using the packet-based Amanda Protocol. This protocol grew out of the UDP days, so it includes lots of timeouts and retransmissions which are essentially superfluous in modern installations of Amanda.

Packet Types

There are five types of packet

REQ (0)

A request, with the following format (optionally prefixed with authentication information):

SERVICE servicename\n
OPTIONS options\n
service-specific information

The OPTIONS line generally describes the features supported by the initiator, the authentication mechanism in use, and so on.

REP (1)

A full reply to a request, and its format depends on the request.

PREP (2)

A partial reply to a request, indicating that the sender is still working and will reply later.

ACK (3)

An acknowledgement of a previous packet, containing no body.

NAK (4)

A negative acknowledgement, carrying a boddy with the form

ERROR errormessage\n

Packet Encoding

Packets are encoded as a single-byte type identifier, followed by a NUL-terminated string representing the body of the packet.

Protocol Definition

The protocol's only purpose is to start a service, and in some cases return results from that service. Only one such transaction may run at any time. The following sections describe the protocol states from the initiator's perspective.

sendreq

The process of starting a service begins by sending a REQ packet. After sending this packet, the initiator enters the ackwait state

ackwait

In this state, the initiator is waiting for an ACK packet, which indicates that the REQ was received, but does not contain any data. If an ACK is received, it goes to the repwait state. If a NAK is received, the transaction is over. If a REP or PREP is received, the ACK is presumed lost and processing continues as if in the repwait state. If no packet is received for 30 seconds, the protocol will return to sendreq to retransmit the REQ packet a total of req_tries times (see amanda.conf(5)) before failing the transaction (the famous "timeout waiting for ACK" error).

repwait

If a REP packet is received, send an ACK packet and complete the transaction. If a PREP packet is received, its contents are processed as a prefix of an as-yet-incomplete REP packet, but no ACK is sent and the protocol stays in the repwait state. If no packet is received for 60 seconds, the protocol will return to sendreq a total of two times, resettting the req_tries counter each time, although if a total of an hour has passed since the original REQ was sent, it will give up (this is the "DROP_DEAD_TIME").