1# Introduction 2 3Compile ff tools 4 5 make 6 7Install ff tools, all ff tools will be installed to `/usr/local/bin/f-stack/`, and some soft link will be created in `/usr/local/bin`, such as `ff_top`,`ff_traffic`, etc. 8 9 make install 10 11Directory `compat` implements an ipc library using dpdk `rte_ring` and ports some source files compatible with FreeBSD and Linux. 12 13Directory `sbin` contains all the tools binary that compiled. 14 15All other directories are useful tools ported from FreeBSD. 16Since F-Stack is multi-process architecture and every process has an independent stack, so we must communicate with every F-Stack process. 17Each tool add an option `-p`(Which F-Stack process to communicate with, default 0), except that, it is same with the original FreeBSD. 18 19Note that these tools must be executed serially. 20 21# sysctl 22Usage: 23``` 24sysctl -p <f-stack proc_id> [-bdehiNnoqTtWx] [ -B <bufsize> ] [-f filename] name[=value] ... 25sysctl -p <f-stack proc_id> [-bdehNnoqTtWx] [ -B <bufsize> ] -a 26``` 27For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?sysctl). 28 29# ifconfig 30Usage: 31``` 32ifconfig -p <f-stack proc_id> [-f type:format] %sinterface address_family 33 [address [dest_address]] [parameters] 34 ifconfig -p <f-stack proc_id> interface create 35 ifconfig -p <f-stack proc_id> -a %s[-d] [-m] [-u] [-v] [address_family] 36 ifconfig -p <f-stack proc_id> -l [-d] [-u] [address_family] 37 ifconfig -p <f-stack proc_id> %s[-d] [-m] [-u] [-v] 38``` 39We has supportted inet6, you can config ipv6 address like this: 40 41 ifconfig -p <f-stack proc_id> interface inet6 <ipv6 address> autoconf 42 43Unsupported interfaces or parameters: 44``` 45MAC(Mandatory Access Control) 46media 47SFP/SFP+ 48IEEE80211 Wireless 49pfsync 50LAGG LACP 51jail 52``` 53For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ifconfig). 54 55# route 56Usage: 57``` 58route -p <f-stack proc_id> [-46dnqtv] command [[modifiers] args] 59``` 60Examples: 61``` 62 Add a default route: 63 64 ./sbin/route -p 0 add -net 0.0.0.0/0 192.168.1.1 65 66 A shorter version of adding a default route can also be written as: 67 68 ./sbin/route -p 0 add default 192.168.1.1 69 70 Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gate- 71 way: 72 73 ./sbin/route -p 0 add -net 172.16.10.0/24 172.16.1.1 74 75 Change the gateway of an already established static route in the routing 76 table: 77 78 ./sbin/route -p 0 change -net 172.16.10.0/24 172.16.1.2 79 80 Display the route for a destination network: 81 82 ./sbin/route -p 0 show 172.16.10.0 83 ./sbin/route -p 0 -6 show ::/0 84 85 Delete a static route from the routing table: 86 87 ./sbin/route -p 0 delete -net 172.16.10.0/24 172.16.1.2 88 89 Remove all routes from the routing table: 90 91 ./sbin/route -p 0 flush 92 93 FreeBSD uses `netstat -rn ` to list the route table which we havn't ported, 94 you can execute the following command instead, `-d` means debug mode, `-v` 95 means verbose. 96 ./sbin/route -p 0 -d -v flush 97``` 98Note that, if you want to modify the route table, you must use `-p` to execute the same command for each f-stack process. 99 100For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?route). 101 102# top 103Usage: 104``` 105top [-p <f-stack proc_id>] [-P <max proc_id>] [-d <secs>] [-n <num>] 106``` 107Examples: 108``` 109./sbin/top -p 0 -P 3 110|---------|---------|---------|---------|---------------| 111| proc_id| idle| sys| usr| loop| 112|---------|---------|---------|---------|---------------| 113| 0| 92.44%| 4.00%| 3.56%| 13427| 114| 1| 92.18%| 4.21%| 3.61%| 14035| 115| 2| 92.19%| 4.19%| 3.62%| 13929| 116| 3| 92.33%| 4.14%| 3.53%| 13938| 117| total| 369.14%| 16.54%| 14.32%| 55329| 118| | | | | | 119| 0| 92.27%| 4.10%| 3.63%| 13438| 120| 1| 92.03%| 4.27%| 3.70%| 13906| 121| 2| 92.08%| 4.24%| 3.68%| 13817| 122| 3| 92.28%| 4.15%| 3.57%| 13759| 123| total| 368.65%| 16.77%| 14.58%| 54920| 124| | | | | | 125| 0| 91.88%| 4.30%| 3.81%| 13802| 126| 1| 91.94%| 4.32%| 3.74%| 13928| 127| 2| 92.10%| 4.24%| 3.66%| 13856| 128| 3| 92.30%| 4.14%| 3.56%| 13708| 129| total| 368.22%| 17.00%| 14.77%| 55294| 130| | | | | | 131``` 132 133# netstat 134Usage: 135``` 136 netstat -P <f-stack proc_id> [-46AaLnRSTWx] [-f protocol_family | -p protocol] 137 netstat -P <f-stack proc_id> -i | -I interface [-46abdhnW] [-f address_family] 138 netstat -P <f-stack proc_id> -w wait [-I interface] [-46d] [-q howmany] 139 netstat -P <f-stack proc_id> -s [-46sz] [-f protocol_family | -p protocol] 140 netstat -P <f-stack proc_id> -i | -I interface -s [-46s] 141 [-f protocol_family | -p protocol] 142 netstat -P <f-stack proc_id> -B [-z] [-I interface] 143 netstat -P <f-stack proc_id> -r [-46AnW] [-F fibnum] [-f address_family] 144 netstat -P <f-stack proc_id> -rs [-s] 145 netstat -P <f-stack proc_id> -g [-46W] [-f address_family] 146 netstat -P <f-stack proc_id> -gs [-46s] [-f address_family] 147 netstat -P <f-stack proc_id> -Q 148``` 149 150Unsupported commands or features: 151``` 152-M 153-N 154-m 155netgraph 156ipsec 157``` 158 159For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?netstat). 160 161# ngctl 162Usage: 163``` 164ngctl -p <f-stack proc_id> [-d] [-f file] [-n name] [command ...] 165``` 166 167About interactive mode: 168- if you have `libedit` in your system, you can turn on `MK_HAVE_LIBEDIT` in `opts.mk`, 169 the interactive mode will support generic line editing, history functions. 170 171 172For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ngctl). 173 174# ipfw 175Usage: 176``` 177ipfw -P <f-stack proc_id> [-abcdefhnNqStTv] <command> 178 179where <command> is one of the following: 180 181add [num] [set N] [prob x] RULE-BODY 182{pipe|queue} N config PIPE-BODY 183[pipe|queue] {zero|delete|show} [N{,N}] 184nat N config {ip IPADDR|if IFNAME|log|deny_in|same_ports|unreg_only|reset| 185 reverse|proxy_only|redirect_addr linkspec| 186 redirect_port linkspec|redirect_proto linkspec} 187set [disable N... enable N...] | move [rule] X to Y | swap X Y | show 188set N {show|list|zero|resetlog|delete} [N{,N}] | flush 189table N {add ip[/bits] [value] | delete ip[/bits] | flush | list} 190table all {flush | list} 191 192RULE-BODY: check-state [PARAMS] | ACTION [PARAMS] ADDR [OPTION_LIST] 193ACTION: check-state | allow | count | deny | unreach{,6} CODE | 194 skipto N | {divert|tee} PORT | forward ADDR | 195 pipe N | queue N | nat N | setfib FIB | reass 196PARAMS: [log [logamount LOGLIMIT]] [altq QUEUE_NAME] 197ADDR: [ MAC dst src ether_type ] 198 [ ip from IPADDR [ PORT ] to IPADDR [ PORTLIST ] ] 199 [ ipv6|ip6 from IP6ADDR [ PORT ] to IP6ADDR [ PORTLIST ] ] 200IPADDR: [not] { any | me | ip/bits{x,y,z} | table(t[,v]) | IPLIST } 201IP6ADDR: [not] { any | me | me6 | ip6/bits | IP6LIST } 202IP6LIST: { ip6 | ip6/bits }[,IP6LIST] 203IPLIST: { ip | ip/bits | ip:mask }[,IPLIST] 204OPTION_LIST: OPTION [OPTION_LIST] 205OPTION: bridged | diverted | diverted-loopback | diverted-output | 206 {dst-ip|src-ip} IPADDR | {dst-ip6|src-ip6|dst-ipv6|src-ipv6} IP6ADDR | 207 {dst-port|src-port} LIST | 208 estab | frag | {gid|uid} N | icmptypes LIST | in | out | ipid LIST | 209 iplen LIST | ipoptions SPEC | ipprecedence | ipsec | iptos SPEC | 210 ipttl LIST | ipversion VER | keep-state | layer2 | limit ... | 211 icmp6types LIST | ext6hdr LIST | flow-id N[,N] | fib FIB | 212 mac ... | mac-type LIST | proto LIST | {recv|xmit|via} {IF|IPADDR} | 213 setup | {tcpack|tcpseq|tcpwin} NN | tcpflags SPEC | tcpoptions SPEC | 214 tcpdatalen LIST | verrevpath | versrcreach | antispoof 215``` 216Note [dummynet](https://www.freebsd.org/cgi/man.cgi?query=dummynet) is not supported yet. 217 218For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ipfw) or [handbook](https://www.freebsd.org/doc/handbook/firewalls-ipfw.html). 219 220# arp 221Usage 222``` 223usage: arp -p <f-stack proc_id> [-n] [-i interface] hostname 224 arp -p <f-stack proc_id> [-n] [-i interface] -a 225 arp -p <f-stack proc_id> -d hostname [pub] 226 arp -p <f-stack proc_id> -d [-i interface] -a 227 arp -p <f-stack proc_id> -s hostname ether_addr [temp] [reject | blackhole] [pub [only]] 228 arp -p <f-stack proc_id> -S hostname ether_addr [temp] [reject | blackhole] [pub [only]] 229 arp -p <f-stack proc_id> -f filename 230``` 231 232For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?arp). 233 234# traffic 235Usage: 236``` 237traffic [-p <f-stack proc_id>] [-P <max proc_id>] [-d <secs>] [-n <num>] 238``` 239Examples: 240``` 241./sbin/traffic -p 0 -P 3 242 243|---------|--------------------|--------------------|--------------------|--------------------| 244| proc_id| rx packets| rx bytes| tx packets| tx bytes| 245|---------|--------------------|--------------------|--------------------|--------------------| 246| 0| 39594| 3721836| 79218| 30945013| 247| 1| 43427| 4082138| 86860| 33918830| 248| 2| 37708| 3544552| 75448| 29462444| 249| 3| 41306| 3882764| 82598| 32254519| 250| total| 162035| 15231290| 324124| 126580806| 251| | | | | | 252| 0| 40849| 3839831| 81686| 31898383| 253| 1| 44526| 4185444| 89056| 34776368| 254| 2| 38491| 3618154| 76974| 30058347| 255| 3| 41631| 3913314| 83244| 32506782| 256| total| 165497| 15556743| 330960| 129239880| 257| | | | | | 258| 0| 41136| 3866750| 82268| 32125654| 259| 1| 42184| 3965296| 84372| 32947266| 260| 2| 39182| 3683108| 78358| 30598799| 261| 3| 41458| 3897052| 82926| 32382603| 262| total| 163960| 15412206| 327924| 128054322| 263| | | | | | 264``` 265 266# how to implement a custom tool for communicating with F-Stack process 267 268Add a new FF_MSG_TYPE in ff_msg.h: 269``` 270enum FF_MSG_TYPE { 271 FF_UNKNOWN = 0, 272 FF_SYSCTL, 273 FF_HELLOWORLD, 274}; 275``` 276 277Define a structure used to communicate: 278``` 279struct ff_helloworld_args { 280 void *request; 281 size_t req_len; 282 void *reply; 283 size_t rep_len; 284}; 285``` 286Note that, when using struct ff_helloworld_args, pointers in this structure must point to the addresses range from ff_msg.buf_addr and ff_msg.buf_addr+ff_msg.buf_len, ff_msg.buf_len is (10240 - sizeof(struct ff_msg)). 287 288And add it to ff_msg: 289``` 290struct ff_msg { 291 ... 292 union { 293 struct ff_sysctl_args sysctl; 294 struct ff_helloworld_args helloworld; 295 }; 296}; 297``` 298 299Modify ff_dpdk_if.c, add a handle function: 300``` 301static inline void 302handle_helloworld_msg(struct ff_msg *msg, uint16_t proc_id) 303{ 304 printf("helloworld msg recved.\n"); 305 msg->result = 0; 306 rte_ring_enqueue(msg_ring[proc_id].ring[1], msg); 307} 308 309static inline void 310handle_msg(struct ff_msg *msg, uint16_t proc_id) 311{ 312 switch (msg->msg_type) { 313 case FF_SYSCTL: 314 handle_sysctl_msg(msg, proc_id); 315 break; 316 case FF_HELLOWORLD: 317 handle_helloworld_msg(msg, proc_id); 318 default: 319 handle_default_msg(msg, proc_id); 320 break; 321 } 322} 323``` 324 325Create helloworld.c: 326 327``` 328int main() 329{ 330 struct ff_msg *msg = ff_ipc_msg_alloc(); 331 332 char *buf = msg->buf_addr; 333 334 msg->helloworld.request = buf; 335 memcpy(msg->helloworld.request, "hello", 5); 336 msg->helloworld.req_len = 5; 337 buf += 5; 338 339 msg->helloworld.reply = buf; 340 msg->helloworld.rep_len = 10; 341 342 ff_ipc_send(msg, 0); 343 344 struct ff_msg *retmsg; 345 ff_ipc_recv(retmsg, 0); 346 assert(remsg==msg); 347 348 ff_ipc_msg_free(msg); 349} 350 351``` 352 353The Makefile may like this: 354``` 355TOPDIR?=${CURDIR}/../.. 356 357PROG=helloworld 358 359include ${TOPDIR}/tools/prog.mk 360``` 361