diff options
Diffstat (limited to 'doc/trex_console.asciidoc')
| -rwxr-xr-x | doc/trex_console.asciidoc | 596 |
1 files changed, 596 insertions, 0 deletions
diff --git a/doc/trex_console.asciidoc b/doc/trex_console.asciidoc new file mode 100755 index 00000000..f6928399 --- /dev/null +++ b/doc/trex_console.asciidoc @@ -0,0 +1,596 @@ +TRex console - commands proposal +================================= +:author: Hanoch Haim +:email: <hhaim@cisco.com> +:revnumber: 0.1 +:quotes.++: +:numbered: +:web_server_url: http://trex-tgn.cisco.com/trex +:local_web_server_url: csi-wiki-01:8181/trex +:toclevels: 4 + +include::trex_ga.asciidoc[] + +== Console + +=== Overview + +The console will use TRex Client API for controling TRex +Some guidelines: + +* Console should not save it own state, it should only cache server state. It assumed there is only one console that has R/W capability so once connected as R/W console (per user/port) it could read the server state and then cache all the operations. +* There could be many read-only clients for same user same ports. The ability to enforce it does not yet exits in the server (will be done). +* Console should sync with server to get the state in connection time and cache the server information locally once the state was changed +* In case of crash/exit of the Console it should sync again at startup +* Let's assume Console acquire all ports - for simplicity, for now. +* Commands will be like bash shell - no order args, many flags +* Ability to show stats in real time. gives the option to open two Console one for stats and one for commands ( many readonly clients) + +=== Ports State + +[options="header",cols="^1,3a"] +|================= +| state | meaning +| IDLE | no streams, does not work +| STREAMS | with streams, does not work +| WORK | with streams, works +| PAUSE | with streams, pause +|================= + + +[source,bash] +---- + + IDLE -> (add streams) -> STREAMS (start) -> WORK (stop) -> STREAMS (start) + | WORK (pause) -> PAUSE (resume )--- + | | + | | + ------------------------------------ + +----- + +=== Tutorial + +First run trex in interactive mode + +[source,bash] +---- +$sudo ./t-rex-64 -i +---- + +on the same machine from a different window connect to to trex + +[source,bash] +---- +$./trex-console +---- + + +from console you can run this + +[source,bash] +---- + +# start traffic on all port +>start -a -m 1 -f stl/imix_1pkt.yaml + +# stop traffic on all port +>stop -a + +# show dynamic statistic +>tui + +#stop all and remove all stats +>reset +---- + +=== Common Arguments + +This section includes arguments that are common to many commands +In the command they will be marked like this (arg name) + +==== Port mask + +this gives the ability to choose batch of ports + +[source,bash] +---- +$command [-a] [-port 1 2 3] [-port 0xff] [-port clients/servers] + + port mask : + [-a] : all ports + [-port 1 2 3] : port 1,2 3 + [-port 0xff] : port by mask 0x1 for port 0 0x3 for port 0 and 1 + [-port clients/servers] : -port clients will choose all the client side ports +---- + +==== Duration + +duration in second or in min or hours + +[source,bash] +---- +$command[-d 100] [-d 10m] [-d 1h] + + duration: + -d 100 : in sec + -d 10m : in min + -d 1h : in hours +---- + + +==== Multiplier + +[source,bash] +---- +$command [-m 100] [-m 10gb] [-m 10kpps] [-m 40%] + + multiplier : + + -m 100 : multiply stream file by this factor + -m 10gb : from graph calculate the maximum rate as this bandwidth ( for each port ) + -m 10kpps : from graph calculate the maximum rate as this pps ( for each port ) + -m 40% : from graph calculate the maximum rate as this precent from total port ( for each port ) +---- + + +=== Commands + + +==== Connect + +[source,bash] +---- + +$trex-con [--ip $IP] [--server $IP] [--rpc-port $PORT] [--async_port port] + + --rpc-port : change the default server - default 5505 for RPC + + --async_port : for sub/pub ZMQ - default 4505 + + --ip or --server :default 127.0.0.1 the TRex server ip +---- + +This command +* try to connect to server +* send ping command +* sync with all the ports info / streams info state +* read all counters stats for reference + +==== reset + +Reset the server and client to a known state - should not be used in a normal scenario + +[source,bash] +---- +$reset +---- + +- force acuire all the ports +- Stop all traffic on all the ports +- Remove all the streams from all the ports + + +==== port + +Configure port state, autoneg, rate etc + +[source,bash] +---- +$port (port mask) --cfg "auto/10/" + + --cfg string with the configuration name + +---- + + +==== clear + +Clear all port stats counters + +[source,bash] +---- +$clear (port mask) +---- + + +==== stats + +Shows global and port statistic + +[source,bash] +---- +$stats (port mask) [-g] [-p] [-ps] + + -g show only global stats + -p only ports stats + -ps only port status (type/driver/link-up/down/negotion type etc) + +---- + +Examples + + +[source,bash] +---- +$stats -g + +Connected : 127.0.0.1 4500 +Version : 1.78 UUID : 12121212 +CPU : 12.0 %% +Total TX : 20.2 Gb/sec +Total Rx : 20.2 Gb/sec +Total PPS : 100MPPS +Total Streams : 10 +Active ports : 4 +---- + +[source,bash] +---- +$stats -p + + port 0 1 2 3 + ------------------------------------ + owner my my my my - place holder no need to implement as we takes all port avali + active on on off off + tx-bytes 12131 0 0 0 + rx-bytes 0 0 0 0 + tx-pkts 0 0 0 0 + rx-pkts 0 0 0 0 + tx-errors 0 0 0 0 + rx-errors 0 0 0 0 + Tx-Bw 12gb 1.3Gb 0 0 + Rx-Bw 10mb 11.2mb 0 0 +---- + +In case of more than four ports should show only the first ports or by mask ( --port mask) + + +[source,bash] +---- +$stats -ps + + --- port status + port 0 1 2 3 + ------------------------------------ + port-type I350 I350 I350 I350 + maximum 1Gb 1Gb 1Gb !gb + link on on off off +---- + + +==== streams + +Shows the configured streams on each port/ports +Should show from client cache + +[source,bash] +---- +$streams (port mask) [--streams mask] [-f] [--full] [--graph] + + --port mask, e.g --port 1 2 3 4 + --streams mask e.g. --streams 1 2 + -f /--full print stream info in a JSON format with all the information + --graph : add the graph in time of each port stream +---- + + +example + +[source,bash] +---- +$streams + +port 0 : imix/a.yaml + + stream id , packet type , length , mode , rate , next + + 0 , ip/tcp , 64 , continues , 100KPPS , none + + 1 , ip/udp , 128 , burst , 200KPPS , none + + 2 , ip/udp , 1500 , multi-burst , 100KPPS , none + + + +port 1 : imix/a.yaml + + + 0 , ip/tcp , 64 , continues , 100KPPS , none + + 1 , ip/udp , 128 , burst , 200KPPS , none + + 2 , ip/udp , 1500 , multi-burst , 100KPPS , none + +---- + + +show only port 1 and 2 + +[source,bash] +---- +$streams --port 1 2 + + .. + .. +---- + +[source,bash] +---- +$streams --port 0 --streams 0 -f + + + show the full info on stream 0 and port 0, print in JSON format + +---- + + + + +==== start + +* work on a set of ports +* remove all streams +* load new streams +* start traffic with specific multiplier +* limit the traffic to a specific duration +* port state should be stopped, in case of --force stop the port +* in case one of the port is not stop don't start any port +* all ports should be in state IDLE or STREAMS + +[source,bash] +---- +$start [--force] (port mask) [-f stl/imix.yaml] [-db ab] (duration) (multiplier) + + + stream to load: + -f stl/imix.yaml : load from local disk the streams file + --db stream that was loaded to db + + force: + --force stop ports if they are active + +---- + +examples + + +[source,bash] +---- +$start -a -f stl/imix.yaml -m 10gb +---- +start this profile on all all ports maximum bandwidth is 10gb + + +[source,bash] +---- +$start -port 1 2 -f stl/imix.yaml -m 100 +---- +start this profile on port 1,2 multiply by 100 + + +[NOTE] +===================================== + in case of start command without args, try to remember the last args given and reprint them +===================================== + +==== stop + +* work on a set of ports +* change the mode of the port to stopped +* do not remove the streams +* in case port state is already stopped don't do anything +* all ports should be in state WORK + + +[source,bash] +---- +$stop (port mask) + + See ports command explanation from the start + +---- + + +==== pause + +* work on a set of ports +* move a wokring set of ports to a state of pause +* all ports should be in state WORK + + + +[source,bash] +---- +$pause (port mask) + + see ports command explanation from start + +---- + + +==== resume + +* work on a set of ports +* move a wokring set of port to a state of resume +* all ports should be in state PAUSE + + + +[source,bash] +---- +$resume (port mask) + + see ports command explanation from start + +---- + + +==== restart + +* restart the work on the loaded streams +* same as start without the -f /--db switch +* all ports should be in state STREAMS + +[source,bash] +---- +$restart (port mask) (duration) (multiplier) + + see ports command explanation from start + +---- + +==== update + +* all ports should be in state WORK + + +[source,bash] +---- +>update (port mask) (multiplier) +---- +Update the bandwidth multiplier for a mask of ports + + +[NOTE] +===================================== + Here we could add the ability to disable/enable specific stream, load new stream dynamically etc. +===================================== + + +==== async events queue + +there are two ways to know if somthing async happned + +* pool the state +* get async event + +example for events are: + +* link is up/down +* port id stoped +* port id start +* errors +* info + + +[source,bash] +---- +$clear_events +---- + +clear events queue + +[source,bash] +---- +$show_events +---- +show a list of events from the queue + +[source,bash] +---- +$remove --event [event-id] --top + --event : remove the event-id from the list + --top : remove the even from the top +---- + + +[source,bash] +---- +$wait_for_event [event-id] +---- +wait only in script mode, simple way to wait for event like all port stopped + + +==== stream database commands + +* load/remove/show streams from memory + + +[source,bash] +---- +$db_load -f [stream ] -name [name] +---- + +[source,bash] +---- +$db_remove -name [name] +---- + +[source,bash] +---- +$db_show [--all] [--name $name] [--full] +---- + + +==== script + +[source,bash] +---- +$script -f script_name +----- + +run script of commands + + +==== tui + +shows the stats in a textual window (like top) + +[source,bash] +---- +$tui +---- + +enter to a mode of Stats and present 3 type of windows +* global/port stats/version/connected etc +* per port +* per port streams info + + +get keyboard + q - quit the gui window + c - clear all counters + + +=== Priorty + +* Console logger - JSON-RPC into a file ( req/res) +* start/stop/stats/tui/streams/reset +* db +* port +* events +* pause/resume/restart/restart +* scripts +* move all the debug commands to be dbg_xxx +* implement advance -m ( by reading graphs) +* Enforcement of one user/port with R/W capability + +=== More ideas + +* define a YAML format that include stream per port inside so in away load each YAML to each port +* add ability to load range of ip/mac program in YAML file + fields : + name : ipv4.src + offset : 12 + range : + min_ip : 10.0.0.1/ipv6 addr + max_ip : 10.0.0.20 + inc : 1 + dec : 1 + start : 10.0.0.4 + + name : ipv4.dest + offset : 45 + range : + min_ip : 10.0.0.1 + max_ip : 10.0.0.2 + + +=== Change log + +[options="header",cols="^1,^h,3a"] +|================= +| Version | name | meaning +| 1.00 | Hanoch Haim (hhaim) | +- first version +| 1.01 | Hanoch Haim (hhaim) | +- Incorporate Itay comments +|================= + + + |