diff options
Diffstat (limited to 'scripts/automation/trex_control_plane/doc_stl')
5 files changed, 501 insertions, 9 deletions
diff --git a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst index ef7feb61..bc9d521a 100644 --- a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst +++ b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst @@ -1,17 +1,194 @@ -Module documentation -================================ +TRex Client Module +================== + +TRex Client is an object to access TRex server. It is per user. Each user can own number of interfaces. +Multi user can interact with one TRex server each user should own a different set of interfaces. +The protocol is JSON-RPC2 over ZMQ transport. + +The API has two type of API + +1. Normal API +2. xx_line: this api get a line like the Console and parse it and call the low level api + +Example1:: + + c = STLClient() + + try: + # connect to server + c.connect() + + # prepare our ports (my machine has 0 <--> 1 with static route) + c.reset(ports = [0, 1]) + + # add both streams to ports + c.add_streams(s1, ports = [0]) + + # clear the stats before injecting + c.clear_stats() + + c.start(ports = [0, 1], mult = "5mpps", duration = 10) + + # block until done + c.wait_on_traffic(ports = [0, 1]) + + finally: + c.disconnect() + STLClient class ------------------ +--------------- .. autoclass:: trex_stl_lib.trex_stl_client.STLClient :members: + :member-order: bysource + -Stream class +STLClient snippet ----------------- -.. automodule:: trex_stl_lib.trex_stl_streams - :members: +Example1:: + + c = STLClient() + + try: + # connect to server + c.connect() + + # prepare our ports (my machine has 0 <--> 1 with static route) + c.reset(ports = [0, 1]) + + # add both streams to ports + c.add_streams(s1, ports = [0]) + + # clear the stats before injecting + c.clear_stats() + + c.start(ports = [0, 1], mult = "5mpps", duration = 10) + + # block until done + c.wait_on_traffic(ports = [0, 1]) + + finally: + c.disconnect() + + + +Example2: wait while doing somthing:: + + c = STLClient() + try: + #connect to server + c.connect() + + #.. + + c.start(ports = [0, 1], mult = "5mpps", duration = 10) + + # block until done + while True : + # do somthing else + os.sleep(1) # sleep for 1 sec + # check if the port is still active + if c.is_traffic_active(ports = [0, 1])==False + break; + + finally: + c.disconnect() + + +Example3: Console like:: + + def simple (): + + # create client + #verbose_level = LoggerApi.VERBOSE_HIGH # set to see JSON-RPC commands + c = STLClient(verbose_level = LoggerApi.VERBOSE_REGULAR) + passed = True + + try: + # connect to server + c.connect() + + my_ports=[0,1] + + # prepare our ports + c.reset(ports = my_ports) + + print (" is connected {0}".format(c.is_connected())) + + print (" number of ports {0}".format(c.get_port_count())) + print (" acquired_ports {0}".format(c.get_acquired_ports())) + # port stats + print c.get_stats(my_ports) + + # port info, mac-addr info, speed + print c.get_port_info(my_ports) + + c.ping() + + print("start") + # start traffic on port 0,1 each 10mpps + c.start_line (" -f ../../../../stl/udp_1pkt_simple.py -m 10mpps --port 0 1 ") + time.sleep(2); + c.pause_line("--port 0 1"); + time.sleep(2); + c.resume_line("--port 0 1"); + time.sleep(2); + c.update_line("--port 0 1 -m 5mpps"); # reduce to 5 mpps + time.sleep(2); + c.stop_line("--port 0 1"); # stop both ports + + except STLError as e: + passed = False + print e + + finally: + c.disconnect() + +Example4: Load profile from a file:: + + def simple (): + + # create client + #verbose_level = LoggerApi.VERBOSE_HIGH + c = STLClient(verbose_level = LoggerApi.VERBOSE_REGULAR) + passed = True + + try: + # connect to server + c.connect() + + my_ports=[0,1] + + # prepare our ports + c.reset(ports = my_ports) + + profile_file = "../../../../stl/udp_1pkt_simple.py" # a traffic profile file + + try: # load a profile + profile = STLProfile.load(profile_file) + except STLError as e: + print format_text("\nError while loading profile '{0}'\n".format(profile_file), 'bold') + print e.brief() + "\n" + return + + print profile.dump_to_yaml() # print it as YAML + + c.remove_all_streams(my_ports) # remove all streams + + + c.add_streams(profile.get_streams(), ports = my_ports) # add them + + c.start(ports = [0, 1], mult = "5mpps", duration = 10) # start for 10 sec + + # block until done + c.wait_on_traffic(ports = [0, 1]) # wait + + + finally: + c.disconnect() + diff --git a/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst b/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst new file mode 100644 index 00000000..271ff058 --- /dev/null +++ b/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst @@ -0,0 +1,164 @@ + +Field Engine modules +======================= + +The Field Engine (FE) has limited number of instructions/operation for supporting most use cases. +There is a plan to add LuaJIT to be more flexible at the cost of performance. +The FE can allocate stream variables in a Stream context, write a stream variable to a packet offset, change packet size, etc. + +*Some examples for what can be done:* + +* Change ipv4.tos 1-10 +* Change packet size to be random in the range 64-9K +* Create range of flows (change src_ip, dest_ip, src_port, dest_port) +* Update IPv4 checksum + + +for example this snippet will create SYN Attack:: + + # create attack from random src_ip from 16.0.0.0-18.0.0.254 and random src_port 1025-65000 + # attack 48.0.0.1 server + + def create_stream (self): + + + # TCP SYN + base_pkt = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S") + + + # vm + vm = CTRexScRaw( [ STLVmFlowVar(name="ip_src", + min_value="16.0.0.0", + max_value="18.0.0.254", + size=4, op="random"), + + STLVmFlowVar(name="src_port", + min_value=1025, + max_value=65000, + size=2, op="random"), + + STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ), + + STLVmFixIpv4(offset = "IP"), # fix checksum + + STLVmWrFlowVar(fv_name="src_port", + pkt_offset= "TCP.sport") # fix udp len + + ] + ) + + pkt = STLPktBuilder(pkt = base_pkt, + vm = vm) + + return STLStream(packet = pkt, + random_seed = 0x1234,# can be remove. will give the same random value any run + mode = STLTXCont()) + + + + +CTRexScRaw class +---------------- + +Aggregate a raw instructions objects + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexScRaw + :members: + :member-order: bysource + + +STLVmFlowVar +------------ + +It is alias for CTRexVmDescFlowVar + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescFlowVar + :members: + :member-order: bysource + +STLVmWrMaskFlowVar +------------------ + +It is alias for CTRexVmDescWrMaskFlowVar + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescWrMaskFlowVar + :members: + :member-order: bysource + +STLVmFixIpv4 +------------------ + +It is alias for CTRexVmDescFixIpv4 + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescFixIpv4 + :members: + :member-order: bysource + + +STLVmTrimPktSize +------------------ + +It is alias for CTRexVmDescTrimPktSize + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTrimPktSize + :members: + :member-order: bysource + +STLVmTupleGen +------------------ + +It is alias for CTRexVmDescTupleGen + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTupleGen + :members: + :member-order: bysource + +STLVmTupleGen +------------------ + +It is alias for STLVmTupleGen + +.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTupleGen + :members: + :member-order: bysource + + + +Field Engine snippet +-------------------- + +Example1:: + + + base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + + pad = max(0, size - len(base_pkt)) * 'x' + + vm = CTRexScRaw( [ STLVmTupleGen ( ip_min="16.0.0.1", ip_max="16.0.0.2", + port_min=1025, port_max=65535, + name="tuple"), # define tuple gen + + STLVmWrFlowVar (fv_name="tuple.ip", pkt_offset= "IP.src" ), # write ip to packet IP.src + STLVmFixIpv4(offset = "IP"), # fix checksum + STLVmWrFlowVar (fv_name="tuple.port", pkt_offset= "UDP.sport" ) #write udp.port + ] + ); + + pkt = STLPktBuilder(pkt = base_pkt/pad, + vm = vm) + + + +Example2:: + + #range of source mac-addr + + base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + pad = max(0, size - len(base_pkt)) * 'x' + + vm = CTRexScRaw( [ STLVmFlowVar(name="mac_src", min_value=1, max_value=30, size=2, op="dec",step=1), + STLVmWrMaskFlowVar(fv_name="mac_src", pkt_offset= 11,pkt_cast_size=1, mask=0xff) + ] + ) + + diff --git a/scripts/automation/trex_control_plane/doc_stl/api/index.rst b/scripts/automation/trex_control_plane/doc_stl/api/index.rst index 4e4be230..733a896d 100644 --- a/scripts/automation/trex_control_plane/doc_stl/api/index.rst +++ b/scripts/automation/trex_control_plane/doc_stl/api/index.rst @@ -2,12 +2,28 @@ TRex Stateless API Reference ============================ -**TRex Modules** +**TRex Client: STLClient** .. toctree:: :maxdepth: 4 client_code -**TRex JSON Template** +**TRex Traffic profile: STLProfile,STLStream ** + +.. toctree:: + :maxdepth: 4 + + profile_code + + +**TRex Field Engine: ** + +.. toctree:: + :maxdepth: 4 + + field_engine + + + diff --git a/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst b/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst new file mode 100644 index 00000000..9484f565 --- /dev/null +++ b/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst @@ -0,0 +1,128 @@ + +Traffic profile modules +======================= + +TRex STLProfile profile include a list of STLStream. The profile is a ``program`` of streams with a relation betwean the streams. +Each stream can trigger another stream. Stream can be given a name for a full examples see here Manual_. + +.. _Manual: ../draft_trex_stateless1.html + + +for example:: + + def create_stream (self): + + # create a base packet and pad it to size + size = self.fsize - 4; # no FCS + base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + base_pkt1 = Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025) + base_pkt2 = Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025) + pad = max(0, size - len(base_pkt)) * 'x' + + + return STLProfile( [ STLStream( isg = 1.0, # star in delay in usec + packet = STLPktBuilder(pkt = base_pkt/pad), + mode = STLTXCont( pps = 10), + ), + + STLStream( isg = 2.0, + packet = STLPktBuilder(pkt = base_pkt1/pad), + mode = STLTXCont( pps = 20), + ), + + STLStream( isg = 3.0, + packet = STLPktBuilder(pkt = base_pkt2/pad), + mode = STLTXCont( pps = 30) + + ) + ]).get_streams() + + +STLProfile class +---------------- + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLProfile + :members: + :member-order: bysource + +STLStream +--------- + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLStream + :members: + :member-order: bysource + + +STLStream modes +---------------- + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXMode + :members: + :member-order: bysource + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXCont + :members: + :member-order: bysource + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXSingleBurst + :members: + :member-order: bysource + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXMultiBurst + :members: + :member-order: bysource + +.. autoclass:: trex_stl_lib.trex_stl_streams.STLFlowStats + :members: + :member-order: bysource + + +STLProfile snippet +------------------ + + +Example1:: + + size = self.fsize - 4; # no FCS + base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + base_pkt1 = Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025) + base_pkt2 = Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025) + pad = max(0, size - len(base_pkt)) * 'x' + + + return STLProfile( [ STLStream( isg = 10.0, # star in delay + name ='S0', + packet = STLPktBuilder(pkt = base_pkt/pad), + mode = STLTXSingleBurst( pps = 10, total_pkts = 10), + next = 'S1'), # point to next stream + + STLStream( self_start = False, # stream is disabled enable trow S0 + name ='S1', + packet = STLPktBuilder(pkt = base_pkt1/pad), + mode = STLTXSingleBurst( pps = 10, total_pkts = 20), + next = 'S2' ), + + STLStream( self_start = False, # stream is disabled enable trow S0 + name ='S2', + packet = STLPktBuilder(pkt = base_pkt2/pad), + mode = STLTXSingleBurst( pps = 10, total_pkts = 30 ) + ) + ]).get_streams() + + +Example2:: + + class STLS1(object): + + def get_streams (self, direction = 0): + return [STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap"), + mode = STLTXCont(pps=1000), + flow_stats = STLFlowStats(pg_id = 7)), + + STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_594B_no_crc.pcap"), + mode = STLTXCont(pps=5000), + flow_stats = STLFlowStats(pg_id = 12)) + ] + + + diff --git a/scripts/automation/trex_control_plane/doc_stl/index.rst b/scripts/automation/trex_control_plane/doc_stl/index.rst index fe58db25..b8a1a8e5 100644 --- a/scripts/automation/trex_control_plane/doc_stl/index.rst +++ b/scripts/automation/trex_control_plane/doc_stl/index.rst @@ -1,5 +1,4 @@ .. TRex Stateless Python API documentation - sphinx-quickstart on Tue Jun 2 07:48:10 2015. contain the root `toctree` directive. TRex Stateless Python API @@ -12,6 +11,14 @@ To understand the entirely how the API works and how to set up the server side, **Use the table of contents below or the menu to your left to navigate through the site** +How to Install +============= +.. toctree:: + :maxdepth: 2 + +* **TODO** + + API Reference ============= .. toctree:: |