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

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