Debian Codegraph @

manuals/en/developers/netprotocol.tex

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