rt900 training — writing xml files for the generic pdu...

1

RT900 Training— Writing XML Files for the Generic PDU Builder

2

Objective

• To purpose of this training is to:

• Learn and understand the new Generic PDU Builder.

• Learn the XML basics.

• Learn how to create new protocols using XML.

3

Presentation Contents

• Generic PDU Builder

• XML Basics

• Writing protocol descriptions in XML

• Summary

4

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.

5

Generic PDU Builder

• The new Generic PDU builder offers the following advantages:

• Payload fill and field value generation features for packet

blasting applications.

• The ability to stretch a PDU to any specified length, and have all

affected protocol fields automatically adjusted.

• The Generic PDU Builder empowers anyone, including users of

the tool, to add support for new protocols without writing any

code.

• This is because the Generic PDU Builder sources all protocol

knowledge from external XML text files, which anyone can

write.

6

Generic PDU Builder

1

2

3

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.

1. Button to create a New Packet.

2. Button to add a Protocol Layer.

3. Button to delete a Protocol Layer.

7

XML Basics - Files

• XML is the Extensible Markup Language

• It is primarily designed to improve the functionality of the Web by

providing more flexible and adaptable information identification.

• It is called extensible because it is not a fixed format like HTML.

• XML is created to structure, store, and to send information.

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.

8

XML Basics – Files on RT900

• XML files can be created on the RT900 application to Build/Decode

specific protocols.

• There are existing RT900 PDU XML files:

• Stored in the directory –

C:\Program Files\Agilent\RouterTester\Protocols

• Some examples are: IP/TCP/UDP/BGP/RIP/L2oMPLS/L2TP…

• RT900 PDU XML files are named: AgtPdu_PROTOCOL.xml

Eg. AgtPdu_BGP4.xml, AgtPdu_ATM.xml

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

9

XML Basics - Tags

• In XML files, text data is organized into a hierarchical structure using application defined tags.

• Data is enclosed within a pair of tags - known as a start tag and end tag.

• The tags each have a name, and are identified by angled brackets, for example:

• <protocol> .. some protocol data ... </protocol>

• A tag can enclose other tags, for example:

• <protocol><field></field>

</protocol>

• In fact, an XML document must always comprise one (and only one) root tag which encloses all others.

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.

10

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>

• Attribute values, even numeric values, are always enclosed in quotes.

• The Generic PDU Builder understands numeric values expressed as

integers, or as hexadecimal, eg: "0x45ab3f". Values for fields longer

than 32 bits must be expressed in hexadecimal.

• Each attribute must be separated by at least one space.

• Where applicable, the name attribute must be the first attribute and

appear on the same line as the tag

Start Tag End TagAttribute AttributeValue Value

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.

11

XML Basics – Tags - Attributes

• XML provides two ways to represent data - as attributes, or enclosed by a set of tags.

• In the case of protocol descriptions, all data is represented as attributes. Tags may only contain other tags. Because of this, we often have "empty" tags, eg:

• <protocol name="tcp" fullName="Transmission Control Protocol"><field name="source_port" length="16"></field><field name="dest_port" length="16"></field>

</protocol>

• The <field> tag is empty because there is no data or tags between the start tag and the end tag. For empty tags, we can use a slash '/>' notation to avoid spelling out the end tag, eg:

• <protocol name="tcp" fullName="Transmission Control Protocol"><field name="source_port" length="16"/><field name="dest_port" length="16"/>

</protocol>

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”/>

12

XML Basics – Header and Comments

• Each XML document must have this quirky header:

• <?xml version="1.0" standalone="yes"?>

• Note that this is not like other XML tags - there is no end tag for

it.

• You can optionally include comments in your XML document, using

the syntax:

• 

• Note that you cannot insert a comment inside a tag, ie between

the < > brackets

The start of all XML files must have the header:

<?xml version="1.0" standalone="yes"?>

Comments can be put into XML files:



Comments can be put anywhere except inside a tag.

13

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 theirsite.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.

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.

14

Writing Protocol Descriptions in XML

• A protocol description describes each field in the protocol's

messages, how they interrelate and are to be displayed. Protocol

Descriptions are written in XML.

• Protocol description files may contain three different types of

information:

