git.gag.com Git - debian/amanda/blob - docs/INTERNALS

   1 This is an attempt to document Amanda's internals.  Please feel free to make
   2 comments and suggest changes.  Text for new sections gratefully accepted!
   3
   4 George.
   5 (George.Scott@cc.monash.edu.au)
   6
   7 ===============
   8 == PROTOCOLS ==
   9 ===============
  10
  11
  12       Client I Server         +-planner-+
  13              I                |         |
  14              I                |         |
  15              I                |         |                     ______
  16 +-amandad-+  I                |         |                    (______)
  17 |         |  I                |         |                    |amdump|
  18 |         |  I                |         |           all ::::>|      |
  19 |         |  I                |         |           stderr   |      |
  20 |         |  I                |         |                    |      |
  21 |         |  I                |   so    |                    +------+
  22 |         |  I                +---------+
  23 |         |  I                    ::                          ______
  24 |         |  I                    \/                         (______)
  25 |         |  I                +-driver--+                    | log  |
  26 +---------+  I                |   si    |           all ::::>|      |
  27              I                |         |           log      |      |
  28              I                |         |                    |      |
  29 +-sendback+  I                |         |                    +------+
  30 |         |  I                |         |
  31 |         |  I        ::::::::|         |<::::::
  32 |         |  I       ::       |         |      ::
  33 |         |  I      ::   ::::>|         |::::   ::
  34 |         |  I      ::  ::    |         |   ::  ::
  35 |         |  I      :: ::     +---------+    :: ::
  36 |         |  I      :: ::                    :: ::
  37 |         |  I      :: ::                    :: ::
  38 |         |  I      :: ::       ______       :: ::
  39 +---------+  I      :: ::      (______)      :: ::
  40              I      :: ::      | /tmp |      :: ::
  41              I      \/ ::    :>|      |      \/ ::
  42 +-dump----+  I  +-dumper--+ :: +------+    +-taper/r-+    +-taper/w-+
  43 |         |  I  |   si so | ::             | si so   |    |         |
  44 |         |  I  |         | ::  ______     |         |    |         |
  45 |         |  I  |mesgfd   | :: (______)    |         |    |         |
  46 |       se|::::>|::::::::>|::  | hold |    |         |    |         |
  47 |         |  I  |     errf|    | disk |    |      p2c|:::>|p2c      |
  48 |         |  I  |         |    |      |    |      c2p|<:::|c2p      |     ____
  49 |         |  I  |datafd   | ::>|      |::: |fd       |    |         |   /   \
  50 |       so|::::>|::::::::>|::  +------+  :>|::::::::>SHDMEM::::::::>|::>|tape|
  51 |         |  I  |    outfd| ::          :: |         |    |   tapefd|   \ _ /
  52 +---------+  I  +---------+  ::::::::::::  +---------+    +---------+
  53              I
  54
  55
  56 server and amandad on client
  57 ============================
  58
  59 XXX - still to be done
  60
  61
  62 planner and driver
  63 ==================
  64
  65 Planner interrogates all clients and generates a plan of which disks to
  66 backup and what dump level to do them at.  The plan is plain text with one
  67 line per disk to be dumped.  It is piped from planners stdout to drivers
  68 stdin.  Plan lines come in two flavours:
  69
  70 For total dumps:
  71    <host> <disk> <pri> <lev> <size> <time> <deg lev> <deg size> <deg time>
  72
  73 For incremental dumps:
  74    <host> <disk> <pri> <lev> <size> <time>
  75
  76 Where:
  77    <host>      Host name of client (from disklist file)
  78    <disk>      Name of disk (from disklist file)
  79    <pri>       Priority of backup (pri from disklist and amanda.conf + days
  80                  overdue for total)
  81    <lev>       Dump level for dump (0 for total, 1-9 for incremental)
  82    <size>      Estimated size (in Kb after compression if requested)
  83    <time>      Estimated time for backup (in seconds)
  84    <deg lev>   <lev> to use if in degraded mode
  85    <deg size>  <size> to use if in degraded mode
  86    <deg time>  <time> to use if in degraded mode
  87
  88
  89 driver and dumper
  90 =================
  91
  92 Driver talks via two pipes connected to each dumper's stdin and stdout.  The
  93 commands and responses are plain text.
  94
  95 Driver can ask dumper to do a dump to a file on the holding disk:
  96    FILE-DUMP <handle> <filename> <host> <disk> <level> <dumpdate> <chunksize> <prog> <use> <options>
  97 or directly to taper:
  98    PORT-DUMP <handle> <port> <host> <disk> <level> <dumpdate> <prog> <options>
  99 or exit at the end of the run:
 100    QUIT
 101
 102 If the dump finishes correctly dumper replies with:
 103    DONE <handle> [<message>]
 104
 105 If something goes wrong with the dump, dumper can request that the dump be
 106 retried at a later time with:
 107    TRY-AGAIN <handle> [<message>]
 108 or, for fatal errors, be abandoned with:
 109    FAILED <handle> [<message>]
 110
 111 If the holding disk runs out of space (i. e. 'disk full'), dumper will give:
 112    NO-ROOM <handle> <missing_size>
 113 After that, it will issue RQ_MORE_DISK (see below). The driver will correct
 114 its notion of free diskspace by subtracting <missing_size> from the
 115 holding disk's alleged size.
 116
 117 If the dumper has used up all of its allocated holding disk space, it will
 118 request more with
 119    RQ-MORE-DISK <handle>
 120 and wait for driver to either allocate more diskspace for the dumper and say
 121    CONTINUE <filename> <chunksize> <use>
 122 or just say
 123    ABORT
 124 (see above).
 125
 126 If driver says something that dumper doesn't recognise it responds with:
 127    BAD-COMMAND <message>
 128
 129 Where:
 130    <handle>    Request ID
 131    <filename>  Name of file on holding disk to write dump (see the section
 132                 'Multiple Holding Disks' below)
 133    <port>      Port (of taper) to send dump directly
 134    <host>      Hostname of client
 135    <disk>      Disk to backup
 136    <level>     Dump level to do backup at
 137    <prog>      Dump program to use
 138    <options>   Options to pass to sendbackup
 139    <message>   Error or status message
 140    <use>       Amount of diskspace to use on the holding disk given by
 141                <filename>
 142    <chunksize> Maximum size of a file on the given holding disk
 143    <missing_size> Difference between the allocated space and the space
 144                   actually used by a dumper when a DISK FULL occurs
 145
 146
 147 driver and taper
 148 ================
 149
 150 Driver talks via two pipes connected to taper's stdin and stdout.  The
 151 commands and responses are plain text.
 152
 153 Driver initialises taper with:
 154    START-TAPER <datestamp>
 155 to which taper replies with:
 156    TAPER-OK
 157 or, for fatal errors, with:
 158    TAPER-ERROR [<message>]
 159
 160 Driver can ask taper to to copy a file from the holding disk to tape:
 161    FILE-WRITE <handle> <filename> <host> <disk> <level>
 162 or directly from a dumper:
 163    PORT-WRITE <handle> <host> <disk> <level>
 164 or exit at the end of the run:
 165    QUIT
 166
 167 Taper responds to the PORT-WRITE command with:
 168    PORT <port>
 169 which driver should then hand on to dumper in a PORT-DUMP command.
 170
 171 Taper responds to the QUIT command with:
 172    QUITING
 173
 174 If the copy to tape finishes correctly taper replies with:
 175    DONE <handle> [<message>]
 176
 177 If something goes wrong with the tape, taper can request that the dump be
 178 retried at a later time with:
 179    TRY-AGAIN <handle> [<message>]
 180 or, for fatal errors, be abandoned with:
 181    TAPE-ERROR <handle> [<message>]
 182
 183 If driver says something that taper doesn't recognise it responds with:
 184    BAD-COMMAND <message>
 185
 186 Where:
 187    <datestamp> Todays date as "yymmdd"
 188    <handle>    Request ID
 189    <filename>  Name of file (on holding disk) to write dump
 190    <port>      Port (of taper) to send dump directly
 191    <host>      Hostname of client
 192    <disk>      Disk to backup
 193    <level>     Dump level to do backup at
 194    <message>   Error or status message
 195
 196
 197 taper(read) and taper(write)
 198 ============================
 199
 200 There are two parts to taper: the file reader and the tape writer.
 201 Communication between the two sides is via a bit of shared memory for data
 202 transfer and two pipes (one in each direction) for synchronisation.
 203
 204 The shared memory area is made up of NBUFS (=20) buffers each of which
 205 contains a status word and a BUFFER_SIZE (=32*1024) byte data buffer.
 206
 207 The sync pipes are used to transfer a simplistic command sequence:
 208
 209 reader                              writer
 210 ------                              ------
 211
 212 Startup           S<datestamp> --->
 213                                <--- S             Start OK
 214                                <--- E<messge>     Error
 215
 216 Open tape         O<datestamp><hostname><diskname><level>
 217                                --->
 218                                <--- O             Opening
 219
 220 Write buffer      W<bufnum>    --->
 221                                <--- R<bufnum>     Buffer empty
 222                                <--- E<message>    Error
 223                                <--- T<message>    Error, try again
 224 E ack             e            --->
 225 Protocol error    X            --->
 226                                <--- x             X ack
 227
 228 Close tape        C            --->
 229                                <--- C<label><filenum><stats>  Closing
 230
 231 Quit              Q            --->
 232
 233
 234 Multiple Holding Disks
 235 ======================
 236
 237 (This section was written by Peter Conrad <conrad@opus5.de>)
 238
 239 Since amanda version x.x.x a single dump file may be spread across multiple
 240 holding disks. Some changes in the driver-dumper protocol have been introduced
 241 for this, as well as in the allocation of holding diskspace.
 242
 243 1. Before the dump starts, an initial amount of holding diskspace is
 244    allocated for the dump. The amount is based on the estimate for the
 245    disk.
 246 2. If there is enough space available on the holding disks a list of holding
 247    disks is created. For each holding disk to be used by the dumper, the
 248    space to be used by this dumper and the chunksize of that holding disk
 249    are noted (and, of course, the name of the holding disk).
 250 3. This list is turned into an array? of structures containing the values
 251    found in step 2. The first set of values is sent to the dumper.
 252 4. A dumper is responsible for sticking to the given values:
 253     - no file created by the dumper may be larger than the corresponding
 254       chunksize
 255     - on any given holding disk, no more than 'use' KBytes of diskspace may
 256       be used.
 257 5. a) When all allocated diskspace has been used and the dump still hasn't
 258       finished, the dumper may request more space from the driver. The driver
 259       can either send a filename and additional size to be used, possibly on
 260       a different hodling disk, or tell the dumper to abort the dump.
 261    b) When the disk currently in use by the dumper runs full the dumper
 262       will tell the driver about this situation. The driver will react like
 263       in step a), but it will correct its notion of free diskspace.
 264 6. If the driver supplies another list of holding disks (not necessarily as
 265    much as the dumper requested), the dumper interprets the given 'use' values
 266    as *additional* diskspace it may use.
 267    Continue at 4.
 268
 269 The protocol between driver and taper didn't need to be modified, because
 270 each chunk of a dump contains the full pathname of the succeeding chunk.
 271