XML Protocol Training Guide
XML Protocol Training Guide
1
Objective
Page 2
2
Presentation Contents
Page 3
3
Generic PDU Builder
• The new RT900 6.0 application introduces a new Generic PDU Builder
using a different infrastructure to IP-Performance.
• The Generic PDU Builder is a software tool for creating and decoding
PDUs, or packets, for a wide and growing range of protocols.
• The new Generic PDU builder offers the following advantages:
• PDU's can be edited at a field level and may be saved and
restored
• The ability to nest any protocol inside any other to an arbitrary
depth.
• Predefined packet types, which allow you to create multi-layer
packets in one step.
Page 4
4
Generic PDU Builder
Page 5
5
Generic PDU Builder
Page 6
The above screen shot shows the GUI for the Generic PDU builder.
Any protocol can be placed over any other protocol.
The example shows BGP over TCP over L2TP over IP over Ethernet.
6
XML Basics - Files
Page 7
XML is a language primarily used by Web designers to create Internet web pages.
It is a very flexible and easy to learn language used for expressing data.
7
XML Basics – Files on RT900
Page 8
XML is used by the RT900 application to Build and Decode any protocol which is to
be tested.
There is a directory on the Hard Disk where all the XML files are stored – C:\Program
Files\Agilent\RouterTester\Protocols
There are pre-defined XML files for various protocols with the naming convention:
AgtPdu_PROTOCOL.xml. You can however create your own files in the directory
C:\Program Files\Agilent\RouterTester\UserProtocols
8
XML Basics - Tags
XML files is made up of a series of tags. A tag holds specific information about a
certain entity.
Data is enclosed between a pair of tags – Start Tag and End Tag.
EG. <protocol> is the Start Tag. </protocol> is the End Tag. Not the / in the
End Tag.
Tags can be nested in other tags.
There is always ONE ROOT TAG. All other tags are enclosed within the root tag.
9
XML Basics – Tags - Attributes
• A tag may also have attributes defined within the start tag’s brackets, eg:
• <field name="source_port" length="16“> </field>
Start Tag Attribute Value Attribute Value End Tag
Page 10
A Tag will have an attribute which describes the properties of that tag.
The attributes are defined inside the Start Tag’s brackets.
The attribute is followed by the equals character = and then a value enclosed in
quotes “”.
Multiple attributes must be separated by at least one space character. But they can
also be on separate lines if you want to.
The name attribute must always be the first attribute specified.
10
XML Basics – Tags - Attributes
Data in an XML files can be represented by the attributes or by data within two
tags.
The protocol descriptions for the RT900 Generic PDU builder have all the data
represented as attributes. This makes it a lot easier to code and more standard.
Therefore, all the tags in a Protocol XML file will be empty. There will be nothing in
between the Start and End Tags – only attributes of the tag.
When there is no data in between tags, an end tag is not needed. The / can be put
before the end of the Start Tag.
So, <field name =“source_port”> </field> can be shortened to <field
name =“source_port”/>
11
XML Basics – Header and Comments
Page 12
12
XML Basics – Other Information
• Many modern editors have inbuilt support for XML. Microsoft also
has a free "XML notepad" tool which may be downloaded from their
site.Word editors like Word/EditPlus can also be used to create XML
files.
• XML is case sensitive BUT, the Tcl PDU builder code is case
insensitive.
• Also, XML documents can be viewed by Microsoft Internet
Explorer. This can be useful for checking for any syntax errors.
• Syntax checking can be enhanced with the use of an XML schema, a
special XML document which describes the tags used by the
application, the available attributes and how tags may be nested.
• A schema file: AgtPduSchema.xml is provided with the Generic PDU
Builder for just this purpose.
Page 13
XML files can be written in any text editor – such as Word or EditPlus.
There are special XML editors which can make it easier to write.
When the XML files are viewed in Internet Explorer, syntax errors can be seen.
A schema file called AgtPduSchema.xml is located in C:\Program
Files\Agilent\RouterTester\Protocols which describes the different tags that can be
used along with their attributes.
13
Writing Protocol Descriptions in XML
Page 14
14
Writing Protocol Descriptions in XML
Page 15
When writing Protocol Description XML files, all the possible fields/options should be
contained in the file.
Useful default values and default field selections should be set so that the PDU can
be sent when first loaded.
15
Writing Protocol Descriptions in XML
• There are only a handful of XML tags to learn to write your own protocol descriptions. All tags,
and their possible inter-relationships are shown in the skeleton document below:
• <ProtocolSet> <!– Root Tag -->
<enumSet> <!-- a global enumSet -->
<enum/>
</enumSet>
<protocol>
<enumSet> <!-- a local enumSet -->
<enum/>
</enumSet>
<field>
<enum/> <!-- an inline enum -->
</field>
<payload/>
</protocol>
<packetType>
<layer>
<preset/>
</layer>
</packetType>
</ProtocolSet> Page 16
All possible tags needed to create the XML file is shown above.
We see that <ProtocolSet> is the root tag, and may contain <enumSet>,
<protocol> and <packetType> tags.
The <protocol> tag, for example, may contain <enumSet>, <field> and
<payload> tags – this defines the message types and fields of a protocol.
Note that although a PDU instance may have fields deeply nested inside other
fields, the protocol description does not.
In the protocol description, all fields are treated as if they are at the same
hierarchical level.
The possible relationships between fields in a PDU instance are described using a set
of attributes called container attributes.
A <packetType> contains one or more layers which specify the protocol layers
within a pre-built packet.
16
Writing Protocol Descriptions in XML
• The Reference Guide will assist you in filling in the attributes for the
different tags.
Page 17
There is a XML reference guide which will help to fill in the attributes for the
different tags.
17
Writing Protocol Descriptions in XML – Example
1 Message Multiple Fields – Layer 2 over MPLS
Sequence
Reserved Flags Zero Length
Number
4 bits 4 Bits 2 Bits 6 Bits
16 Bits
The slide above shows the main XML code needed for L2oMPLS Control Words.
The protocol tag contains general attributes that describe the protocol: name and
standard. It also has a sequence attribute which defines what fields are contained
in the protocol. In this case, the Control Word is made up of : Reserved, Flags,
Zero, Length, Sequence Number fields.
The XML file then has a series of Field tags which describe each field in detail. For
example, the Reserved Field is 4 bits in length and is represented in Hex – it is
given a value of 0.
The fullName attribute is the text that appears on the RT900 PDU Builder GUI.
18
Writing Protocol Descriptions in XML – Example
1 Message Multiple Fields – Layer 2 over MPLS
Page 19
The above screen shot shows the GUI equivalent of the XML file on the previous
slide.
19
Writing Protocol Descriptions in XML – Example
Multiple Messages, Multiple Fields – BGP-4
MORE MORE
Marker Length Open_Type FIELDS Marker Length Update_Type FIELDS
128 bits 16 Bits 8 Bits NOT 128 bits 16 Bits 8 Bits NOT
SHOWN SHOWN
The purpose of this slide is to show how multiple MESSAGES are written into the
XML file.
BGP Runs over TCP Port 179. The selectRef attribute in the protocol tag is used
to define which PROTOCOL and FIELD the XML-protocol runs over. The
selectValue attribute defines the value of the field. In this case 179 is the value for
the Destination Port field in the TCP protocol.
In the above example the select attribute is used in the protocol tag to define the
different messages in the protocol (as opposed to the sequence attribute on the
previous slide for 1 message type).
The first two field tags in the above example, define the message and what fields
are contained in the message.
The bottom two field tags define the actual fields and associated values.
20
Writing Protocol Descriptions in XML – Example
Multiple Messages, Multiple Fields – BGP-4
Page 21
The above screen shot shows the GUI equivalent of the XML file on the previous
slide.
21
Writing Protocol Descriptions in XML – Example
Optional Fields – BGP-4
MORE Optional
Authentication
Marker Length Open_Type FIELDS Parameters Optional
NOT Parameters: Parameters:
128 bits 16 Bits 8 Bits Length Auth. Type
SHOWN 8 Bits
OPEN MESSAGE
The BGP Open message contains some Optional Fields – may or may not be present
in the message.
The message has a mandatory field Optional Parameters Length – which is 0 if
there are no optional fields.
The field Optional Parameters define what optional fields are available. The
attribute instance=”optional” defines that the field is Optional.
The length of the optional parameters will FILL in the Optional Parameters Length
field value – by using the attribute lengthRef.
The optional fields available is Authentication Parameters which contains the
auth_type parameter.
22
Writing Protocol Descriptions in XML – Example
Optional Fields – BGP-4
Page 23
The above screen shot shows the GUI equivalent of the XML file for the BGP
Optional Fields on the previous slide.
23
Writing Protocol Descriptions in XML – Example
– Enum Types – ARP – Hardware Types
Page 24
The ARP message contains many fields. One of the fields is called hw_type
(Hardware Type).
Next, the Enum Set is defined and given the name hardware_types.
In the Enum Set different Enum Values are given a name. EG. 1 is equivalent to
“Ethernet (10MB)”
Next, the field hw_type is associated with the Enum Set hardware_types.
24
Writing Protocol Descriptions in XML – Example
– Length Functions
• Sometimes protocols specify complex algorithms for determining the
value or length of certain fields, which are beyond the scope of the
generic algorithms of the PDU builder.
• To handle these situations, the Generic PDU builder provides hooks
for both internal and externally provided functions:
• Length functions derive a field length based on the value of another
field. Length functions are specified by the lengthFunction attribute of
the <protocol>, <field> or <payload> tags. The other field may be
any type of field and is specified by the lengthRef attribute.
<field name="header" lengthRef="hlen" lengthMultiplier="32"/>
Page 25
The values for some fields are dependant on the content of other fields.
Each length function must also be supplied with an inverse length function from
which the value can be derived from the length.
In the above example, the length of field "header" is derived by multiplying the
value of field "hlen" by 32.
25
Writing Protocol Descriptions in XML – Example
– Value Functions
• Value functions derive a field value based on the value of another
field. Value functions are specified by the valueFunction attribute of
the <field> tag. The "other field" may be any type of field and is
specified by the valueRef attribute.
<field name="header_checksum"
fullName="Header checksum"
length="16"
valueFunction="checksum"
valueRef="header">
• Currently, three internal value functions are provided,
• checksum
• crc (calculated in software).
• count
Page 26
26
Writing Protocol Descriptions in XML – Example
– External Functions
• In case a suitable internal function is not provided, you can create
your own length and value functions!
• External functions are written in TCL, and are made available to the
PDU Builder by putting the TCL source file into the same directory as
the protocol descriptions that reference them.
• A sample set of length and value functions has been provided in
ApbTclSampleFunctions.tcl. Use these sample procedures as a
starting point for your own functions.
Page 27
27
Writing Protocol Descriptions in XML –
Errors/Debugging
• If you edit an XML file, the changes will only be seen when you
restart the RT900 application.
• The XML files are stored in a common location on the RT900
controller. Care must be taken because incorrect XML files
created can cause problems for other users starting up the RT900
application.
• You must NOT have two protocol description files with the same
name.
• You must NOT have two global Enum Types with the same name.
• Field names must match up – watch out for typing mistakes.
Page 28
The XML files are loaded when the RT900 application is started. Modifying an XML
file while the RT900 application is running will not have any affect on the modified
protocol.
If you create an XML file by copying another file and converting it to the new
protocol – make sure that all the names are changed. Having the same protocol
name in 2 protocol files can cause errors.
Global Enum Types must also be kept unique.
If a message has a field, the corresponding field tag must be spelt the same way or
else the XML file will not load up correctly.
28
Writing Protocol Descriptions in XML –
Errors/Debugging
• Make sure the SelectRef and Field are spelt correctly for the
corresponding protocol.
• Make sure all Start Tags have the End Tags – unless its an empty tag.
• To make debugging easier, the GPB (Generic Pdu Builder) shell can
be used.
Page 29
When using the SelectRef attribute, make sure that the Protocol/Field is spelt
correctly in the corresponding protocol XML file.
You really only need the End Tags for the protocol and protocol set tags.
29
Writing Protocol Descriptions in XML –
Errors/Debugging – GPB Shell -1
• The GPB shell sits on top of the GPB library and allows you to verify a
XML files without going through the GUI.
GUI
• The GPB Shell allows you to load the XML files into the GPB library.
• It allows you to debug an XML file before loading it up in the GUI.
• The GPB Shell manages 1 PDU at a time.
Page 30
30
Writing Protocol Descriptions in XML –
Errors/Debugging – GPB Shell - 2
• Say you create a PDU in XML and want to verify that it is valid.
• Run the GPB shell
• Type help, help 1 or help 2 to see a list of possible commands.
• First load the protocol XML files into the GPB Library
% loadProtocols “/Program Files/Agilent/RouterTester/Protocols”
• Next List the Protocols available in the library
% listProtocols
arp atm_cell bgp4 bpdu CiscoHDLC dhcp ethernet ethernet_SAP
ethernet_SNAP framerelay_nlpid framerelay_snap framerelay_q933
framerelay_null gre icmp icmp_v6 igmp ipv4
ipv6 udp_v6 tcp_v6 IPX isl L2TPv2 L2TPv3 control_word PPP
mpls PPPoHDLC PPPoE raw_shim raw_layer2 rip tcp udp
Page 31
31
Writing Protocol Descriptions in XML –
Errors/Debugging – GPB Shell - 3
• Create a PDU
% createPdu ethernet IPv4
• Print the contents of the PDU
% printPdu
PDU has 26 elements. Length = 656
0 +ethernet length=656
1 +header length=112
2 destination_address length=48 value=00:00:00:00:00:00
3 source_address length=48 value=00:00:00:00:00:00
4 ether_type length=16 value=2048 (0x0800: IPv4)
5 payload data length=512 protocols: ipv4
6 +ipv4 length=512
…
• If there is an error in the XML file, it will show up through the printPdu
command.
Page 32
32
Writing Protocol Descriptions in XML –
Errors/Debugging – GPB Shell - 4
• You can also use the command traceAll to find out more details.
• A script called gpbSanityCheck.tcl is written which will also check the
syntax of the XML file. Run this script from the GPB Shell.
% _gpbsh.exe gpbSanityCheck.tcl
Generic PDU Builder. Copyright (C) 2002-2003 Agilent Technologies
Type "help" for list of commands
-> Loading protocols from /Program
Files/Agilent/RouterTester/protocols ...
--------------------------------------------------------------------------
Testing protocol arp ...
--------------------------------------------------------------------------
Testing protocol arp2 ...
-> load error
-> Unable to create default PDU arp2
Sanity Check FAILED. 1 error:
1. Unable to create default PDU arp2
Run test again with -verbose to see message log
child process exited abnormally Page 33
33
Writing Protocol Descriptions in XML – Steps to
Create New Protocol
1. Copy an existing (similar) protocol XML file from
C:\Program Files\Agilent\RouterTester\Protocols to
C:\Program Files\Agilent\RouterTester\UserProtocols
2. Replace the old the protocol/field names with the new names.
3. Delete the field names that are not useful from copied protocol.
4. Look at the Reference Guide to see which attributes to use.
5. Save XML file.
6. Load Protocols in GPB shell.
Check for and fix any errors in XML and save again.
Repeat Step 6 till no errors.
7. Load RT900 Application PDU Builder and check to see that the
protocol comes up OK.
Page 34
The above slide shows general steps needed to go and create anew protocol
description XML file.
First, copy an existing file from the Protocols to the User Protocols directory. Try
and copy a protocol that is similar in structure to the one that you want to create.
Make sure that the old protocol names are replaced as this can cause errors.
Also delete any fields from the copied protocol file that are not useful.
Look up the Reference Guide to see what attributes to use.
Save the XML file.
Start up the RT900 Application PDU Builder. Try and add the new protocol that you
have created. Check to see that the fields are correct. If you get errors, check the
file and look for spelling errors in the fields and also the End tags have the /.
34
Summary
• The Generic PDU Builder is a flexible and powerful software tool for
creating and decoding PDUs, or packets, for a wide and growing
range of protocols.
• XML is an easy and flexible language for expressing data.
• New protocols can be Built and Decoded on RT900 by creating the
appropriate Protocol Description XML file.
• Protocol descriptions should contain all the information needed to
build all the possible types of PDU for the protocol.
• There are only a handful of XML tags to learn to write your own
protocol descriptions.
• Tcl functions can be written to handle protocol specific functions.
Page 35
35
Questions
Page 36
36