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 (23 years, 5 months 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!)
#	User	Rev	Content
1	pjm2	1.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	pjm2	1.2	<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	pjm2	1.1
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