ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
Revision: 1.8
Committed: Tue Feb 27 18:45:15 2001 UTC (23 years, 2 months ago) by tdb
Content type: text/plain
Branch: MAIN
Changes since 1.7: +11 -0 lines
Log Message: 
Added a feature to send the FQDN of the connected host.

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