documentation/specification/protocols.txt

i-scream Protocols
==================

Contents
--------
 - Conventions

 - Host Connection Protocol
 - Host Heartbeat Protocol
 - Host Data Protocol

 - Client Control Protocol
 - Client Data Protocol

Conventions
-----------
All protocols in this document assume a valid connection of
the appropriate type has been made, and that data streams
already available.  All strings should and will be 
terminated with a \n (newline character) to indicate the end
of the message.  All messages are sent as ASCII Strings.

Fixed protocol messages will appear in [] brackets, if there
is a variety of options they will be seperated with the |
character.  For example:

    [OK|ERROR]
    
Indicates that the message "OK" OR the message "ERROR" will
be sent depending on the result of the last action.

Data messages will appear in {} brackets, where the name in
the brackets indicates the type (as in kind, not data type)
of data that will be returned.  For example:

    {lastmodified}

Indicates that data indicating for use as last modified will
be returned.    

If ever [ERROR] is sent back at any time, this indicates
that all communication is over. EXCEPT where specified!

Host Connection Protocol
------------------------
The initial connection of a host to the i-scream server is
through the FilterManager.  A Host gets its configuration
and then gets assigned a filter to connect to and start
sending data.

The port number of the filter manager is fully configurable,
however the default at this time is 4567.

Host         (direction) Server         Comment
------------------------------------------------------------
[STARTCONFIG]---------->                Requests to start
                                        receiving config
                                        information
             
             <---------- [OK|ERROR]     If the server ok's
                                        the request or not

[LASTMODIFIED]---------->               Asks when the config
                                        was last modified
                                        (used when checking
                                        if the config has 
                                        changed)
             
             <---------- [{lastmodified}Returns a long int
                         |ERROR]        time since epoc
                                        eg, 123456789

[FILELIST]   ---------->                Asks the server for
                                        the list of files
                                        that were used to
                                        build the config
                                        (used when checking
                                        if the config has
                                        changed)
        
             <---------- [{filelist}    Returns a semi-colon
                         |ERROR]        seperated list of
                                        filenames
                                        eg,
                                        a.conf;b.conf;c.conf

             ********** LOOP START **********
             This loop reads configuration
             properties from the config

[{property}] ---------->                Sends the name of a
                                        property to be
                                        retrieved from the
                                        config file
                                        eg, UDPUpdateTime
             
             <---------- [{value}|ERROR]Returns the value of
                                        the requested config
                                        property
                                        eg, 120
                                        If it is unable to
                                        find the requested 
                                        property it returns
                                        ERROR to indicate
                                        that fact
                                        
             ********** LOOP UNTIL **********
             The loop continues until the host
             sends the following message
             
[ENDCONFIG]  ---------->                Indicates that the 
                                        host requires no
                                        more config
             
             ********** LOOP  END **********
             Communication continues
             
             <---------- [OK]           Indicates that the
                                        server is ready to
                                        proceed
                                        
[FILTER]     ---------->                Asks the server to
                                        send it the host
                                        information of a 
                                        filter that it
                                        should connect to
                                        
             <---------- {filter}       Returns a semi-colon
                                        seperated list of
                                        FQDN hostname, UDP
                                        port number and TCP
                                        port number that a 
                                        configured Filter is
                                        running on and
                                        assigned to the 
                                        calling host
                                        eg,
                                        raptor.ukc.ac.uk;
                                        1234;5678

[END]        ---------->                Indicates to the
                                        server that the host
                                        has finished an will
                                        disconnect
             
             <---------- [OK|ERROR]     Indicates that the
                                        server is either ok
                                        or that it thought
                                        there was an error
        
Host Heartbeat Protocol
-----------------------
When a host is configured after it has connected it should
obtain a property TCPUpdateTime.  This indicates how often
a host should send a "Heart Beat" which is a pro-active
connection to the server by the host to indicate that it is
still alive.  This "Heart Beat" also allows a host to see
its configuration has changed and act accordingly.  In a 
well written host this should just be a case of dropping out
of a loop and heading back to the start (connecting to the
filter manager).

Host            (direction) Server      Comment
------------------------------------------------------------
[HEARTBEAT]     ---------->             Starts the
                                        heartbeat protocol
                                        off
                                        
                <---------- [OK|ERROR]  Indicates that the
                                        server is ok or not

[CONFIG]        ---------->             Indicates that the
                                        host wants to check
                                        its config

                <---------- [OK|ERROR]  Indicates that the
                                        server is ok or not

[{filelist}]    ---------->             Send a semi-colon
                                        seperated list of
                                        filenames
                                        eg,
                                        a.conf;b.conf;c.conf
                                        This should be
                                        identical to the one
                                        recieved in the 
                                        connection protocol

                <---------- [OK]        Indicates that the
                                        server is ok

[{lastmodified}]---------->             Returns a long int
                                        time since epoc
                                        eg, 123456789
                                        This should be
                                        identical to the one
                                        recieved in the 
                                        connection protocol

                <---------- [OK|ERROR]  The server then
                                        checks all the files
                                        in the file list to
                                        see if they have
                                        been modified more
                                        recently than the
                                        lastmodified value
                                        if they HAVE that
                                        indicates that the
                                        configuration has
                                        changed and the host
                                        should re-configure,
                                        thus it sends ERROR.
                                        If the files remain
                                        unchanged the server
                                        will return OK to
                                        indicate the host
                                        should continue as
                                        before

