+++ /dev/null
-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<datestamp><hostname><diskname><level>
- --->
- <--- 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.
-