documentation/specification/xml_via_udp.txt


Submission of host data with XML UDP packets
============================================


<<< Provisional, pjm2@ukc.ac.uk >>>


Purpose of this document
------------------------

This document shall help to provide a separate party with
the knowledge required to use their own implementation of
a piece of host monitoring software.  In particular, this
document details the expected manner of data transfer from
a host to the central server.


Background
----------

Hosts are expected to periodically send UDP packets to the
central monitoring system.  Such packets may contain various
pieces of information about the host, such as how much free
memory is remaining on the host, etc.


Specification
-------------

It is the responsibility of the host monitoring software to
realise where to send its data, by means of some auto-
configuration system, or otherwise.

Each discrete bundle of data from the host must be sent via
a UDP packet to the central monitoring system.  There is no
limit to the size of this packet, however, the server may
reject packets that are too large.  The central monitoring
system may ignore any data after the first 8kb of each
packet, resulting in the possibility of such packets being
rejected due to malformed/incomplete contents.

The UDP packet must contain a complete and well-formed
pice of XML markup, describing the data that the host is
submitting.

The XML contents of the UDP packet may define a document
encoding standard, however, this is not a necessity as a
default encoding can be assumed, this being suitable in
most cases.

Any packets that do not parse as being valid XML shall be
rejected by the server.  This is likely to also include any
packets that have the closing root tag placed after 8kb from
the start of the packet's contents.

The XML markup within a packet is typically used to specify
the data that the host is submitting.  This must consist of
at least a root tag, called "packet".

For example, the bare minimum that a host should send is
the following: -

    <packet>
    </packet>

Note that every XML tag must also have a matching closing
tag.

The server can recognise parameter values within tags,
such as: -

    <packet machine_name="raptor" ip="aaa.bbb.ccc.ddd">
    </packet>

Data to be transmitted may be defined within the parameters
of tags (as above) or it may be defined within its own
tags, vis: -

    <packet>
        <machine_name>raptor</machine_name>
        <ip>aaa.bbb.ccc.ddd</ip>
    </packet>

To avoid confusion, it is clearly necessary to escape any
characters that may be incorrectly misinterpreted as XML by
the parser.

The XML structure may be free-form.  Any leading and
trailing spaces are ignored in values.  For example, the
following defines exactly the same data as the above
example: -

    <packet>
        <machine_name>
            raptor
        </machine_name>
        <ip>
            aaa.bbb.ccc.ddd
        </ip>
    </packet>

In cases where multiple data may be present, it may be more
useful to nest tags to a number of levels.  For example: -

    <packet>
        <machine_name>raptor</machine_name>
        <ip>aaa.bbb.ccc.ddd</ip>
        <freespace>
            <drive1>23677</drive1>
            <drive2>23534</drive2>
            <drive3>10390</drive3>
        </freespace>
    </packet>

Such formatting is perfectly acceptable by the server.
Packets may also contain comments, for example: -

    <packet>
        <!-- This is a comment! -->
        <machine_name>raptor</machine_name>
        <ip>aaa.bbb.ccc.ddd</ip>
        <freespace>
            <drive1>23677</drive1>
            <drive2>23534</drive2>
            <drive3>10390</drive3>
        </freespace>
    </packet>

Remember that malformed XML data would be rejected by the
central monitoring system without acting upon it.


Flexibility and Minimising bandwidth
------------------------------------

The means of submitting host data via UDP containing XML
markup is provided so that future customisation is easily
possible.  It would be possible to easily tailor a custom
piece of host monitoring software to provide exactly what
data is desired for adequate monitoring.

Some of the XML markup demonstrated above contains a lot
of rendundant features.  For example, it is not necessary
to lay the contents out neatly (although this certainly
helps visualise the contents).

The amount of data sent within each UDP packet may be (in
some cases, vastly) reduced by using some of the ideas
described below: -

  - Remove unnecessary linefeeds and 'white space'

  - If a single piece of data is to be represented, it
    will usually occupy less space if it is stored as
    an attribute to a tag, rather than within a pair
    of tags.

  - Comments within the XML may be useful for testing
    purposes, however, the server ignores all comments
    so these can be removed to reduce packet sizes.

Taking the above into account, this means that the final
XML example above may be turned into the following without
losing any information: -

    <packet machine_name="raptor" ip="aaa.bbb.ccc.ddd"
    ><freespace><drive1>23677</drive1><drive2>23534</d
    rive2><drive3>10390</drive3></freespace></packet>

Notice how all unnecessary 'white space' and linefeeds have
been removed.  The comment has also been removed.  Values
such as "machine_name" and "ip" have both been stored as an
attribute of the root node ("packet") as this results in
a smaller packet size.


About
-----

