Amandad Service Protocol: Difference between revisions
(save) |
(done?) |
||
Line 8: | Line 8: | ||
;0 (stdin):read any request arguments here | ;0 (stdin):read any request arguments here | ||
;1 (stdout):write a REP packet body here (see below) | ;1 (stdout):write a REP packet body here (see below) | ||
;2 (stderr): | ;2 (stderr):error messages | ||
;50 (DATA_FD_OFFSET + 0*2 + 0):write fd for first stream | ;50 (DATA_FD_OFFSET + 0*2 + 0):write fd for first stream | ||
;51 (DATA_FD_OFFSET + 0*2 + 1):read fd for first stream | ;51 (DATA_FD_OFFSET + 0*2 + 1):read fd for first stream | ||
Line 32: | Line 32: | ||
== REP Packet == | == 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 | Before using any other file descriptors, the service must send a REP packet on its stdout, signalling the end of the packet with EOF. | ||
If the process exits at this point, and the exit is abormal, then amandad will | 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 file descriptors: | |||
CONNECT GOOD 50 BAD 52 UGLY 51 | |||
note that each tag/descriptor pair specifies a unidirectional pipe. If bidirectional communication is necessary, the service should open two pipes - one outgoing and one incoming. | |||
For each file descriptor in the CONNECT line, amandad creates a new security stream and translates the file descriptor into a stream id, resulting in something like: | |||
CONNECT GOOD 49241 BAD 49240 UGLY 49238 | |||
Any file descriptors 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 = | = Service-Specific Hacks = | ||
Line 49: | Line 65: | ||
: '''sendsize''' | : '''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 <tt>etimeout</tt> timer on the server, it does ''not'' reset the 6 hour REP timeout in amandad. | 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 <tt>etimeout</tt> 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. |
Revision as of 18:13, 4 February 2010
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 file descriptors:
CONNECT GOOD 50 BAD 52 UGLY 51
note that each tag/descriptor pair specifies a unidirectional pipe. If bidirectional communication is necessary, the service should open two pipes - one outgoing and one incoming.
For each file descriptor in the CONNECT line, amandad creates a new security stream and translates the file descriptor into a stream id, resulting in something like:
CONNECT GOOD 49241 BAD 49240 UGLY 49238
Any file descriptors 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.