TRex console - commands proposal ================================= :author: Hanoch Haim :email: :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 |=================