Amandad Service Protocol

This article describes the way that amandad launches services like sendsize or amidxtaped. Amanda serves as a sort of amanda-specific inetd, but adds support for multiple parallel communication channels, authentication, and lots of crazy backward-compatibility hacks.

Note that most of amandad's activity takes place at connection set-up. There may be other pages on this wiki to describe the protocol observed by particular sevices. For example, amindexd protocol describes the protocol that amidxtaped speaks, and takes over where this page leaves off. Amandad is always on the receiving end of the Security API, so a familiarity with that API will help in reading this document.

Service Launch

File Descriptors

When amandad launches a service, the following file descriptors are open:

0 (stdin)

read any request arguments here

1 (stdout)

write a REP packet body here (see below)

2 (stderr)

error messages

50 (DATA_FD_OFFSET + 0*2 + 0)

write fd for first stream

51 (DATA_FD_OFFSET + 0*2 + 1)

read fd for first stream

52 (DATA_FD_OFFSET + 1*2 + 0)

write fd for second stream

53 (DATA_FD_OFFSET + 1*2 + 1)

read fd for second stream

54 (DATA_FD_OFFSET + 2*2 + 0)

write fd for third stream

55 (DATA_FD_OFFSET + 2*2 + 1)

read fd for third stream

more data streams can be added if necessary: they are limited by DATA_FD_COUNT, which is currently 3.

Note that OpenBSD's fake thread libraries have trouble dealing with nonstandard file descriptors open at process start; use fcntl(F_GETFD) to "notify" the runtime of these file descriptors before using them.

Command-line Arguments

The service is run with the following command-line arguments:

service amandad auth

and with a stripped-down, "safe" environment. The executable name is the name of the service, and must reside in the

REQ Packet

The request packet sent from the client has its first two words and newline stripped. The first must be SERVICE, and the second the name of the service. The remainder of the request packet appears on the stdin of the service, and are service-specific. The end of the packet data is signalled by EOF on stdin.

Note that any subsequent identical REQ packets are assumed to be duplicates and discarded.

REP Packet

Before using any other file descriptors, the service must send a REP packet on its stdout, signalling the end of the packet with EOF.

Any output written to stderr will become ERROR lines in the REP packet. If the process exits at this point, and the exit is abormal, then amandad will add appropriate ERROR lines to the REP packet.

There is a hard-coded limit of 6 hours for a REP packet, after which amandad will abandon the attempt and send a NAK to the server.

The REP packet is "transformed" by amandad before being sent on to the server: First, if it begins with "KENCRYPT\n" then amandad will initiate kerberos encryption to the server. This line is removed from the REP packet.

If the remaining packet body begins with "CONNECT ", then that line is presumed to contain a description of the desired security streams, specified by tags and integers:

CONNECT GOOD 50 BAD 52 UGLY 51

This is where it gets crazy - these integers look like file descriptors, but they are not! They are indexes to *pairs* of file descriptors. If N is the integer supplied, then the write file descriptor is 50+(N-50)*2, and the read file descriptor is 51+(N-50)*2. To spell that out a bit:

N	write fd	read fd
50	50	51
51	52	53
52	54	55

This makes reading the code very confusing. Welcome to Amanda. Enjoy your stay.

For each file descriptor in the CONNECT line, amandad creates a new (bidirectional) security stream and translates the integer into a stream id, resulting in something like:

CONNECT GOOD 49241 BAD 49240 UGLY 49238

Any integers specified as -1 are passed through unchanged, although it's not clear why this would be useful.

The REP packet is then sent via the Security API. Note that any output to stderr after the REP is sent will be silently discarded.

When an ACK is received, amandad sets up to forward data between the security stream and the file descriptor. If there was no CONNECT line, amandad kills the service and returns to its base state.

Service-Specific Hacks

Conceptually, amandad is a general service-dispatch tool. In practice, it has a lot of special cases for particular services.

Wait for process to exit before relaying REP

sendsize

selfcheck

noop

Amandad waits up to five seconds for these processes to exit cleanly after they have sent a REP but before that REP is sent on to the other end of the Security API connection.

Send partial replies (P_PREP)

sendsize

For the sendsize service, amandad assumes that the request packet begins with an OPTIONS line, and parses those options. If the options include fe_partial_estimate, then a P_PREP packet wil be sent each time the service writes data to its stdout, even if no EOF is received. Note that while this resets the etimeout timer on the server, it does not reset the 6 hour REP timeout in amandad.

Send data last

sendbackup

Dumper assumes that it will receive at least some MESG or INDEX data from sendbackup before it receives any DATA. Amandad ensures that this is the case by not paying attention to sendbackup's fd 50 until it sees the string "sendbackup info end" in the MESG stream.

Old (inetd-based) Services

Two services, amidxtaped and amindexd, can also be launched directly from inetd. This is used to support old (Amanda-2.5.0 and before) amrecover implementations (source code now hidden under oldrecover-src/).

The specifics of this mode are described in the pages for the services themselves - see Amidxtaped protocol.