git.gag.com Git - debian/amanda/blob - docs/internals.txt

   1
   2          Chapter 22. AMANDA Internals
   3 Prev  Part V. Technical Background  Next
   4
   5 -------------------------------------------------------------------------------
   6
   7 Chapter 22. AMANDA Internals
   8
   9
  10 George Scott
  11
  12 Original text<George.Scott@cc.monash.edu.au>
  13
  14 Stefan G. Weichinger
  15
  16 XML-conversion
  17 AMANDA Core Team
  18 <sgw@amanda.org>
  19 Table of Contents
  20
  21
  22   Protocols
  23
  24   server_and_amandad_on_client
  25
  26   planner_and_driver
  27
  28   driver_and_dumper
  29
  30   taper(read)_and_taper(write)
  31
  32
  33 Note
  34
  35 Refer to http://www.amanda.org/docs/internals.html for the current version of
  36 this document.
  37 This is an attempt to document AMANDA's internals. Please feel free to make
  38 comments and suggest changes. Text for new sections gratefully accepted!
  39
  40  Protocols
  41
  42
  43 Note
  44
  45 The following was an ASCII-illustration in the original docs, I managed to
  46 transfer it at last. Maybe someone will convert this to the first image in the
  47 AMANDA-docs ;-) . sgw.
  48
  49
  50         Client I Server         +-planner-+
  51                I                |         |
  52                I                |         |
  53                I                |         |                     ______
  54   +-amandad-+  I                |         |                    (______)
  55   |         |  I                |         |                    |amdump|
  56   |         |  I                |         |           all ::::>|      |
  57   |         |  I                |         |           stderr   |      |
  58   |         |  I                |         |                    |      |
  59   |         |  I                |   so    |                    +------+
  60   |         |  I                +---------+
  61   |         |  I                    ::                          ______
  62   |         |  I                    \/                         (______)
  63   |         |  I                +-driver--+                    | log  |
  64   +---------+  I                |   si    |           all ::::>|      |
  65                I                |         |           log      |      |
  66                I                |         |                    |      |
  67   +-sendback+  I                |         |                    +------+
  68   |         |  I                |         |
  69   |         |  I        ::::::::|         |<::::::
  70   |         |  I       ::       |         |      ::
  71   |         |  I      ::   ::::>|         |::::   ::
  72   |         |  I      ::  ::    |         |   ::  ::
  73   |         |  I      :: ::     +---------+    :: ::
  74   |         |  I      :: ::                    :: ::
  75   |         |  I      :: ::                    :: ::
  76   |         |  I      :: ::       ______       :: ::
  77   +---------+  I      :: ::      (______)      :: ::
  78                I      :: ::      | /tmp |      :: ::
  79                I      \/ ::    :>|      |      \/ ::
  80   +-dump----+  I  +-dumper--+ :: +------+    +-taper/r-+    +-taper/w-+
  81   |         |  I  |   si so | ::             | si so   |    |         |
  82   |         |  I  |         | ::  ______     |         |    |         |
  83   |         |  I  |mesgfd   | :: (______)    |         |    |         |
  84   |       se|::::>|::::::::>|::  | hold |    |         |    |         |
  85   |         |  I  |     errf|    | disk |    |      p2c|:::>|p2c      |
  86   |         |  I  |         |    |      |    |      c2p|<:::|c2p      |
  87   ____
  88   |         |  I  |datafd   | ::>|      |::: |fd       |    |         |   /   \
  89   |       so|::::>|::::::::>|::  +------+  :>|::::::::>SHDMEM::::::::>|::
  90   >|tape|
  91   |         |  I  |    outfd| ::          :: |         |    |   tapefd|   \ _ /
  92   +---------+  I  +---------+  ::::::::::::  +---------+    +---------+
  93                I
  94
  95
  96  server and amandad on client
  97
  98 XXX - still to be done
  99
 100  planner and driver
 101
 102 planner interrogates all clients and generates a plan of which disks to backup
 103 and what dump level to do them at. The plan is plain text with one line per
 104 disk to be dumped. It is piped from planners stdout to drivers stdin. Plan
 105 lines come in two flavours:
 106 For total dumps: <host> <disk> <pri> <lev> <size> <time> <deg lev> <deg size>
 107 <deg time>
 108 For incremental dumps: <host> <disk> <pri> <lev> <size> <time>
 109 Where: <host> Host name of client (from disklist file) <disk> Name of disk
 110 (from disklist file) <pri> Priority of backup (pri from disklist and
 111 amanda.conf + days overdue for total) <lev> Dump level for dump (0 for total,
 112 1-9 for incremental) <size> Estimated size (in Kb after compression if
 113 requested) <time> Estimated time for backup (in seconds) <deg lev> <lev> to use
 114 if in degraded mode <deg size> <size> to use if in degraded mode <deg time>
 115 <time> to use if in degraded mode
 116
 117  driver and dumper
 118
 119 dumper talks via two pipes connected to each dumper's stdin and stdout. The
 120 commands and responses are plain text.
 121 driver can ask dumper to do a dump to a file on the holding disk: FILE-DUMP
 122 <handle> <filename> <host> <disk> <level> <dumpdate> <chunksize> <prog>
 123 <options> or directly to taper: PORT-DUMP <handle> <port> <host> <disk> <level>
 124 <dumpdate> <prog> <options> or exit at the end of the run: QUIT
 125 If the dump finishes correctly dumper replies with: DONE <handle> [<message>]
 126 If something goes wrong with the dump, dumper can request that the dump be
 127 retried at a later time with: TRY-AGAIN <handle> [<message>] or, for fatal
 128 errors, be abandoned with: FAILED <handle> [<message>]
 129 If the holding disk runs out of space, dumper will give: NO-ROOM <handle> and
 130 wait for driver to either fix the problem and say: CONTINUE or just say: ABORT
 131 in which case dumper kills the dump and replies with: ABORT-FINISHED <handle>
 132 If driver says something that dumper doesn't recognise it responds with: BAD-
 133 COMMAND <message>
 134 Where: <handle> Request ID <filename> Name of file (on holding disk) to write
 135 dump <port> Port (of taper) to send dump directly <host> Hostname of client
 136 <disk> Disk to backup <level> Dump level to do backup at <prog> Dump program to
 137 use <options> Options to pass to sendbackup <message> Error or status message
 138 *driver and taper
 139 driver talks via two pipes connected to taper's stdin and stdout. The commands
 140 and responses are plain text.
 141 driver initialises taper with: START-TAPER <datestamp> to which taper replies
 142 with: TAPER-OK or, for fatal errors, with: TAPER-ERROR [<message>]
 143 driver can ask taper to to copy a file from the holding disk to tape: FILE-
 144 WRITE <handle> <filename> <host> <disk> <level> or directly from a dumper:
 145 PORT-WRITE <handle> <host> <disk> <level> or exit at the end of the run: QUIT
 146 taper responds to the PORT-WRITE command with: PORT <port> which driver should
 147 then hand on to dumper in a PORT-DUMP command.
 148 taper responds to the QUIT command with: QUITING
 149 If the copy to tape finishes correctly taper replies with: DONE <handle>
 150 [<message>]
 151 If something goes wrong with the tape, taper can request that the dump be
 152 retried at a later time with: TRY-AGAIN <handle> [<message>] or, for fatal
 153 errors, be abandoned with: TAPE-ERROR <handle> [<message>]
 154 If driver says something that taper doesn't recognise it responds with: BAD-
 155 COMMAND <message>
 156 Where: <datestamp> Todays date as "yymmdd" <handle> Request ID <filename> Name
 157 of file (on holding disk) to write dump <port> Port (of taper) to send dump
 158 directly <host> Hostname of client <disk> Disk to backup <level> Dump level to
 159 do backup at <message> Error or status message
 160
 161  taper(read) and taper(write)
 162
 163 There are two parts to taper: the file reader and the tape writer.
 164 Communication between the two sides is via a bit of shared memory for data
 165 transfer and two pipes (one in each direction) for synchronisation.
 166 The shared memory area is made up of NBUFS (=20) buffers each of which contains
 167 a status word and a BUFFER_SIZE (=32*1024) byte data buffer.
 168 The sync pipes are used to transfer a simplistic command sequence:
 169 reader writer ------ ------
 170 Startup S<datestamp> ---> <--- S Start OK <--- E<messge> Error
 171 Open tape O<datestamp><hostname><diskname><level> ---> <--- O Opening
 172 Write buffer W<bufnum> ---> <--- R<bufnum> Buffer empty <--- E<message> Error
 173 <--- T<message> Error, try again E ack e ---> Protocol error X ---> <--- x X
 174 ack
 175 Close tape C ---> <--- C<label><filenum><stats> Closing
 176 Quit Q --->
 177 -------------------------------------------------------------------------------
 178
 179 Prev                            Up                           Next
 180 Chapter 21. AMANDA dumper API  Home  Chapter 23. AMANDA Event API
 181