Amidxtaped protocol

This page picks up where Amandad Service Protocol leaves off. Amidxtaped sends exactly one dump in response to a set of parameters on its control stream. To get another dump, start a new amidxtaped.

REQ

An amidxtaped REQ packet looks like:

SERVICE amidxtaped
OPTIONS features=features;auth=auth;

All of the interesting specification of which data to send comes on the control connection, below.

REP

Amidxtaped sets up two streams in its REP packet:

CONNECT CTL ctlfd DATA datafd

the control connection is bidirectional, while the data connection only carries data from amidxtaped.

Started from Inetd

If amidxtaped is started directly from inetd, then it assumes its stdin and stdout are tied to a TCP socket.

This service expects to see the string

 SECURITY USER root\r\n

(or some other user than root). Note the \r\n at the end. I couldn't say why, but without the \r amidxtaped will hang. This line triggers a BSDTCP-style security check: the username and remote IP must match .amandahosts, the source port must be privileged, and the forward and reverse DNS must match. Note that the installchecks override this particular test.

Note that when amidxtaped is started directly from inetd, the main socket becomes the control connection after the SECURITY line.

Control Connection

The control connection is a set of specifier lines, followed by an "END" line. All lines are terminated by "\r\n". Are you still asking why? Accept the insanity.

Not all specifiers must be given in any particular request. The available specifiers are:

LABEL=label

not a label, but a Tapelist Specification giving the files to be recovered

FSF=fsf

seek to this file before starting the recovery (ignored)

HEADER

prefix the data with an Amanda header (DISK_BLOCK_BYTES long)

FEATURES=features

reiterates the requester's feature-set (in case amidxtaped was started from inetd). When run from amandad, amidxtaped will immediately respond with the equivalent line giving its own features. When run from inetd, amidxtaped will respond with its features only, with no terminating newline of any sort. This relies on "normal" buffering of the TCP connection to receive the features in a single read operation.

DEVICE=device

tape device (or changer) to restore from

HOST=host

host match expression for this dump (ignored; optional)

DISK=disk

diskname match expression for this dump (ignored; optional)

DATESTAMP=datestamp

datestamp for this dump (ignored; optional)

CONFIG=config

Amanda configuration to use

the list of specifiers is terminated by

END\r\n

or by any line that starts with a digit (.. good, you didn't ask why -- you're learning!). Any non-matchting lines will be ignored.

When the requested dump is on a holding disk, then LABEL is omitted, and DEVICE specifies the holding file in Tapelist Specification format -- that is, with a :0 suffix, e.g.,

DEVICE=/A/p/hold\:ing/20100205181319/euclid._A_p_etc.1:0

(note that the : in the holding pathname is quoted)

Now the time comes to transfer the data stream. First, if the FEATURES did not include fe_recover_splits, then the data is streamed directly over the control connection, and no further interaction is possible. Otherwise, if amidxtaped is operating from inetd then it opens a new, unprivileged TCP port, and sends a CONNECT line on the control connection.

 CONNECT 1234\n

(where 1234 is the port number) Note that there is no \r in this particular message. Amidxtaped then blocks waiting for an incoming connection. That incoming connection must be from a privileged port and begin with the same SECURITY USER line as appeared on the main connection. After that point, the data begins flowing. See amidxtaped protocol for information about other messages on the control stream. Of course, if amidxtaped is run from amandad, then the data simply flows over the data connection.

After the header is sent (or immediately, if no HEADER specification was given), if both ends of the connection have fe_amidtaped_datapath, then amidxtaped waits for a DATA-PATH line, one of

DATA-PATH AMANDA\r\n
DATA-PATH DIRECT-TCP\r\n

and immediately replies with a similar line of its own. This forms a kind of negotiation between the two ends of the connection, with amidxtaped's determination being final

If amidxtaped has a message for the user, it sends a MESSAGE line on the control connection:

MESSAGE I like green eggs and ham.\r\n

If it needs the user to feed a particular volume, it sends a FEEDME line:

FEEDME DailySet1-013\r\n

Labels longer than 132 bytes are not currently supported. If the volume is not available (the user cancels), amidxtaped expects an ERROR response:

ERROR\r\n

Otherwise, if amidxtaped does not have the fe_amrecover_feedme_tape feature, then it expects an OK response and does not support trying some other device:

OK\r\n

Finally, if amidxtaped has the fe_amrecover_feedme_tape feature, then it expects a TAPE response, specifying either the same device as used in the original request, or a new device:

TAPE tape:/dev/nrst0\r\n

indicating that amidxtaped should use the given device.

Once data is available, it starts flowing on the data connection. Note that, in the case of a split dump, MESSAGE or FEEDME lines may come after a significant quantity of dta has been transferred.