diff options
Diffstat (limited to 'scripts/automation/trex_control_plane/doc')
17 files changed, 170 insertions, 130 deletions
diff --git a/scripts/automation/trex_control_plane/doc/about_trex.rst b/scripts/automation/trex_control_plane/doc/about_trex.rst deleted file mode 100755 index 97cad97d..00000000 --- a/scripts/automation/trex_control_plane/doc/about_trex.rst +++ /dev/null @@ -1,16 +0,0 @@ -=================== -About T-Rex project -=================== - -Full project's official site ----------------------------- - -To learn all about T-Rex project, visit Cisco's internal `official site <http://csi-wiki-01:8080/display/bpsim/Home>`_ - -Even more ---------- - -.. toctree:: - :maxdepth: 2 - - authors
\ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/api/index.rst b/scripts/automation/trex_control_plane/doc/api/index.rst index 8233a634..cfdc6917 100755 --- a/scripts/automation/trex_control_plane/doc/api/index.rst +++ b/scripts/automation/trex_control_plane/doc/api/index.rst @@ -1,9 +1,8 @@ API Reference ============= -The T-Rex API reference section is currently a work in progress. -**T-Rex Modules** +**TRex Modules** .. toctree:: :maxdepth: 4 @@ -11,7 +10,7 @@ The T-Rex API reference section is currently a work in progress. client_code exceptions -**T-Rex JSON Template** +**TRex JSON Template** .. toctree:: :maxdepth: 4 diff --git a/scripts/automation/trex_control_plane/doc/api/json_fields.rst b/scripts/automation/trex_control_plane/doc/api/json_fields.rst index b1a2af7c..9e32d23e 100755 --- a/scripts/automation/trex_control_plane/doc/api/json_fields.rst +++ b/scripts/automation/trex_control_plane/doc/api/json_fields.rst @@ -1,23 +1,23 @@ -T-Rex JSON Template
-===================
+TRex JSON Template
+==================
-Whenever T-Rex is publishing live data, it uses JSON notation to describe the data-object.
+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 T-Rex server.
+Each client may parse it differently, however this page will describe the values meaning when published by TRex server.
Main Fields
-----------
-Each T-Rex server-published JSON object contains data divided to main fields under which the actual data lays.
+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 T-Rex run, | |
+| :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. | |
@@ -117,7 +117,7 @@ trex-global field .. _tx-gen-field:
tx-gen field
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~
+-------------------+-------+-----------------------------------------------------------+
| Sub-key | Type | Meaning |
diff --git a/scripts/automation/trex_control_plane/doc/authors.rst b/scripts/automation/trex_control_plane/doc/authors.rst deleted file mode 100755 index 3b85f020..00000000 --- a/scripts/automation/trex_control_plane/doc/authors.rst +++ /dev/null @@ -1,12 +0,0 @@ -======= -Authors -======= - -T-Rex is developed in Cisco Systems Inc. as the next generation traffic generator. - -T-Rex core-team developers are: - - - Hanoch Haim - - Dave Johnson - - Wenxian Li - - Dan Klein
\ No newline at end of file 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/conf.py b/scripts/automation/trex_control_plane/doc/conf.py index fb9ea83c..46d0435d 100755 --- a/scripts/automation/trex_control_plane/doc/conf.py +++ b/scripts/automation/trex_control_plane/doc/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# T-Rex Control Plain documentation build configuration file, created by +# TRex Control Plain documentation build configuration file, created by # sphinx-quickstart on Tue Jun 2 07:48:10 2015. # # This file is execfile()d with the current directory set to its @@ -54,7 +54,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'T-Rex Control Plain' +project = u'TRex Control Plain' copyright = u'2015, Cisco Systems Inc.' author = u'Dan Klein for Cisco Systems Inc.' @@ -211,7 +211,7 @@ html_static_path = ['_static'] #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'T-RexControlPlaindoc' +htmlhelp_basename = 'TRexControlPlaindoc' # -- Options for LaTeX output --------------------------------------------- @@ -233,7 +233,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'T-RexControlPlain.tex', u'T-Rex Control Plain Documentation', + (master_doc, 'TRexControlPlain.tex', u'TRex Control Plain Documentation', u'Dan Klein for Cisco Systems Inc', 'manual'), ] @@ -263,7 +263,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 't-rexcontrolplain', u'T-Rex Control Plain Documentation', + (master_doc, 'TRexcontrolplain', u'TRex Control Plain Documentation', [author], 1) ] @@ -277,8 +277,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'T-RexControlPlain', u'T-Rex Control Plain Documentation', - author, 'T-RexControlPlain', 'One line description of project.', + (master_doc, 'TRexControlPlain', u'TRex Control Plain Documentation', + author, 'TRexControlPlain', 'One line description of project.', 'Miscellaneous'), ] diff --git a/scripts/automation/trex_control_plane/doc/index.rst b/scripts/automation/trex_control_plane/doc/index.rst index e7a619d8..62fd9975 100755 --- a/scripts/automation/trex_control_plane/doc/index.rst +++ b/scripts/automation/trex_control_plane/doc/index.rst @@ -1,32 +1,23 @@ -.. 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** -Getting Started -=============== -.. toctree:: - :maxdepth: 2 - - installation - client_utils - usage_examples - API Reference ============= .. toctree:: @@ -34,14 +25,19 @@ API Reference api/index -About T-Rex -=========== +Client Utilities +================ .. toctree:: :maxdepth: 2 - All about T-Rex <about_trex> - license + client_utils +Usage Examples +============== +.. toctree:: + :maxdepth: 2 + + usage_examples Indices and tables diff --git a/scripts/automation/trex_control_plane/doc/installation.rst b/scripts/automation/trex_control_plane/doc/installation.rst deleted file mode 100755 index dda32f56..00000000 --- a/scripts/automation/trex_control_plane/doc/installation.rst +++ /dev/null @@ -1,25 +0,0 @@ -============
-Installation
-============
-
-Prerequisites
--------------
-The T-Rex control plane is based on client-server model that interacts using JSON-RPC.
-
-In order to use the client-side API documented a T-Rex server daemon must be up and listening on the same host and port that the client tries to connect with.
-
-Compatibility
--------------
-Both client and server side were developed for Linux platform.
-The client-side module is also compatible with windows python.
-
-The client side can be used with both Python 2 and Python 3 versions.
-However, the server side was desined to and best fits with Python 2.7.6 and on (all 2.x series, assuming > 2.6.9).
-
-
-Installation manual
--------------------
-
-T-Rex Control Plane is a cross-platform, cross-operatin system APi to control and run T-Rex.
-
-The full, most updated manual (which refers to all programming languages) can be found under the `Automation API documentation <http://csi-wiki-01:8080/display/bpsim/Documentation>`_ .
\ No newline at end of file diff --git a/scripts/automation/trex_control_plane/doc/json_dictionary.yaml b/scripts/automation/trex_control_plane/doc/json_dictionary.yaml index 853ded65..89535b56 100755 --- a/scripts/automation/trex_control_plane/doc/json_dictionary.yaml +++ b/scripts/automation/trex_control_plane/doc/json_dictionary.yaml @@ -1,6 +1,6 @@ -################################################################ -#### T-Rex JSON Dictionary definitions #### -################################################################ +############################################################### +#### TRex JSON Dictionary definitions #### +############################################################### trex-global : diff --git a/scripts/automation/trex_control_plane/doc/license.rst b/scripts/automation/trex_control_plane/doc/license.rst deleted file mode 100755 index b83dd4b3..00000000 --- a/scripts/automation/trex_control_plane/doc/license.rst +++ /dev/null @@ -1,18 +0,0 @@ -======= -License -======= - - -Copyright 2015 Cisco Systems Inc. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. 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..bff1ef7f --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/examples.rst @@ -0,0 +1,5 @@ +
+Packet Builder Usage Examples
+=============================
+
+Here I'll add usage examples, very similar to those I added to RPC document
\ 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..9f8c8f7b --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/export_format.yaml @@ -0,0 +1,47 @@ +#################################################### +#### TRex packet export format #### +#################################################### + +# 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 new file mode 100755 index 00000000..ed1d460d --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/index.rst @@ -0,0 +1,18 @@ + +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 + :titlesonly: + + 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..eb639f7c --- /dev/null +++ b/scripts/automation/trex_control_plane/doc/packet_generator/stream_export.rst @@ -0,0 +1,29 @@ +
+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. The YAML file can either contain Byte representation of the packet of refer to a .pcap file that contains it.
+2. The YAML file is similar as much as possible to the `add_stream method <http://trex-tgn.cisco.com/trex/doc/trex_rpc_server_spec.html#_add_stream>`_ of TRex RPC server spec, which defines the raw interaction with TRex server.
+3. Only packet binary data and VM instructions 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
+-------
+
+The following files snapshot represents each of the options (Binary/pcap) for the very same HTTP GET request packet.
diff --git a/scripts/automation/trex_control_plane/doc/requirements.rst b/scripts/automation/trex_control_plane/doc/requirements.rst deleted file mode 100755 index e69de29b..00000000 --- a/scripts/automation/trex_control_plane/doc/requirements.rst +++ /dev/null diff --git a/scripts/automation/trex_control_plane/doc/usage_examples.rst b/scripts/automation/trex_control_plane/doc/usage_examples.rst index 7116f28c..ff5c026d 100755 --- a/scripts/automation/trex_control_plane/doc/usage_examples.rst +++ b/scripts/automation/trex_control_plane/doc/usage_examples.rst @@ -6,7 +6,7 @@ Usage Examples Full-featured interactive shell
-------------------------------
-The `client_interactive_example.py` extends and uses the `Cmd <https://docs.python.org/2/library/cmd.html>`_ built in python class to create a Full-featured shell using which one can interact with T-Rex server and get instant results.
+The `client_interactive_example.py` extends and uses the `Cmd <https://docs.python.org/2/library/cmd.html>`_ built in python class to create a Full-featured shell using which one can interact with TRex server and get instant results.
The help menu of this application is:
@@ -14,21 +14,21 @@ The help menu of this application is: usage: client_interactive_example [options]
- Run T-Rex client API demos and scenarios.
+ Run TRex client API demos and scenarios.
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-t HOST, --trex-host HOST
- Specify the hostname or ip to connect with T-Rex
+ Specify the hostname or ip to connect with TRex
server.
-p PORT, --trex-port PORT
- Select port on which the T-Rex server listens. Default
+ Select port on which the TRex server listens. Default
port is 8090.
-m SIZE, --maxhist SIZE
Specify maximum history size saved at client side.
Default size is 100.
- --verbose Switch ON verbose option at T-Rex client. Default is:
+ --verbose Switch ON verbose option at TRex client. Default is:
OFF.
**Code Excerpt**
@@ -51,8 +51,8 @@ The demo takes the user a full circle: 2. exporting the generated packets into .pcap file named `dns_traffic.pcap`.
3. Use the :class:`trex_yaml_gen.CTRexYaml` generator to include that pcap file in the yaml object.
4. Export the YAML object onto a YAML file named `dns_traffic.yaml`
- 5. Push the generated files to T-Rex server.
- 6. Run T-Rex based on the generated (and pushed) files.
+ 5. Push the generated files to TRex server.
+ 6. Run TRex based on the generated (and pushed) files.
**Code Excerpt** [#f1]_
|