4 \section*{TCP/IP Network Protocol}
6 \index{TCP/IP Network Protocol }
7 \index{Protocol!TCP/IP Network }
8 \addcontentsline{toc}{section}{TCP/IP Network Protocol}
12 \addcontentsline{toc}{subsection}{General}
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.
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
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.
31 \subsection*{bnet and Threads}
32 \index{Threads!bnet and }
33 \index{Bnet and Threads }
34 \addcontentsline{toc}{subsection}{bnet and Threads}
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.
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.
47 \subsection*{bnet\_open}
49 \addcontentsline{toc}{subsection}{bnet\_open}
51 To establish a connection to a server, use the subroutine:
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.
60 \subsection*{bnet\_send}
62 \addcontentsline{toc}{subsection}{bnet\_send}
64 To send a packet, one uses the subroutine:
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:
79 In the case of a failure, an error message will be sent to the JCR contained
80 within the bsock packet.
82 \subsection*{bnet\_fsend}
84 \addcontentsline{toc}{subsection}{bnet\_fsend}
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
92 \subsection*{Additional Error information}
93 \index{Information!Additional Error }
94 \index{Additional Error information }
95 \addcontentsline{toc}{subsection}{Additional Error information}
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).
104 \subsection*{bnet\_recv}
106 \addcontentsline{toc}{subsection}{bnet\_recv}
108 To read a packet, one uses the subroutine:
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:
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
126 It should be noted that bnet\_recv() is a blocking read.
128 \subsection*{bnet\_sig}
130 \addcontentsline{toc}{subsection}{bnet\_sig}
132 To send a ``signal'' from one daemon to another, one uses the subroutine:
134 int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following:
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
148 \subsection*{bnet\_strerror}
149 \index{Bnet\_strerror }
150 \addcontentsline{toc}{subsection}{bnet\_strerror}
152 Returns a formated string corresponding to the last error that occurred.
154 \subsection*{bnet\_close}
156 \addcontentsline{toc}{subsection}{bnet\_close}
158 The connection with the server remains open until closed by the subroutine:
160 void bnet\_close(BSOCK *sock)
162 \subsection*{Becoming a Server}
163 \index{Server!Becoming a }
164 \index{Becoming a Server }
165 \addcontentsline{toc}{subsection}{Becoming a Server}
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.
174 \subsection*{Higher Level Conventions}
175 \index{Conventions!Higher Level }
176 \index{Higher Level Conventions }
177 \addcontentsline{toc}{subsection}{Higher Level Conventions}
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:
185 S: wait for connection C: attempt connection
186 S: accept connection C: bnet_send() send request
187 S: bnet_recv() wait for request
189 S: bnet_send() send ack C: bnet_recv() wait for ack
193 Thus a single command is sent, acted upon by the server, and then
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
204 while ((n=bnet_recv(bsock)) > 0) {
212 The client will perform the following:
219 bnet_sig(bsock, BNET_EOD);
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.