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)

??

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

If the process exits at this point, and the exit is abormal, then amandad will formulate an appropriate ERROR

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.