ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
Revision: 1.6
Committed: Sun Jan 28 22:01:14 2001 UTC (23 years, 9 months ago) by tdb
Content type: text/plain
Branch: MAIN
Changes since 1.5: +65 -61 lines
Log Message: 
A few changes in the client-server protocol.

File Contents

# Content
1 i-scream Protocols
2 ==================
3
4 Contents
5 --------
6 - Conventions
7
8 - Host Connection Protocol
9 - Host Heartbeat Protocol
10 - Host Data Protocol
11
12 - Client Control Protocol
13 - Client Data Protocol
14
15 Conventions
16 -----------
17 All protocols in this document assume a valid connection of
18 the appropriate type has been made, and that data streams
19 are already available. All strings should, and will be,
20 terminated with a \n (newline character) to indicate the end
21 of the message. All messages are sent as ASCII Strings.
22
23 Fixed protocol messages will appear in [] brackets, if there
24 is a variety of options they will be separated with the |
25 character. For example:
26
27 [OK|ERROR]
28
29 Indicates that the message "OK" OR the message "ERROR" will
30 be sent depending on the result of the last action.
31
32 Data messages will appear in {} brackets, where the name in
33 the brackets indicates the type (as in kind, not data type)
34 of data that will be returned. For example:
35
36 {lastmodified}
37
38 Indicates that data for use as 'last modified' will be
39 returned.
40
41 If [ERROR] is sent back at any time, this indicates that all
42 communication is over. EXCEPT where otherwise specified!
43
44 Host Connection Protocol
45 ------------------------
46 The initial connection of a host to the i-scream server is
47 through the FilterManager. A Host gets its configuration
48 and then gets assigned a Filter to connect to and start
49 sending data.
50
51 The port number of the FilterManager is fully configurable,
52 however the default at this time is 4567.
53
54 Host (direction) Server Comment
55 ------------------------------------------------------------
56 [STARTCONFIG]----------> Requests to start
57 receiving config
58 information
59
60 <---------- [OK|ERROR] If the server ok's
61 the request or not
62
63 [LASTMODIFIED]----------> Asks when the config
64 was last modified
65 (used when checking
66 if the config has
67 changed)
68
69 <---------- [{lastmodified}Returns a long int
70 |ERROR] time since epoch
71 eg, 123456789
72 To indicate what
73 format this is in,
74 I quote from the
75 Java 1.3 JDK API
76 "measured in milli
77 -seconds since the
78 epoch"
79
80 [FILELIST] ----------> Asks the server for
81 the list of files
82 that were used to
83 build the config
84 (used when checking
85 if the config has
86 changed)
87
88 <---------- [{filelist} Returns a semi-colon
89 |ERROR] separated list of
90 filenames
91 eg,
92 a.conf;b.conf;c.conf
93
94 ********** LOOP START **********
95 This loop reads configuration
96 properties from the config
97
98 [{property}] ----------> Sends the name of a
99 property to be
100 retrieved from the
101 config file
102 eg, UDPUpdateTime
103
104 <---------- [{value}|ERROR]Returns the value of
105 the requested config
106 property
107 eg, 120
108 If it is unable to
109 find the requested
110 property it returns
111 ERROR to indicate
112 that fact, but
113 communication still
114 proceeds
115
116 ********** LOOP UNTIL **********
117 The loop continues until the host
118 sends the following message
119
120 [ENDCONFIG] ----------> Indicates that the
121 host requires no
122 more config
123
124 ********** LOOP END **********
125 Communication continues
126
127 <---------- [OK] Indicates that the
128 server is ready to
129 proceed
130
131 [FILTER] ----------> Asks the server to
132 send it the host
133 information of a
134 filter that it
135 should connect to
136
137 <---------- {filter} Returns a semi-colon
138 separated list of
139 FQDN hostname, UDP
140 port number and TCP
141 port number that a
142 configured Filter is
143 running on and
144 assigned to the
145 calling host
146 eg,
147 raptor.ukc.ac.uk;
148 1234;5678
149
150 [END] ----------> Indicates to the
151 server that the host
152 has finished an will
153 disconnect
154
155 <---------- [OK|ERROR] Indicates that the
156 server is either ok
157 or that it thought
158 there was an error
159 ------------------------------------------------------------
160
161 Host Heartbeat Protocol
162 -----------------------
163 When a host is configured after it has connected it should
164 obtain a property TCPUpdateTime. This indicates how often
165 a host should send a "Heart Beat", which is a pro-active
166 connection to the server by the host to indicate that it is
167 still alive. This "Heart Beat" also allows a host to see
168 its configuration has changed and act accordingly. In a
169 well written host this should just be a case of dropping out
170 of a loop and heading back to the start (connecting to the
171 filter manager).
172
173 Host (direction) Server Comment
174 ------------------------------------------------------------
175 [HEARTBEAT] ----------> Starts the
176 heartbeat protocol
177 off
178
179 <---------- [OK|ERROR] Indicates that the
180 server is ok or not
181
182 [CONFIG] ----------> Indicates that the
183 host wants to check
184 its config
185
186 <---------- [OK|ERROR] Indicates that the
187 server is ok or not
188
189 [{filelist}] ----------> Send a semi-colon
190 separated list of
191 filenames
192 eg,
193 a.conf;b.conf;c.conf
194 This should be
195 identical to the one
196 received in the
197 connection protocol
198
199 <---------- [OK] Indicates that the
200 server is ok
201
202 [{lastmodified}]----------> Returns a long int
203 time since epoch
204 eg, 123456789
205 This should be
206 identical to the one
207 received in the
208 connection protocol
209 To indicate what
210 format this is in,
211 I quote from the
212 Java 1.3 JDK API
213 "measured in milli
214 -seconds since the
215 epoch"
216
217 <---------- [OK|ERROR] The server then
218 checks all the files
219 in the file list to
220 see if they have
221 been modified more
222 recently than the
223 lastmodified value.
224 If they HAVE that
225 indicates that the
226 configuration has
227 changed and the host
228 should re-configure,
229 thus it sends ERROR.
230 If the files remain
231 unchanged the server
232 will return OK to
233 indicate the host
234 should continue as
235 before
236
237 [ENDHEARTBEAT] ----------> Indicates to the
238 server that the host
239 has finished an will
240 disconnect
241
242 <---------- [OK|ERROR] Indicates that the
243 server is either ok
244 or that it thought
245 there was an error
246 ------------------------------------------------------------
247
248 Host Data Protocol
249 ------------------
250 The UDP data packets that are sent by the host contain
251 simply XML data. For information on the format of this
252 data see the XML via UDP specification document at:
253
254 http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
255
256 Client Control Protocol
257 -----------------------
258
259 The client control protocol channel is opened by the client
260 and allows a variety of actions to be carried out by the
261 client at anytime. Unlike previous protocols, this is NOT
262 sequential, all of the requests can be carried out in
263 any order.
264
265 All client protocols are backwards compatible, and the
266 version is shown by the protocol identifier.
267
268 There are three sections to this protocol.
269
270 1) Initialise (sent only at start)
271 2) Send command(s) - unlimited number in any order
272 3) Disconnect (sent only at end)
273
274 If at anytime the client sends something the server does
275 not understand, an [ERROR] will be sent
276
277 All are indicated with <> brackets.
278
279 v1.0 - Protocol identifier: "PROTOCOL 1.0" (without quotes)
280 Supported commands:
281 STARTCONFIG
282 STARTDATA
283 STOPDATA
284
285 Host (direction) Server Comment
286 ------------------------------------------------------------
287 <initialise>
288 [CONNECT] ----------> Starts off the
289 client protocol
290
291 <---------- [{protocol}] The server sends the
292 protocol identifier
293
294 [{name}] ----------> The client sends its
295 "name". This name
296 is used to identify
297 the type of client
298 to the system and
299 obtain its config
300 eg, Conient
301
302 <---------- [OK] Indicates the server
303 is ok to proceed
304
305
306 <command #1> (allows client to obtain its configuration)
307 [STARTCONFIG]----------> Tell the server we
308 want to start this
309 command
310
311 <---------- [OK] Indicates the server
312 is ok to proceed
313
314 ********** LOOP START **********
315 This loop reads configuration
316 properties from the config
317
318 [{property}] ----------> Sends the name of a
319 property to be
320 retrieved from the
321 config file
322 Clients can obtain
323 host information
324 eg,
325 Host.UDPUpdateTime
326 Otherwise it must
327 prefix requests
328 with "Client."
329 All other requests
330 will be ignored as
331 if it was unable to
332 retrieve the
333 property
334
335 <---------- [{value}|ERROR]Returns the value of
336 the requested config
337 property
338 eg, 120
339 If it is unable to
340 find the requested
341 property it returns
342 ERROR to indicate
343 that fact
344
345 ********** LOOP UNTIL **********
346 The loop continues until the client
347 sends the following message
348
349 [ENDCONFIG] ----------> Indicates that the
350 client requires no
351 more config
352
353 ********** LOOP END **********
354 Communication continues
355
356 <---------- [OK] Indicates that the
357 server is ready to
358 proceed
359
360 <command #2> (tells the server to start the data link)
361 [STARTDATA] ----------> Tell the server we
362 want to start this
363 command
364
365 <---------- [{portnumber} The server then sets
366 |ERROR] itself listening for
367 a connection on its
368 data link socket for
369 this client. It
370 returns the port no.
371 that it is listening
372 on eg, 12367
373 If the data link is
374 already started the
375 server will return
376 ERROR
377
378 <---------- [OK] Indicates the client
379 has successfully
380 connected to the
381 data socket.
382
383 <command #3> (tells the server to stop the data link)
384 [STOPDATA] ----------> Tell the server we
385 want to start this
386 command
387 The server then
388 shuts down the
389 data link to the
390 client
391
392 <---------- [OK|ERROR] Returns OK is the
393 server is ready to
394 proceed, or ERROR
395 if the data link
396 was not open in the
397 first place
398
399 <disconnect>
400 [DISCONNECT] ----------> Tells the server the
401 client wants to
402 close the control
403 link
404
405 <---------- [OK] The last word from
406 the server, it will
407 disappear after
408 this, and close the
409 data link if
410 required
411 ------------------------------------------------------------
412
413 v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes)
414 Supported commands:
415 SETHOSTLIST
416
417 Host (direction) Server Comment
418 ------------------------------------------------------------
419 <command #4> (indicates to the server which hosts the client
420 wants data from)
421 [SETHOSTLIST]----------> Tell the server we
422 want to start this
423 command
424
425 <---------- [OK|ERROR] The server will
426 return an ERROR if
427 the data link is
428 open, as a host list
429 must ONLY be set
430 if the data link is
431 closed
432 If the server is
433 ok to proceed with
434 the command it says
435 [OK]
436
437 [{hostlist}] ----------> This is a semi-colon
438 seperated list of
439 FQDN hostnames that
440 the client wishes to
441 recieve data from
442 eg,
443 raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk
444
445 If the list is sent
446 blank (or if no list
447 is set at all) then
448 data from ALL hosts
449 will be sent to the
450 client (this is the
451 default if no
452 SETHOSTLIST is not
453 run by the client
454
455 <---------- [OK] Indicates the server
456 is ok to proceed and
457 the host list has
458 been accepted
459 ------------------------------------------------------------
460
461 Client Data Protocol
462 --------------------
463 Once the data link has been opened by the control link, the
464 server will send XML formatted data packets separated by the
465 \n (newline) character. For information on the format of
466 this data see the XML via UDP specification document at:
467
468 http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
469
470 About
471 -----
472 This document was written by AJ Moore [ajm4@ukc.ac.uk] for
473 use by the team working on a 3rd year Computer Science
474 project called "i-scream". More details can be found on the
475 project website;
476
477 http://www.i-scream.org.uk