This is an attempt to document Amanda's internals.  Please feel free to make
comments and suggest changes.  Text for new sections gratefully accepted!

George.
(George.Scott@cc.monash.edu.au)

===============
== PROTOCOLS ==
===============


      Client I Server         +-planner-+
             I                |         |
             I                |         |
             I                |         |                     ______
+-amandad-+  I                |         |                    (______)
|         |  I                |         |                    |amdump|
|         |  I                |         |           all ::::>|      |
|         |  I                |         |           stderr   |      |
|         |  I                |         |                    |      |
|         |  I                |   so    |                    +------+
|         |  I                +---------+
|         |  I                    ::                          ______
|         |  I                    \/                         (______)
|         |  I                +-driver--+                    | log  |
+---------+  I                |   si    |           all ::::>|      |
             I                |         |           log      |      |
             I                |         |                    |      |
+-sendback+  I                |         |                    +------+
|         |  I                |         |
|         |  I        ::::::::|         |<::::::
|         |  I       ::       |         |      ::
|         |  I      ::   ::::>|         |::::   ::
|         |  I      ::  ::    |         |   ::  ::
|         |  I      :: ::     +---------+    :: ::
|         |  I      :: ::                    :: ::
|         |  I      :: ::                    :: ::
|         |  I      :: ::       ______       :: ::
+---------+  I      :: ::      (______)      :: ::
             I      :: ::      | /tmp |      :: ::
             I      \/ ::    :>|      |      \/ ::
+-dump----+  I  +-dumper--+ :: +------+    +-taper/r-+    +-taper/w-+
|         |  I  |   si so | ::             | si so   |    |         |
|         |  I  |         | ::  ______     |         |    |         |
|         |  I  |mesgfd   | :: (______)    |         |    |         |
|       se|::::>|::::::::>|::  | hold |    |         |    |         |
|         |  I  |     errf|    | disk |    |      p2c|:::>|p2c      |
|         |  I  |         |    |      |    |      c2p|<:::|c2p      |     ____
|         |  I  |datafd   | ::>|      |::: |fd       |    |         |   /   \
|       so|::::>|::::::::>|::  +------+  :>|::::::::>SHDMEM::::::::>|::>|tape|
|         |  I  |    outfd| ::          :: |         |    |   tapefd|   \ _ /
+---------+  I  +---------+  ::::::::::::  +---------+    +---------+      
             I


server and amandad on client
============================

XXX - still to be done


planner and driver
==================

Planner interrogates all clients and generates a plan of which disks to
backup and what dump level to do them at.  The plan is plain text with one
line per disk to be dumped.  It is piped from planners stdout to drivers
stdin.  Plan lines come in two flavours:

For total dumps:
   <host> <disk> <pri> <lev> <size> <time> <deg lev> <deg size> <deg time>

For incremental dumps:
   <host> <disk> <pri> <lev> <size> <time>

Where:
   <host>      Host name of client (from disklist file)
   <disk>      Name of disk (from disklist file)
   <pri>       Priority of backup (pri from disklist and amanda.conf + days
                 overdue for total)
   <lev>       Dump level for dump (0 for total, 1-9 for incremental)
   <size>      Estimated size (in Kb after compression if requested)
   <time>      Estimated time for backup (in seconds)
   <deg lev>   <lev> to use if in degraded mode
   <deg size>  <size> to use if in degraded mode
   <deg time>  <time> to use if in degraded mode


driver and dumper
=================

Driver talks via two pipes connected to each dumper's stdin and stdout.  The
commands and responses are plain text.

Driver can ask dumper to do a dump to a file on the holding disk:
   FILE-DUMP <handle> <filename> <host> <disk> <level> <dumpdate> <chunksize> <prog> <use> <options>
or directly to taper:
   PORT-DUMP <handle> <port> <host> <disk> <level> <dumpdate> <prog> <options>
or exit at the end of the run:
   QUIT

If the dump finishes correctly dumper replies with:
   DONE <handle> [<message>]

If something goes wrong with the dump, dumper can request that the dump be
retried at a later time with:
   TRY-AGAIN <handle> [<message>]
or, for fatal errors, be abandoned with:
   FAILED <handle> [<message>]

If the holding disk runs out of space (i. e. 'disk full'), dumper will give:
   NO-ROOM <handle> <missing_size>
After that, it will issue RQ_MORE_DISK (see below). The driver will correct
its notion of free diskspace by subtracting <missing_size> from the
holding disk's alleged size.

If the dumper has used up all of its allocated holding disk space, it will 
request more with
   RQ-MORE-DISK <handle>
and wait for driver to either allocate more diskspace for the dumper and say
   CONTINUE <filename> <chunksize> <use>
or just say
   ABORT
(see above).

