From 16e3b19016a0d6e63d9162040811de4386142af0 Mon Sep 17 00:00:00 2001 From: Dan Klein Date: Sun, 4 Oct 2015 17:22:46 +0300 Subject: Updated and added documentation files for packet builder module --- .../doc/packet_generator/examples.rst | 233 +++++++++++++++++++++ .../doc/packet_generator/export_format.yaml | 27 +++ .../doc/packet_generator/index.rst | 17 ++ .../doc/packet_generator/packet_builder_code.rst | 12 ++ .../doc/packet_generator/stream_export.rst | 27 +++ 5 files changed, 316 insertions(+) create mode 100755 scripts/automation/trex_control_plane/doc/packet_generator/examples.rst create mode 100755 scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml create mode 100755 scripts/automation/trex_control_plane/doc/packet_generator/index.rst create mode 100755 scripts/automation/trex_control_plane/doc/packet_generator/packet_builder_code.rst create mode 100755 scripts/automation/trex_control_plane/doc/packet_generator/stream_export.rst (limited to 'scripts/automation/trex_control_plane/doc/packet_generator') diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/examples.rst b/scripts/automation/trex_control_plane/doc/packet_generator/examples.rst new file mode 100755 index 00000000..f903feac --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/examples.rst @@ -0,0 +1,233 @@ + +Packet Builder Usage Examples +============================= + +Whenever TRex is publishing live data, it uses JSON notation to describe the data-object. + +Each client may parse it diffrently, however this page will describe the values meaning when published by TRex server. + + +Main Fields +----------- + +Each TRex server-published JSON object contains data divided to main fields under which the actual data lays. + +These main fields are: + ++-----------------------------+----------------------------------------------------+---------------------------+ +| Main field | Contains | Comments | ++=============================+====================================================+===========================+ +| :ref:`trex-global-field` | Must-have data on TRex run, | | +| | mainly regarding Tx/Rx and packet drops | | ++-----------------------------+----------------------------------------------------+---------------------------+ +| :ref:`tx-gen-field` | Data indicate the quality of the transmit process. | | +| | In case histogram is zero it means that all packets| | +| | were injected in the right time. | | ++-----------------------------+----------------------------------------------------+---------------------------+ +| :ref:`trex-latecny-field` | Latency reports, containing latency data on | - Generated when latency | +| | generated data and on response traffic | test is enabled (``l`` | +| | | param) | +| | | - *typo* on field key: | ++-----------------------------+----------------------------------------------------+ will be fixed on next | +| :ref:`trex-latecny-v2-field`| Extended latency information | release | ++-----------------------------+----------------------------------------------------+---------------------------+ + + +Each of these fields contains keys for field general data (such as its name) and its actual data, which is always stored under the **"data"** key. + +For example, in order to access some trex-global data, the access path would look like:: + + AllData -> trex-global -> data -> desired_info + + + + +Detailed explanation +-------------------- + +.. _trex-global-field: + +trex-global field +~~~~~~~~~~~~~~~~~ + + ++--------------------------------+-------+-----------------------------------------------------------+ +| Sub-key | Type | Meaning | ++================================+=======+===========================================================+ +| m_cpu_util | float | CPU utilization (0-100) | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_platform_factor | float | multiplier factor | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_bps | float | total tx bit per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_rx_bps | float | total rx bit per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_pps | float | total tx packet per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_cps | float | total tx connection per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_expected_cps | float | expected tx connection per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_expected_pps | float | expected tx packet per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_tx_expected_bps | float | expected tx bit per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_rx_drop_bps | float | drop rate in bit per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_active_flows | float | active trex flows | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_open_flows | float | open trex flows from startup (monotonically incrementing) | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_tx_pkts | int | total tx in packets | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_rx_pkts | int | total rx in packets | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_tx_bytes | int | total tx in bytes | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_rx_bytes | int | total rx in bytes | ++--------------------------------+-------+-----------------------------------------------------------+ +| opackets-# | int | output packets (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| obytes-# | int | output bytes (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| ipackets-# | int | input packet (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| ibytes-# | int | input bytes (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| ierrors-# | int | input errors (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| oerrors-# | int | input errors (per interface) | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_tx_bps-# | float | total transmitted data in bit per second | ++--------------------------------+-------+-----------------------------------------------------------+ +| unknown | int | | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_nat_learn_error [#f1]_ | int | | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_nat_active [#f2]_ | int | | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_nat_no_fid [#f2]_ | int | | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_nat_time_out [#f2]_ | int | | ++--------------------------------+-------+-----------------------------------------------------------+ +| m_total_nat_open [#f2]_ | int | | ++--------------------------------+-------+-----------------------------------------------------------+ + + +.. _tx-gen-field: + +tx-gen field +~~~~~~~~~~~~~~ + ++-------------------+-------+-----------------------------------------------------------+ +| Sub-key | Type | Meaning | ++===================+=======+===========================================================+ +| realtime-hist | dict | histogram of transmission. See extended information about | +| | | histogram object under :ref:`histogram-object-fields`. | +| | | The attribute analyzed is time packet has been sent | +| | | before/after it was intended to be | ++-------------------+-------+-----------------------------------------------------------+ +| unknown | int | | ++-------------------+-------+-----------------------------------------------------------+ + +.. _trex-latecny-field: + +trex-latecny field +~~~~~~~~~~~~~~~~~~ + ++---------+-------+---------------------------------------------------------+ +| Sub-key | Type | Meaning | ++=========+=======+=========================================================+ +| avg-# | float | average latency in usec (per interface) | ++---------+-------+---------------------------------------------------------+ +| max-# | float | max latency in usec from the test start (per interface) | ++---------+-------+---------------------------------------------------------+ +| c-max-# | float | max in the last 1 sec window (per interface) | ++---------+-------+---------------------------------------------------------+ +| error-# | float | errors in latency packets (per interface) | ++---------+-------+---------------------------------------------------------+ +| unknown | int | | ++---------+-------+---------------------------------------------------------+ + +.. _trex-latecny-v2-field: + +trex-latecny-v2 field +~~~~~~~~~~~~~~~~~~~~~ + ++--------------------------------------+-------+--------------------------------------+ +| Sub-key | Type | Meaning | ++======================================+=======+======================================+ +| cpu_util | float | rx thread cpu % (this is not trex DP | +| | | threads cpu%%) | ++--------------------------------------+-------+--------------------------------------+ +| port-# | | Containing per interface | +| | dict | information. See extended | +| | | information under ``port-# -> | +| | | key_name -> sub_key`` | ++--------------------------------------+-------+--------------------------------------+ +| port-#->hist | dict | histogram of latency. See extended | +| | | information about histogram object | +| | | under :ref:`histogram-object-fields`.| ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats | | Containing per interface | +| | dict | information. See extended | +| | | information under ``port-# -> | +| | | key_name -> sub_key`` | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_tx_pkt_ok | int | total of try sent packets | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_pkt_ok | int | total of packets sent from hardware | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_no_magic | int | rx error with no magic | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_no_id | int | rx errors with no id | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_seq_error | int | error in seq number | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_length_error | int | | ++--------------------------------------+-------+--------------------------------------+ +| port-#->stats->m_rx_check | int | packets tested in rx | ++--------------------------------------+-------+--------------------------------------+ +| unknown | int | | ++--------------------------------------+-------+--------------------------------------+ + + + +.. _histogram-object-fields: + +Histogram object fields +~~~~~~~~~~~~~~~~~~~~~~~ + +The histogram object is being used in number of place throughout the JSON object. +The following section describes its fields in detail. + + ++-----------+-------+-----------------------------------------------------------------------------------+ +| Sub-key | Type | Meaning | ++===========+=======+===================================================================================+ +| min_usec | int | min attribute value in usec. pkt with latency less than this value is not counted | ++-----------+-------+-----------------------------------------------------------------------------------+ +| max_usec | int | max attribute value in usec | ++-----------+-------+-----------------------------------------------------------------------------------+ +| high_cnt | int | how many packets on which its attribute > min_usec | ++-----------+-------+-----------------------------------------------------------------------------------+ +| cnt | int | total packets from test startup | ++-----------+-------+-----------------------------------------------------------------------------------+ +| s_avg | float | average value from test startup | ++-----------+-------+-----------------------------------------------------------------------------------+ +| histogram | | histogram of relevant object by the following keys: | +| | array | - key: value in usec | +| | | - val: number of packets | ++-----------+-------+-----------------------------------------------------------------------------------+ + + +Access Examples +--------------- + + + +.. rubric:: Footnotes + +.. [#f1] Available only in NAT and NAT learning operation (``learn`` and ``learn-verify`` flags) + +.. [#f2] Available only in NAT operation (``learn`` flag) \ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml b/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml new file mode 100755 index 00000000..86ae4bc1 --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml @@ -0,0 +1,27 @@ +router: + model : 1RU + hostname : ASR1001_T-Rex + ip_address : 10.56.199.247 + image : asr1001-universalk9.BLD_V155_2_S_XE315_THROTTLE_LATEST_20150121_110036-std.bin + line_password : lab + en_password : lab + mgmt_interface : GigabitEthernet0/0/0 + clean_config : /Configurations/danklei/asr1001_TRex_clean_config.cfg + intf_masking : 255.255.255.0 + ipv6_mask : 64 + interfaces : + - client : + name : GigabitEthernet0/0/1 + src_mac_addr : 0000.0001.0000 + dest_mac_addr : 0000.0001.0000 + server : + name : GigabitEthernet0/0/2 + src_mac_addr : 0000.0001.0000 + dest_mac_addr : 0000.0001.0000 + vrf_name : null + +tftp: + hostname : ats-asr-srv-1 + ip_address : 10.56.128.23 + root_dir : /auto/avc-devtest/ + images_path : /images/1RU/ \ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/index.rst b/scripts/automation/trex_control_plane/doc/packet_generator/index.rst new file mode 100755 index 00000000..f3cf46ff --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/index.rst @@ -0,0 +1,17 @@ + +TRex Packet Builder +------------------- +The TRex Packet Generator is a module designed to generate single-packet and set its ranging options, later to be transmitted using TRex. + +The packet generator module does extensive usage with `dkpt `_ python module to create packet headers. + +.. toctree:: + :maxdepth: 4 + + packet_builder_code + +.. toctree:: + :maxdepth: 0 + + examples + stream_export \ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/packet_builder_code.rst b/scripts/automation/trex_control_plane/doc/packet_generator/packet_builder_code.rst new file mode 100755 index 00000000..3a6e8d5f --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/packet_builder_code.rst @@ -0,0 +1,12 @@ + +CTRexPktBuilder class +--------------------- + +.. autoclass:: packet_builder.CTRexPktBuilder + :members: + :member-order: bysource + +Packet Builder Exceptions +------------------------- + +For exceptions documentation see here: :exc:`Packet Builder Exceptions ` \ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/stream_export.rst b/scripts/automation/trex_control_plane/doc/packet_generator/stream_export.rst new file mode 100755 index 00000000..8d5ad5be --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/stream_export.rst @@ -0,0 +1,27 @@ + +Stream Export YAML syntax +========================= + +In order to provide a fluent work-flow that utilize the best TRex user's time, an export-import mini language has been created. + +This enables a work-flow that supports saving and sharing a built packets and its scenarios, so that other tools +(such as TRex Console) could use them. + +The TRex Packet Builder module supports (using ___ method) the export of built stream according to the format described below. + +Guidelines +---------- + +1. One +2. Two +3. Three + +Export Format +------------- + +.. literalinclude:: export_format.yaml + +Example +------- + +Whenever TRex is publishing live data, it uses JSON notation to describe the data-object. -- cgit From c7ba20f4f7c4521fdf50238c7e4ccc50f13b248e Mon Sep 17 00:00:00 2001 From: Dan Klein Date: Sun, 4 Oct 2015 18:39:11 +0300 Subject: Updated packet export doc --- .../doc/packet_generator/export_format.yaml | 72 ++++++++++++++-------- .../doc/packet_generator/index.rst | 1 + .../doc/packet_generator/stream_export.rst | 10 +-- 3 files changed, 53 insertions(+), 30 deletions(-) (limited to 'scripts/automation/trex_control_plane/doc/packet_generator') diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml b/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml index 86ae4bc1..9f8c8f7b 100755 --- a/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml +++ b/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml @@ -1,27 +1,47 @@ -router: - model : 1RU - hostname : ASR1001_T-Rex - ip_address : 10.56.199.247 - image : asr1001-universalk9.BLD_V155_2_S_XE315_THROTTLE_LATEST_20150121_110036-std.bin - line_password : lab - en_password : lab - mgmt_interface : GigabitEthernet0/0/0 - clean_config : /Configurations/danklei/asr1001_TRex_clean_config.cfg - intf_masking : 255.255.255.0 - ipv6_mask : 64 - interfaces : - - client : - name : GigabitEthernet0/0/1 - src_mac_addr : 0000.0001.0000 - dest_mac_addr : 0000.0001.0000 - server : - name : GigabitEthernet0/0/2 - src_mac_addr : 0000.0001.0000 - dest_mac_addr : 0000.0001.0000 - vrf_name : null +#################################################### +#### TRex packet export format #### +#################################################### -tftp: - hostname : ats-asr-srv-1 - ip_address : 10.56.128.23 - root_dir : /auto/avc-devtest/ - images_path : /images/1RU/ \ No newline at end of file +# PACKET REP - OPTION #1 +packet: + is_pcap : YES/NO # <1> + binary : [] # <2> + pcap : path/to/pcap/file.pcap # <3> + meta : any metadata wished to # <4> + +# PACKET REP - OPTION #2 +packet: + data : [] / path/to/pcap/file.pcap # <5> + meta : any metadata wished to # <4> + +vm: # <6> + - vm instruction #1 + - vm instruction #2 + ... + - vm instruction #N + + +################################### +#### Comments #### +################################### +# +# <1>: is_pcap is a boolean field that indicates if packet is transferred by pcap referencs +# ('YES') or binary representation ('NO'). +# +# <2>: binary field encodes the packet in binary representation. in a sequence (array) data. +# Each array item is an integer ranging 0-255. +# **LEAVE BLANK IF USING PCAP REFERENCE** +# +# <3>: path to the linked pcap file. Make sure to provide path with reading credentials. +# **LEAVE BLANK IF USING BINARY REP FOR THE PACKET** +# +# <4>: meta data is any JSON formatted data ment to be passed on. +# +# <5>: data field can be both binary representation or pcap file refernce, +# without the need for user's explicit typing. +# The application logic differs between the cases by the object type +# (array/string ending in '.pcap') +# Less configuration, little more confusing, LESS similar to RPC spec +# +# <6>: vm instructions passed in array representation (sequence). +# Each instruction is deifned according to the structures of the supported VM instructions. \ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/packet_generator/index.rst b/scripts/automation/trex_control_plane/doc/packet_generator/index.rst index f3cf46ff..ed1d460d 100755 --- a/scripts/automation/trex_control_plane/doc/packet_generator/index.rst +++ b/scripts/automation/trex_control_plane/doc/packet_generator/index.rst @@ -12,6 +12,7 @@ The packet generator module does extensive usage with `dkpt `_ of TRex RPC server spec, which defines the raw interaction with TRex server. +3. Only packet binary data and VM instructinos are to be saved. Any meta-data packet builder module used while creating the packet will be stripped out. Export Format ------------- .. literalinclude:: export_format.yaml + :lines: 4- + :linenos: Example ------- -Whenever TRex is publishing live data, it uses JSON notation to describe the data-object. +The following files snapshot represents each of the options. -- cgit