ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
Revision: 1.9
Committed: Wed Mar 14 13:14:57 2001 UTC (24 years, 7 months ago) by tdb
Content type: text/plain
Branch: MAIN
Changes since 1.8: +4 -1 lines
Log Message: 
Clarified the protocol if a Filter cannot be found.

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