git.sur5r.net Git - bacula/docs/blob - docs/developers/daemonprotocol.tex

   1 %%
   2 %%
   3
   4 \section*{Daemon Protocol}
   5 \label{_ChapterStart2}
   6 \index{Protocol!Daemon }
   7 \index{Daemon Protocol }
   8 \addcontentsline{toc}{section}{Daemon Protocol}
   9
  10 \subsection*{General}
  11 \index{General }
  12 \addcontentsline{toc}{subsection}{General}
  13
  14 This document describes the protocols used between the various daemons. As
  15 Bacula has developed, it has become quite out of date. The general idea still
  16 holds true, but the details of the fields for each command, and indeed the
  17 commands themselves have changed considerably.
  18
  19 It is intended to be a technical discussion of the general daemon protocols
  20 and as such is not targeted at end users but rather at developers and system
  21 administrators that want or need to know more of the working details of {\bf
  22 Bacula}.
  23
  24 \subsection*{Low Level Network Protocol}
  25 \index{Protocol!Low Level Network }
  26 \index{Low Level Network Protocol }
  27 \addcontentsline{toc}{subsection}{Low Level Network Protocol}
  28
  29 At the lowest level, the network protocol is handled by {\bf BSOCK} packets
  30 which contain a lot of information about the status of the network connection:
  31 who is at the other end, etc. Each basic {\bf Bacula} network read or write
  32 actually consists of two low level network read/writes. The first write always
  33 sends four bytes of data in machine independent byte order. If data is to
  34 follow, the first four bytes are a positive non-zero integer indicating the
  35 length of the data that follow in the subsequent write. If the four byte
  36 integer is zero or negative, it indicates a special request, a sort of network
  37 signaling capability. In this case, no data packet will follow. The low level
  38 BSOCK routines expect that only a single thread is accessing the socket at a
  39 time. It is advised that multiple threads do not read/write the same socket.
  40 If you must do this, you must provide some sort of locking mechanism. I would
  41 not be appropriate for efficiency reasons to make every call to the BSOCK
  42 routines lock and unlock the packet.
  43
  44 \subsection*{General Daemon Protocol}
  45 \index{General Daemon Protocol }
  46 \index{Protocol!General Daemon }
  47 \addcontentsline{toc}{subsection}{General Daemon Protocol}
  48
  49 In general, all the daemons follow the following global rules. There may be
  50 exceptions depending on the specific case. Normally, one daemon will be
  51 sending commands to another daemon (specifically, the Director to the Storage
  52 daemon and the Director to the File daemon).
  53
  54 \begin{itemize}
  55 \item Commands are always ASCII commands that are  upper/lower case dependent
  56    as well as space sensitive.
  57 \item All binary data is converted into ASCII (either with printf statements
  58    or  using base64 encoding).
  59 \item All responses to commands sent are always  prefixed with a return
  60    numeric code where codes in the 1000's are  reserved for the Director, the
  61    2000's are reserved for the  File daemon, and the 3000's are reserved for the
  62 Storage daemon.
  63 \item Any response that is not prefixed with a numeric  code is a command (or
  64    subcommand if you like) coming  from the other end. For example, while the
  65    Director is  corresponding with the Storage daemon, the Storage daemon  can
  66 request Catalog services from the Director. This  convention permits each side
  67 to send commands to the  other daemon while simultaneously responding to
  68 commands.
  69 \item Any response that is of zero length, depending on the context,  either
  70    terminates the data stream being sent or terminates command mode  prior to
  71    closing the connection.
  72 \item Any response that is of negative length is a special sign that  normally
  73    requires a response. For example, during data transfer from the  File daemon
  74    to the Storage daemon, normally the File daemon  sends continuously without
  75 intervening reads. However, periodically,  the File daemon will send a packet
  76 of length -1 indicating that  the current data stream is complete and that the
  77 Storage  daemon should respond to the packet with an OK, ABORT JOB,  PAUSE,
  78 etc. This permits the File daemon to efficiently send  data while at the same
  79 time occasionally ``polling''  the Storage daemon for his status or any
  80 special requests.
  81
  82 Currently, these negative lengths are specific to the daemon, but  shortly,
  83 the range 0 to -999 will be standard daemon wide signals,  while -1000 to
  84 -1999 will be for Director user, -2000 to -2999  for the File daemon, and
  85 -3000 to -3999 for the Storage  daemon.
  86 \end{itemize}
  87
  88 \subsection*{The Protocol Used Between the Director and the Storage Daemon}
  89 \index{Daemon!Protocol Used Between the Director and the Storage }
  90 \index{Protocol Used Between the Director and the Storage Daemon }
  91 \addcontentsline{toc}{subsection}{Protocol Used Between the Director and the
  92 Storage Daemon}
  93
  94 Before sending commands to the File daemon, the Director opens a Message
  95 channel with the Storage daemon, identifies itself and presents its password.
  96 If the password check is OK, the Storage daemon accepts the Director. The
  97 Director then passes the Storage daemon, the JobId to be run as well as the
  98 File daemon authorization (append, read all, or read for a specific session).
  99 The Storage daemon will then pass back to the Director a enabling key for this
 100 JobId that must be presented by the File daemon when opening the job. Until
 101 this process is complete, the Storage daemon is not available for use by File
 102 daemons.
 103
 104 \footnotesize
 105 \begin{verbatim}
 106 SD: listens
 107 DR: makes connection
 108 DR: Hello <Director-name> calling <password>
 109 SD: 3000 OK Hello
 110 DR: JobId=nnn Allow=(append, read) Session=(*, SessionId)
 111                     (Session not implemented yet)
 112 SD: 3000 OK Job Authorization=<password>
 113 DR: use device=<device-name> media_type=<media-type>
 114         pool_name=<pool-name> pool_type=<pool_type>
 115 SD: 3000 OK use device
 116 \end{verbatim}
 117 \normalsize
 118
 119 For the Director to be authorized, the \lt{}Director-name\gt{} and the
 120 \lt{}password\gt{} must match the values in one of the Storage daemon's
 121 Director resources (there may be several Directors that can access a single
 122 Storage daemon).
 123
 124 \subsection*{The Protocol Used Between the Director and the File Daemon}
 125 \index{Daemon!Protocol Used Between the Director and the File }
 126 \index{Protocol Used Between the Director and the File Daemon }
 127 \addcontentsline{toc}{subsection}{Protocol Used Between the Director and the
 128 File Daemon}
 129
 130 A typical conversation might look like the following:
 131
 132 \footnotesize
 133 \begin{verbatim}
 134 FD: listens
 135 DR: makes connection
 136 DR: Hello <Director-name> calling <password>
 137 FD: 2000 OK Hello
 138 DR: JobId=nnn Authorization=<password>
 139 FD: 2000 OK Job
 140 DR: storage address = <Storage daemon address> port = <port-number>
 141           name = <DeviceName> mediatype = <MediaType>
 142 FD: 2000 OK storage
 143 DR: include
 144 DR: <directory1>
 145 DR: <directory2>
 146     ...
 147 DR: Null packet
 148 FD: 2000 OK include
 149 DR: exclude
 150 DR: <directory1>
 151 DR: <directory2>
 152     ...
 153 DR: Null packet
 154 FD: 2000 OK exclude
 155 DR: full
 156 FD: 2000 OK full
 157 DR: save
 158 FD: 2000 OK save
 159 FD: Attribute record for each file as sent to the
 160     Storage daemon (described above).
 161 FD: Null packet
 162 FD: <append close responses from Storage daemon>
 163     e.g.
 164     3000 OK Volumes = <number of volumes>
 165     3001 Volume = <volume-id> <start file> <start block>
 166          <end file> <end block> <volume session-id>
 167     3002 Volume data = <date/time of last write> <Number bytes written>
 168          <number errors>
 169     ... additional Volume / Volume data pairs for volumes 2 .. n
 170 FD: Null packet
 171 FD: close socket
 172 \end{verbatim}
 173 \normalsize
 174
 175 \subsection*{The Save Protocol Between the File Daemon and the Storage Daemon}
 176 \index{Save Protocol Between the File Daemon and the Storage Daemon }
 177 \index{Daemon!Save Protocol Between the File Daemon and the Storage }
 178 \addcontentsline{toc}{subsection}{Save Protocol Between the File Daemon and
 179 the Storage Daemon}
 180
 181 Once the Director has send a {\bf save} command to the File daemon, the File
 182 daemon will contact the Storage daemon to begin the save.
 183
 184 In what follows: FD: refers to information set via the network from the File
 185 daemon to the Storage daemon, and SD: refers to information set from the
 186 Storage daemon to the File daemon.
 187
 188 \subsubsection*{Command and Control Information}
 189 \index{Information!Command and Control }
 190 \index{Command and Control Information }
 191 \addcontentsline{toc}{subsubsection}{Command and Control Information}
 192
 193 Command and control information is exchanged in human readable ASCII commands.
 194
 195
 196 \footnotesize
 197 \begin{verbatim}
 198 FD: listens
 199 SD: makes connection
 200 FD: append open session = <JobId> [<password>]
 201 SD: 3000 OK ticket = <number>
 202 FD: append data <ticket-number>
 203 SD: 3000 OK data address = <IPaddress> port = <port>
 204 \end{verbatim}
 205 \normalsize
 206
 207 \subsubsection*{Data Information}
 208 \index{Information!Data }
 209 \index{Data Information }
 210 \addcontentsline{toc}{subsubsection}{Data Information}
 211
 212 The Data information consists of the file attributes and data to the Storage
 213 daemon. For the most part, the data information is sent one way: from the File
 214 daemon to the Storage daemon. This allows the File daemon to transfer
 215 information as fast as possible without a lot of handshaking and network
 216 overhead.
 217
 218 However, from time to time, the File daemon needs to do a sort of checkpoint
 219 of the situation to ensure that everything is going well with the Storage
 220 daemon. To do so, the File daemon sends a packet with a negative length
 221 indicating that he wishes the Storage daemon to respond by sending a packet of
 222 information to the File daemon. The File daemon then waits to receive a packet
 223 from the Storage daemon before continuing.
 224
 225 All data sent are in binary format except for the header packet, which is in
 226 ASCII. There are two packet types used data transfer mode: a header packet,
 227 the contents of which are known to the Storage daemon, and a data packet, the
 228 contents of which are never examined by the Storage daemon.
 229
 230 The first data packet to the Storage daemon will be an ASCII header packet
 231 consisting of the following data.
 232
 233 \lt{}File-Index\gt{} \lt{}Stream-Id\gt{} \lt{}Info\gt{} where {\bf
 234 \lt{}File-Index\gt{}} is a sequential number beginning from one that
 235 increments with each file (or directory) sent.
 236
 237 where {\bf \lt{}Stream-Id\gt{}} will be 1 for the Attributes record and 2 for
 238 uncompressed File data. 3 is reserved for the MD5 signature for the file.
 239
 240 where {\bf \lt{}Info\gt{}} transmit information about the Stream to the
 241 Storage Daemon. It is a character string field where each character has a
 242 meaning. The only character currently defined is 0 (zero), which is simply a
 243 place holder (a no op). In the future, there may be codes indicating
 244 compressed data, encrypted data, etc.
 245
 246 Immediately following the header packet, the Storage daemon will expect any
 247 number of data packets. The series of data packets is terminated by a zero
 248 length packet, which indicates to the Storage daemon that the next packet will
 249 be another header packet. As previously mentioned, a negative length packet is
 250 a request for the Storage daemon to temporarily enter command mode and send a
 251 reply to the File daemon. Thus an actual conversation might contain the
 252 following exchanges:
 253
 254 \footnotesize
 255 \begin{verbatim}
 256 FD: <1 1 0> (header packet)
 257 FD: <data packet containing file-attributes>
 258 FD: Null packet
 259 FD: <1 2 0>
 260 FD: <multiple data packets containing the file data>
 261 FD: Packet length = -1
 262 SD: 3000 OK
 263 FD: <2 1 0>
 264 FD: <data packet containing file-attributes>
 265 FD: Null packet
 266 FD: <2 2 0>
 267 FD: <multiple data packets containing the file data>
 268 FD: Null packet
 269 FD: Null packet
 270 FD: append end session <ticket-number>
 271 SD: 3000 OK end
 272 FD: append close session <ticket-number>
 273 SD: 3000 OK Volumes = <number of volumes>
 274 SD: 3001 Volume = <volumeid> <start file> <start block>
 275      <end file> <end block> <volume session-id>
 276 SD: 3002 Volume data = <date/time of last write> <Number bytes written>
 277      <number errors>
 278 SD: ... additional Volume / Volume data pairs for
 279      volumes 2 .. n
 280 FD: close socket
 281 \end{verbatim}
 282 \normalsize
 283
 284 The information returned to the File daemon by the Storage daemon in response
 285 to the {\bf append close session} is transmit in turn to the Director.