This document was written by Paul Mutton [pjm2@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.2
Committed:	Sat Nov 25 13:22:18 2000 UTC (24 years ago) by pjm2
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Changes since 1.1:	+3 -4 lines
Log Message:	Corrected the final XML example (after copying and pasting the wrong bit of one of my previous examples to produce the 'bandwidth minimised' version!)
#	Content
1
2	Submission of host data with XML UDP packets
3	============================================
4
5
6	<<< Provisional, pjm2@ukc.ac.uk >>>
7
8
9	Purpose of this document
10	------------------------
11
12	This document shall help to provide a separate party with
13	the knowledge required to use their own implementation of
14	a piece of host monitoring software. In particular, this
15	document details the expected manner of data transfer from
16	a host to the central server.
17
18
19	Background
20	----------
21
22	Hosts are expected to periodically send UDP packets to the
23	central monitoring system. Such packets may contain various
24	pieces of information about the host, such as how much free
25	memory is remaining on the host, etc.
26
27
28	Specification
29	-------------
30
31	It is the responsibility of the host monitoring software to
32	realise where to send its data, by means of some auto-
33	configuration system, or otherwise.
34
35	Each discrete bundle of data from the host must be sent via
36	a UDP packet to the central monitoring system. There is no
37	limit to the size of this packet, however, the server may
38	reject packets that are too large. The central monitoring
39	system may ignore any data after the first 8kb of each
40	packet, resulting in the possibility of such packets being
41	rejected due to malformed/incomplete contents.
42
43	The UDP packet must contain a complete and well-formed
44	pice of XML markup, describing the data that the host is
45	submitting.
46
47	The XML contents of the UDP packet may define a document
48	encoding standard, however, this is not a necessity as a
49	default encoding can be assumed, this being suitable in
50	most cases.
51
52	Any packets that do not parse as being valid XML shall be
53	rejected by the server. This is likely to also include any
54	packets that have the closing root tag placed after 8kb from
55	the start of the packet's contents.
56
57	The XML markup within a packet is typically used to specify
58	the data that the host is submitting. This must consist of
59	at least a root tag, called "packet".
60
61	For example, the bare minimum that a host should send is
62	the following: -
63
64	<packet>
65	</packet>
66
67	Note that every XML tag must also have a matching closing
68	tag.
69
70	The server can recognise parameter values within tags,
71	such as: -
72
73	<packet machine_name="raptor" ip="aaa.bbb.ccc.ddd">
74	</packet>
75
76	Data to be transmitted may be defined within the parameters
77	of tags (as above) or it may be defined within its own
78	tags, vis: -
79
80	<packet>
81	<machine_name>raptor</machine_name>
82	<ip>aaa.bbb.ccc.ddd</ip>
83	</packet>
84
85	To avoid confusion, it is clearly necessary to escape any
86	characters that may be incorrectly misinterpreted as XML by
87	the parser.
88
89	The XML structure may be free-form. Any leading and
90	trailing spaces are ignored in values. For example, the
91	following defines exactly the same data as the above
92	example: -
93
94	<packet>
95	<machine_name>
96	raptor
97	</machine_name>
98	<ip>
99	aaa.bbb.ccc.ddd
100	</ip>
101	</packet>
102
103	In cases where multiple data may be present, it may be more
104	useful to nest tags to a number of levels. For example: -
105
106	<packet>
107	<machine_name>raptor</machine_name>
108	<ip>aaa.bbb.ccc.ddd</ip>
109	<freespace>
110	<drive1>23677</drive1>
111	<drive2>23534</drive2>
112	<drive3>10390</drive3>
113	</freespace>
114	</packet>
115
116	Such formatting is perfectly acceptable by the server.
117	Packets may also contain comments, for example: -
118
119	<packet>
120	<!-- This is a comment! -->
121	<machine_name>raptor</machine_name>
122	<ip>aaa.bbb.ccc.ddd</ip>
123	<freespace>
124	<drive1>23677</drive1>
125	<drive2>23534</drive2>
126	<drive3>10390</drive3>
127	</freespace>
128	</packet>
129
130	Remember that malformed XML data would be rejected by the
131	central monitoring system without acting upon it.
132
133
134	Flexibility and Minimising bandwidth
135	------------------------------------
136
137	The means of submitting host data via UDP containing XML
138	markup is provided so that future customisation is easily
139	possible. It would be possible to easily tailor a custom
140	piece of host monitoring software to provide exactly what
141	data is desired for adequate monitoring.
142
143	Some of the XML markup demonstrated above contains a lot
144	of rendundant features. For example, it is not necessary
145	to lay the contents out neatly (although this certainly
146	helps visualise the contents).
147
148	The amount of data sent within each UDP packet may be (in
149	some cases, vastly) reduced by using some of the ideas
150	described below: -
151
152	- Remove unnecessary linefeeds and 'white space'
153
154	- If a single piece of data is to be represented, it
155	will usually occupy less space if it is stored as
156	an attribute to a tag, rather than within a pair
157	of tags.
158
159	- Comments within the XML may be useful for testing
160	purposes, however, the server ignores all comments
161	so these can be removed to reduce packet sizes.
162
163	Taking the above into account, this means that the final
164	XML example above may be turned into the following without
165	losing any information: -
166
167	<packet machine_name="raptor" ip="aaa.bbb.ccc.ddd"
168	><freespace><drive1>23677</drive1><drive2>23534</d
169	rive2><drive3>10390</drive3></freespace></packet>
170
171	Notice how all unnecessary 'white space' and linefeeds have
172	been removed. The comment has also been removed. Values
173	such as "machine_name" and "ip" have both been stored as an
174	attribute of the root node ("packet") as this results in
175	a smaller packet size.
176
177
178	About
179	-----
180
181	This document was written by Paul Mutton [pjm2@ukc.ac.uk]
182	for use by the team working on a 3rd year Computer Science
183	project called "i-scream". More details can be found on the
184	project website - http://www.i-scream.org.uk