If driver says something that dumper doesn't recognise it responds with:
   BAD-COMMAND <message>

Where:
   <handle>    Request ID
   <filename>  Name of file on holding disk to write dump (see the section
		'Multiple Holding Disks' below)
   <port>      Port (of taper) to send dump directly
   <host>      Hostname of client
   <disk>      Disk to backup
   <level>     Dump level to do backup at
   <prog>      Dump program to use
   <options>   Options to pass to sendbackup
   <message>   Error or status message
   <use>       Amount of diskspace to use on the holding disk given by
	       <filename>
   <chunksize> Maximum size of a file on the given holding disk
   <missing_size> Difference between the allocated space and the space
		  actually used by a dumper when a DISK FULL occurs


driver and taper
================

Driver talks via two pipes connected to taper's stdin and stdout.  The
commands and responses are plain text.

Driver initialises taper with:
   START-TAPER <datestamp>
to which taper replies with:
   TAPER-OK
or, for fatal errors, with:
   TAPER-ERROR [<message>]

Driver can ask taper to to copy a file from the holding disk to tape:
   FILE-WRITE <handle> <filename> <host> <disk> <level>
or directly from a dumper:
   PORT-WRITE <handle> <host> <disk> <level>
or exit at the end of the run:
   QUIT

Taper responds to the PORT-WRITE command with:
   PORT <port>
which driver should then hand on to dumper in a PORT-DUMP command.

Taper responds to the QUIT command with:
   QUITING

If the copy to tape finishes correctly taper replies with:
   DONE <handle> [<message>]

If something goes wrong with the tape, taper can request that the dump be
retried at a later time with:
   TRY-AGAIN <handle> [<message>]
or, for fatal errors, be abandoned with:
   TAPE-ERROR <handle> [<message>]

If driver says something that taper doesn't recognise it responds with:
   BAD-COMMAND <message>

Where:
   <datestamp> Todays date as "yymmdd"
   <handle>    Request ID
   <filename>  Name of file (on holding disk) to write dump
   <port>      Port (of taper) to send dump directly
   <host>      Hostname of client
   <disk>      Disk to backup
   <level>     Dump level to do backup at
   <message>   Error or status message


taper(read) and taper(write)
============================

There are two parts to taper: the file reader and the tape writer.
Communication between the two sides is via a bit of shared memory for data
transfer and two pipes (one in each direction) for synchronisation.

The shared memory area is made up of NBUFS (=20) buffers each of which
contains a status word and a BUFFER_SIZE (=32*1024) byte data buffer.

The sync pipes are used to transfer a simplistic command sequence:

reader                              writer
------                              ------

Startup           S<datestamp> --->
                               <--- S             Start OK
                               <--- E<messge>     Error

Open tape         O            --->
                               <--- O             Opening

Write buffer      W<bufnum>    --->
                               <--- R<bufnum>     Buffer empty
                               <--- E<message>    Error
                               <--- T<message>    Error, try again
E ack             e            --->
Protocol error    X            --->
                               <--- x             X ack

Close tape        C            --->
                               <--- C<label><filenum><stats>  Closing

Quit              Q            --->


Multiple Holding Disks
======================

(This section was written by Peter Conrad <conrad@opus5.de>)

Since amanda version x.x.x a single dump file may be spread across multiple
holding disks. Some changes in the driver-dumper protocol have been introduced
for this, as well as in the allocation of holding diskspace.

1. Before the dump starts, an initial amount of holding diskspace is
   allocated for the dump. The amount is based on the estimate for the
   disk.
2. If there is enough space available on the holding disks a list of holding
   disks is created. For each holding disk to be used by the dumper, the
   space to be used by this dumper and the chunksize of that holding disk
   are noted (and, of course, the name of the holding disk).
3. This list is turned into an array? of structures containing the values
   found in step 2. The first set of values is sent to the dumper.
4. A dumper is responsible for sticking to the given values:
    - no file created by the dumper may be larger than the corresponding
      chunksize
    - on any given holding disk, no more than 'use' KBytes of diskspace may
      be used.
5. a) When all allocated diskspace has been used and the dump still hasn't
      finished, the dumper may request more space from the driver. The driver
      can either send a filename and additional size to be used, possibly on
      a different hodling disk, or tell the dumper to abort the dump.
   b) When the disk currently in use by the dumper runs full the dumper
      will tell the driver about this situation. The driver will react like
      in step a), but it will correct its notion of free diskspace.
6. If the driver supplies another list of holding disks (not necessarily as
   much as the dumper requested), the dumper interprets the given 'use' values
   as *additional* diskspace it may use.
   Continue at 4.

The protocol between driver and taper didn't need to be modified, because
each chunk of a dump contains the full pathname of the succeeding chunk.