[ENDHEARTBEAT]  ---------->             Indicates to the
                                        server that the host
                                        has finished an will
                                        disconnect
                
                <---------- [OK|ERROR]  Indicates that the
                                        server is either ok
                                        or that it thought
                                        there was an error

Host Data Protocol
------------------
The UDP data packets that are sent by the host contain
simply XML data.  For information on the format of this
data see the XML via UDP specification document at:

http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt

Client Control Protocol
-----------------------

<TODO>

Client Data Protocol
--------------------

<TODO>

About
-----
This document was written by AJ Moore [ajm4@ukc.ac.uk] for
use by the team working on a 3rd year Computer Science
project called "i-scream". More details can be found on the
project website;

http://www.i-scream.org.uk
Revision:	1.1
Committed:	Sun Jan 28 18:35:31 2001 UTC (23 years, 10 months ago) by ajm
Content type:	text/plain
Branch:	MAIN
Log Message:	initial checkin still not done the client side protocols....watch this space ;-) over to Tim for the sp's ;-p
#	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	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 seperated 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 indicating for use as last modified will
39	be returned.
40
41	If ever [ERROR] is sent back at any time, this indicates
42	that all communication is over. EXCEPT where 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 filter manager 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 epoc
71	eg, 123456789
72
73	[FILELIST] ----------> Asks the server for
74	the list of files
75	that were used to
76	build the config
77	(used when checking
78	if the config has
79	changed)
80
81	<---------- [{filelist} Returns a semi-colon
82	\|ERROR] seperated list of
83	filenames
84	eg,
85	a.conf;b.conf;c.conf
86
87	******** LOOP START ********
88	This loop reads configuration
89	properties from the config
90
91	[{property}] ----------> Sends the name of a
92	property to be
93	retrieved from the
94	config file
95	eg, UDPUpdateTime
96
97	<---------- [{value}\|ERROR]Returns the value of
98	the requested config
99	property
100	eg, 120
101	If it is unable to
102	find the requested
103	property it returns
104	ERROR to indicate
105	that fact
106
107	******** LOOP UNTIL ********
108	The loop continues until the host
109	sends the following message
110
111	[ENDCONFIG] ----------> Indicates that the
112	host requires no
113	more config
114
115	******** LOOP END ********
116	Communication continues
117
118	<---------- [OK] Indicates that the
119	server is ready to
120	proceed
121
122	[FILTER] ----------> Asks the server to
123	send it the host
124	information of a
125	filter that it
126	should connect to
127
128	<---------- {filter} Returns a semi-colon
129	seperated list of
130	FQDN hostname, UDP
131	port number and TCP
132	port number that a
133	configured Filter is
134	running on and
135	assigned to the
136	calling host
137	eg,
138	raptor.ukc.ac.uk;
139	1234;5678
140
141	[END] ----------> Indicates to the
142	server that the host
143	has finished an will
144	disconnect
145
146	<---------- [OK\|ERROR] Indicates that the
147	server is either ok
148	or that it thought
149	there was an error
150
151	Host Heartbeat Protocol
152	-----------------------
153	When a host is configured after it has connected it should
154	obtain a property TCPUpdateTime. This indicates how often
155	a host should send a "Heart Beat" which is a pro-active
156	connection to the server by the host to indicate that it is
157	still alive. This "Heart Beat" also allows a host to see
158	its configuration has changed and act accordingly. In a
159	well written host this should just be a case of dropping out
160	of a loop and heading back to the start (connecting to the
161	filter manager).
162
163	Host (direction) Server Comment
164	------------------------------------------------------------
165	[HEARTBEAT] ----------> Starts the
166	heartbeat protocol
167	off
168
169	<---------- [OK\|ERROR] Indicates that the
170	server is ok or not
171
172	[CONFIG] ----------> Indicates that the
173	host wants to check
174	its config
175
176	<---------- [OK\|ERROR] Indicates that the
177	server is ok or not
178
179	[{filelist}] ----------> Send a semi-colon
180	seperated list of
181	filenames
182	eg,
183	a.conf;b.conf;c.conf
184	This should be
185	identical to the one
186	recieved in the
187	connection protocol
188
189	<---------- [OK] Indicates that the
190	server is ok
191
192	[{lastmodified}]----------> Returns a long int
193	time since epoc
194	eg, 123456789
195	This should be
196	identical to the one
197	recieved in the
198	connection protocol
199
200	<---------- [OK\|ERROR] The server then
201	checks all the files
202	in the file list to
203	see if they have
204	been modified more
205	recently than the
206	lastmodified value
207	if they HAVE that
208	indicates that the
209	configuration has
210	changed and the host
211	should re-configure,
212	thus it sends ERROR.
213	If the files remain
214	unchanged the server
215	will return OK to
216	indicate the host
217	should continue as
218	before
219
220	[ENDHEARTBEAT] ----------> Indicates to the
221	server that the host
222	has finished an will
223	disconnect
224
225	<---------- [OK\|ERROR] Indicates that the
226	server is either ok
227	or that it thought
228	there was an error
229
230	Host Data Protocol
231	------------------
232	The UDP data packets that are sent by the host contain
233	simply XML data. For information on the format of this
234	data see the XML via UDP specification document at:
235
236	http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
237
238	Client Control Protocol
239	-----------------------
240
241	<TODO>
242
243	Client Data Protocol
244	--------------------
245
246	<TODO>
247
248	About
249	-----
250	This document was written by AJ Moore [ajm4@ukc.ac.uk] for
251	use by the team working on a 3rd year Computer Science
252	project called "i-scream". More details can be found on the
253	project website;
254
255	http://www.i-scream.org.uk