• Protocols - which describe all the available fields and how they

interrelate.

• Enum Sets - (name, value) pairs used to assist the user select

meaningful values – Drop down lists.

• Packet Types - pre-defined packets comprising one or more

protocol layers.

Protocols – describe all the messages and fields of a particular protocol.

Enum sets – are used to pair up a value to a name.

Eg. In L2TP,if the Control Message Type has a value of 1, it means SCCRQ

Start-Control-Connection-Request. If Enum types are created for Control Message

Types, the PDU builder will allow the user to select SCCRQ instead of having to

look up the standard and find the value for SCCRQ.

Enum Sets may be defined globally - and available for use by several protocols, or

may be defined within a protocol definition, and accessible only by that protocol.

Packet Types: allow pre-defined packets comprising of one or more protocol layers.

For example an XML file can contain protocol definitions for IPv4, TCP, and BGP.

The packet type can be BGP over TCP over IPv4.

15


• Protocol descriptions should contain all the information needed to

build all the possible types of PDU for the protocol.

• A correctly written protocol description will contain sufficient

information (such as default values and default field selections) to

enable the PDU builder to automatically build a useful default PDU

which fully conforms to the protocol.

• Typically a separate file will be used for each protocol, although this

is not necessary.

• User-defined protocols should be stored in:

C:\Program Files\Agilent\RouterTester\UserProtocols

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.

16


• 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> 

<enum/>

</enumSet>

<protocol>

<enumSet> 

<enum/>

</enumSet><field>

<enum/> 

</field>

<payload/>

</protocol>

<packetType><layer>

<preset/>

</layer>

</packetType>

</ProtocolSet>

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.

17


• The Reference Guide will assist you in filling in the attributes for the

different tags.

There is a XML reference guide which will help to fill in the attributes for the

different tags.

18

Writing Protocol Descriptions in XML – Example

1 Message Multiple Fields – Layer 2 over MPLS

<protocol name="control_word“

fullName="Control Word“

standard="draft-martini-l2circuit-encap-mpls-04.txt“

sequence="reserved flags zero length sequence_number">

<field name="reserved“ fullName="Reserved“ length="4“ value="0“ format="hex"/>

<field name="flags“ fullName="Flags“ select="aal5_flags atm_cell flags ethernet_flags

frame_relay_flags hdlc_flags“ default="ethernet_flags“ />

<field name="ethernet_flags" fullName="Ethernet Flags" length="4" format="binary" value="0"/>

<field name="zero“ fullName="Zero“ length="2“ value="0“ format="binary"/>

<field name="length“ fullName="length“ length="6“ format="integer"/><field name="sequence_number“ fullName="Sequence Number“ length="16“ format="integer"/>

</protocol>

Reserved

4 bits

Flags

4 Bits

Zero

2 Bits

Length

6 Bits

Sequence

Number

16 Bits

Note: There are also Field

tags for Flags: AAL5, ATM,

Frame Relay, HDLC which

are not shown on this slide

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.

19


1 Message Multiple Fields – Layer 2 over MPLS

The above screen shot shows the GUI equivalent of the XML file on the previous

slide.

20


Multiple Messages, Multiple Fields – BGP-4

<protocol name="bgp4“

fullName="Border Gateway Protocol Version 4“

instance="primary“ standard="RFC 1771“selectRef="tcp:dest_port“ selectValue="179“

select="open update notification keepalive" default="open“ >

<field name="open“ fullName="OPEN message" lengthRef="length" lengthMultiplier="8“

sequence="marker length open_type version my_as hold_time bgp_id MORE-FIELDS-NOT-SHOWN/>

<field name="update“ fullName="UPDATE message" lengthRef="length" lengthMultiplier="8“sequence="marker length update_type unfeasible_routes_length MORE-FIELDS-NOT-SHOWN/>

<field name="marker" fullName="Marker" length="128" defaultValue="0xFFFF..“ format="hex"/>

<field name="length" fullName="Length" length="16" format="integer"/>

Marker

128 bits

Length

16 Bits

Open_Type

8 Bits

MORE

FIELDS

NOT

SHOWN

Note: This is only part of the

protocol description file.

There are too many

messages/fields for 1 slide.

Marker

128 bits

Length

16 Bits

