git.sur5r.net Git - bacula/docs/blob - docs/manual-fr/netprotocol.tex

   1 %%
   2 %%
   3
   4 \section*{TCP/IP Network Protocol}
   5 \label{_ChapterStart5}
   6 \index{TCP/IP Network Protocol }
   7 \index{Protocol!TCP/IP Network }
   8 \addcontentsline{toc}{section}{TCP/IP Network Protocol}
   9
  10 \subsection*{General}
  11 \index{General }
  12 \addcontentsline{toc}{subsection}{General}
  13
  14 This document describes the TCP/IP protocol used by Bacula to communicate
  15 between the various daemons and services. The definitive definition of the
  16 protocol can be found in src/lib/bsock.h, src/lib/bnet.c and
  17 src/lib/bnet\_server.c.
  18
  19 Bacula's network protocol is basically a ``packet oriented'' protocol built on
  20 a standard TCP/IP streams. At the lowest level all packet transfers are done
  21 with read() and write() requests on system sockets. Pipes are not used as they
  22 are considered unreliable for large serial data transfers between various
  23 hosts.
  24
  25 Using the routines described below (bnet\_open, bnet\_write, bnet\_recv, and
  26 bnet\_close) guarantees that the number of bytes you write into the socket
  27 will be received as a single record on the other end regardless of how many
  28 low level write() and read() calls are needed. All data transferred are
  29 considered to be binary data.
  30
  31 \subsection*{bnet and Threads}
  32 \index{Threads!bnet and }
  33 \index{Bnet and Threads }
  34 \addcontentsline{toc}{subsection}{bnet and Threads}
  35
  36 These bnet routines work fine in a threaded environment. However, they assume
  37 that there is only one reader or writer on the socket at any time. It is
  38 highly recommended that only a single thread access any BSOCK packet. The
  39 exception to this rule is when the socket is first opened and it is waiting
  40 for a job to start. The wait in the Storage daemon is done in one thread and
  41 then passed to another thread for subsequent handling.
  42
  43 If you envision having two threads using the same BSOCK, think twice, then you
  44 must implement some locking mechanism. However, it probably would not be
  45 appropriate to put locks inside the bnet subroutines for efficiency reasons.
  46
  47 \subsection*{bnet\_open}
  48 \index{Bnet\_open }
  49 \addcontentsline{toc}{subsection}{bnet\_open}
  50
  51 To establish a connection to a server, use the subroutine:
  52
  53 BSOCK *bnet\_open(void *jcr, char *host, char *service, int port,  int *fatal)
  54 bnet\_open(), if successful, returns the Bacula sock descriptor pointer to be
  55 used in subsequent bnet\_send() and bnet\_read() requests. If not successful,
  56 bnet\_open() returns a NULL. If fatal is set on return, it means that a fatal
  57 error occurred and that you should not repeatedly call bnet\_open(). Any error
  58 message will generally be sent to the JCR.
  59
  60 \subsection*{bnet\_send}
  61 \index{Bnet\_send }
  62 \addcontentsline{toc}{subsection}{bnet\_send}
  63
  64 To send a packet, one uses the subroutine:
  65
  66 int bnet\_send(BSOCK *sock) This routine is equivalent to a write() except
  67 that it handles the low level details. The data to be sent is expected to be
  68 in sock-\gt{}msg and be sock-\gt{}msglen bytes. To send a packet, bnet\_send()
  69 first writes four bytes in network byte order than indicate the size of the
  70 following data packet. It returns:
  71
  72 \footnotesize
  73 \begin{verbatim}
  74  Returns 0 on failure
  75  Returns 1 on success
  76 \end{verbatim}
  77 \normalsize
  78
  79 In the case of a failure, an error message will be sent to the JCR contained
  80 within the bsock packet.
  81
  82 \subsection*{bnet\_fsend}
  83 \index{Bnet\_fsend }
  84 \addcontentsline{toc}{subsection}{bnet\_fsend}
  85
  86 This form uses:
  87
  88 int bnet\_fsend(BSOCK *sock, char *format, ...) and it allows you to send a
  89 formatted messages somewhat like fprintf(). The return status is the same as
  90 bnet\_send.
  91
  92 \subsection*{Additional Error information}
  93 \index{Information!Additional Error }
  94 \index{Additional Error information }
  95 \addcontentsline{toc}{subsection}{Additional Error information}
  96
  97 Fro additional error information, you can call {\bf is\_bnet\_error(BSOCK
  98 *bsock)} which will return 0 if there is no error or non-zero if there is an
  99 error on the last transmission. The {\bf is\_bnet\_stop(BSOCK *bsock)}
 100 function will return 0 if there no errors and you can continue sending. It
 101 will return non-zero if there are errors or the line is closed (no more
 102 transmissions should be sent).
 103
 104 \subsection*{bnet\_recv}
 105 \index{Bnet\_recv }
 106 \addcontentsline{toc}{subsection}{bnet\_recv}
 107
 108 To read a packet, one uses the subroutine:
 109
 110 int bnet\_recv(BSOCK *sock) This routine is similar to a read() except that it
 111 handles the low level details. bnet\_read() first reads packet length that
 112 follows as four bytes in network byte order. The data is read into
 113 sock-\gt{}msg and is sock-\gt{}msglen bytes. If the sock-\gt{}msg is not large
 114 enough, bnet\_recv() realloc() the buffer. It will return an error (-2) if
 115 maxbytes is less than the record size sent. It returns:
 116
 117 \footnotesize
 118 \begin{verbatim}
 119  * Returns number of bytes read
 120  * Returns 0 on end of file
 121  * Returns -1 on hard end of file (i.e. network connection close)
 122  * Returns -2 on error
 123 \end{verbatim}
 124 \normalsize
 125
 126 It should be noted that bnet\_recv() is a blocking read.
 127
 128 \subsection*{bnet\_sig}
 129 \index{Bnet\_sig }
 130 \addcontentsline{toc}{subsection}{bnet\_sig}
 131
 132 To send a ``signal'' from one daemon to another, one uses the subroutine:
 133
 134 int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following:
 135
 136 \begin{enumerate}
 137 \item BNET\_EOF - deprecated use BNET\_EOD
 138 \item BNET\_EOD - End of data stream, new data may follow
 139 \item BNET\_EOD\_POLL - End of data and poll all in one
 140 \item BNET\_STATUS - Request full status
 141 \item BNET\_TERMINATE - Conversation terminated, doing close()
 142 \item BNET\_POLL - Poll request, I'm hanging on a read
 143 \item BNET\_HEARTBEAT - Heartbeat Response requested
 144 \item BNET\_HB\_RESPONSE - Only response permitted to HB
 145 \item BNET\_PROMPT - Prompt for UA
 146    \end{enumerate}
 147
 148 \subsection*{bnet\_strerror}
 149 \index{Bnet\_strerror }
 150 \addcontentsline{toc}{subsection}{bnet\_strerror}
 151
 152 Returns a formated string corresponding to the last error that occurred.
 153
 154 \subsection*{bnet\_close}
 155 \index{Bnet\_close }
 156 \addcontentsline{toc}{subsection}{bnet\_close}
 157
 158 The connection with the server remains open until closed by the subroutine:
 159
 160 void bnet\_close(BSOCK *sock)
 161
 162 \subsection*{Becoming a Server}
 163 \index{Server!Becoming a }
 164 \index{Becoming a Server }
 165 \addcontentsline{toc}{subsection}{Becoming a Server}
 166
 167 The bnet\_open() and bnet\_close() routines described above are used on the
 168 client side to establish a connection and terminate a connection with the
 169 server. To become a server (i.e. wait for a connection from a client), use the
 170 routine {\bf bnet\_thread\_server}. The calling sequence is a bit complicated,
 171 please refer to the code in bnet\_server.c and the code at the beginning of
 172 each daemon as examples of how to call it.
 173
 174 \subsection*{Higher Level Conventions}
 175 \index{Conventions!Higher Level }
 176 \index{Higher Level Conventions }
 177 \addcontentsline{toc}{subsection}{Higher Level Conventions}
 178
 179 Within Bacula, we have established the convention that any time a single
 180 record is passed, it is sent with bnet\_send() and read with bnet\_recv().
 181 Thus the normal exchange between the server (S) and the client (C) are:
 182
 183 \footnotesize
 184 \begin{verbatim}
 185 S: wait for connection            C: attempt connection
 186 S: accept connection              C: bnet_send() send request
 187 S: bnet_recv() wait for request
 188 S: act on request
 189 S: bnet_send() send ack            C: bnet_recv() wait for ack
 190 \end{verbatim}
 191 \normalsize
 192
 193 Thus a single command is sent, acted upon by the server, and then
 194 acknowledged.
 195
 196 In certain cases, such as the transfer of the data for a file, all the
 197 information or data cannot be sent in a single packet. In this case, the
 198 convention is that the client will send a command to the server, who knows
 199 that more than one packet will be returned. In this case, the server will
 200 enter a loop:
 201
 202 \footnotesize
 203 \begin{verbatim}
 204 while ((n=bnet_recv(bsock)) > 0) {
 205    act on request
 206 }
 207 if (n < 0)
 208    error
 209 \end{verbatim}
 210 \normalsize
 211
 212 The client will perform the following:
 213
 214 \footnotesize
 215 \begin{verbatim}
 216 bnet_send(bsock);
 217 bnet_send(bsock);
 218 ...
 219 bnet_sig(bsock, BNET_EOD);
 220 \end{verbatim}
 221 \normalsize
 222
 223 Thus the client will send multiple packets and signal to the server when all
 224 the packets have been sent by sending a zero length record.