diff options
| author |   Dan Klein <danklei@cisco.com> | 2015-10-04 17:22:46 +0300 |
|---|---|---|
| committer | Dan Klein <danklei@cisco.com> | 2015-10-04 17:22:46 +0300 |
| commit | 16e3b19016a0d6e63d9162040811de4386142af0 (patch) | |
| tree | a6cfd43d40b9368a4c96cf07550b566201d2c5a6 /scripts/automation/trex_control_plane/doc | |
| parent | 7e1bf3602241fb881531965813c0b6ad09790bee (diff) | |
Updated and added documentation files for packet builder module
Diffstat (limited to 'scripts/automation/trex_control_plane/doc')
7 files changed, 356 insertions, 23 deletions
diff --git a/scripts/automation/trex_control_plane/doc/client_utils.rst b/scripts/automation/trex_control_plane/doc/client_utils.rst index 224dfe19..32728a57 100755 --- a/scripts/automation/trex_control_plane/doc/client_utils.rst +++ b/scripts/automation/trex_control_plane/doc/client_utils.rst @@ -1,14 +1,19 @@ -
-Client Utilities
-================
-
-T-Rex YAML generator
---------------------
-
-.. automodule:: trex_yaml_gen
- :members:
-
-General Utilities
------------------
-.. automodule:: general_utils
+ +Client Utilities +================ + +.. toctree:: + :maxdepth: 2 + + packet_generator/index + +TRex YAML generator +------------------- + +.. automodule:: trex_yaml_gen + :members: + +General Utilities +----------------- +.. automodule:: general_utils :members:
\ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/index.rst b/scripts/automation/trex_control_plane/doc/index.rst index e7a619d8..ebcd5dcf 100755 --- a/scripts/automation/trex_control_plane/doc/index.rst +++ b/scripts/automation/trex_control_plane/doc/index.rst @@ -1,18 +1,18 @@ -.. T-Rex Control Plain documentation master file, created by +.. TRex Control Plain documentation master file, created by sphinx-quickstart on Tue Jun 2 07:48:10 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to T-Rex Control Plain's documentation! -=============================================== +Welcome to TRex Control Plain's documentation! +============================================== -T-Rex is a **realistic traffic generator** that enables you to do get learn more about your under developement devices. +TRex is a **realistic traffic generator** that enables you to do get learn more about your under development devices. -This site covers the Python API of T-Rex control plane, and explains how to utilize it to your needs. +This site covers the Python API of TRex control plane, and explains how to utilize it to your needs. However, since the entire API is JSON-RPC [#f1]_ based, you may want to check out other implementations that could suit you. -To understand the entirely how the API works and how to set up the server side, check out the `API documentation <http://csi-wiki-01:8080/display/bpsim/Documentation>`_ undee the documentation section of T-Rex website. +To understand the entirely how the API works and how to set up the server side, check out the `trex-core Wiki <https://github.com/cisco-system-traffic-generator/trex-core/wiki>`_ under the documentation section of TRex website. **Use the table of contents below or the menu to your left to navigate through the site** @@ -24,8 +24,6 @@ Getting Started :maxdepth: 2 installation - client_utils - usage_examples API Reference ============= @@ -34,8 +32,22 @@ API Reference api/index -About T-Rex -=========== +Client Utilities +================ +.. toctree:: + :maxdepth: 2 + + client_utils + +Usage Examples +============== +.. toctree:: + :maxdepth: 2 + + usage_examples + +About TRex +========== .. toctree:: :maxdepth: 2 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 <https://github.com/kbandla/dpkt>`_ 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 <packet_builder.CTRexPktBuilder.CPacketBuildException>`
\ 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.
|