rt900 training — writing xml files for the generic pdu...
Post on 06-Aug-2020
2 Views
Preview:
TRANSCRIPT
1
RT900 Training— Writing XML Files for the Generic PDU Builder
2
Page 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
Page 3
Presentation Contents
• Generic PDU Builder
• XML Basics
• Writing protocol descriptions in XML
• Summary
4
Page 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
Page 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
Page 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
Page 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
Page 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
Page 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
Page 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
Page 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
Page 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:
• <!-- This is a comment -->
• 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:
<!-- This is a comment -->
Comments can be put anywhere except inside a tag.
13
Page 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
Page 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
Page 15
Writing Protocol Descriptions in XML
• 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
Page 16
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>
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
Page 17
Writing Protocol Descriptions in XML
• 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
Page 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
Page 19
Writing Protocol Descriptions in XML – Example
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
Page 20
Writing Protocol Descriptions in XML – Example
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
Page 21
Writing Protocol Descriptions in XML – Example
Multiple Messages, Multiple Fields – BGP-4
The above screen shot shows the GUI equivalent of the XML file on the previous
slide.
22
Page 22
Writing Protocol Descriptions in XML – Example
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
Page 23
Writing Protocol Descriptions in XML – Example
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
Page 24
Writing Protocol Descriptions in XML – Example
– 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
Page 25
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"/>
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
Page 26
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
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
Page 27
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.
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
Page 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
Page 29
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.
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
Page 30
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.
• 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
Page 31
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% 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
Page 32
Writing Protocol Descriptions in XML –
Errors/Debugging – GPB Shell - 3
• 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
Page 33
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.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
Page 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
Page 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
Page 36
Questions
• Any more questions ?
• Thank you for your attention.
top related