Update_Type

8 Bits

MORE

FIELDS

NOT

SHOWN

OPEN MESSAGE UPDATE MESSAGE

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.

21


Multiple Messages, Multiple Fields – BGP-4

The above screen shot shows the GUI equivalent of the XML file on the previous

slide.

22


Optional Fields – BGP-4

<field name="open" fullName="OPEN message" lengthRef="length" lengthMultiplier="8“

sequence="marker length open_type … optional_param_length optional_params"/>

…

<field name="optional_param_length" fullName="Optional parameter length" description="Total

length in octets of option parameters field" length="8" format="integer"/>

<field name="optional_params" fullName="Optional parameters" lengthRef="optional_param_length“

lengthMultiplier="8" instance="optional" multiSelect="auth_param"/>

<field name="auth_param" fullName="Authentication parameter" sequence="auth_type

auth_length auth_value"/>

<field name="auth_type" fullName="parameter type" length="8" format="integer" value="1"/>

Marker

128 bits

Length

16 Bits

Open_Type

8 Bits

MORE

FIELDS

NOT

SHOWN

OPEN MESSAGE

Optional

Parameters

Length

8 Bits

Optional

Parameters:

Authentication

Parameters:

Auth. Type

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.

23


Optional Fields – BGP-4

The above screen shot shows the GUI equivalent of the XML file for the BGP

Optional Fields on the previous slide.

24


– Enum Types – ARP – Hardware Types

<field name="arp_v4" fullName="ARP for IPv4" sequence="hw_type

protocol_v4 …."/>

<enumSet name="hardware_types" fullName="ARP Hardware Types"

standard="http://www.iana.org/assignments/arp-parameters">

<enum value="1" name="Ethernet (10Mb)"/>

<enum value="6" name="IEEE 802 Networks"/>

<enum value="15" name="Frame Relay"/>…

</enumSet>

<field name="hw_type" fullName="Hardware Type" length="16"

defaultValue="6" enumRef="hardware_types“ />

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.

25


– 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"/>

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.

26


– 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

In the above example, the value of field "header_checksum" is computed using a

value function called "checksum". The input data to the "checksum" is the value of

field "header".

Checksum - Compute a checksum suitable for IP, UDP, TCP protocols.

8, 16 and 32 bit checksum algorithms are provided: the correct algorithm is selected

to match the length of the target field

Crc - Compute a Cyclic Reduncandcy Check (CRC).

3, 5, 7, 8, 10, 16 and 32 bit CRC algorithms are provided: the correct algorithm is

selected to match the length of the target field

27


– 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.

You can create your own functions using Tcl.

Make sure that the Tcl source file is in the same directory as the protocol description

XML file.

28

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.

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.

29


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.

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.

30


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.

• 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.

XML

FileGPB

Library

GPB Shell

GPB

Library

API

GUI

31


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% listProtocolsarp atm_cell bgp4 bpdu CiscoHDLC dhcp ethernet ethernet_SAPethernet_SNAP framerelay_nlpid framerelay_snap framerelay_q933framerelay_null gre icmp icmp_v6 igmp ipv4ipv6 udp_v6 tcp_v6 IPX isl L2TPv2 L2TPv3 control_word PPPmpls PPPoHDLC PPPoE raw_shim raw_layer2 rip tcp udp

32



• Create a PDU

% createPdu ethernet IPv4

• Print the contents of the PDU% printPduPDU has 26 elements. Length = 6560 +ethernet length=6561 +header length=1122 destination_address length=48 value=00:00:00:00:00:003 source_address length=48 value=00:00:00:00:00:004 ether_type length=16 value=2048 (0x0800: IPv4)5 payload data length=512 protocols: ipv46 +ipv4 length=512…

• If there is an error in the XML file, it will show up through the printPdu command.

33



• 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.tclGeneric PDU Builder. Copyright (C) 2002-2003 Agilent TechnologiesType "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 arp2Sanity Check FAILED. 1 error:1. Unable to create default PDU arp2Run test again with -verbose to see message logchild process exited abnormally

34

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 toC:\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.

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 /.

35

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.

36

Questions

• Any more questions ?

• Thank you for your attention.

rt900 training — writing xml files for the generic pdu...

Documents