1# Introduction 2 3Directory `compat` implements an ipc library using dpdk `rte_ring` and ports some source files compatible with FreeBSD and Linux. 4 5All other directories are useful tools ported from FreeBSD. 6Since F-Stack is multi-process architecture and every process has an independent stack, so we must communicate with every F-Stack process. 7Each tool add an option `-p`(Which F-Stack process to communicate with, default 0), except that, it is same with the original FreeBSD. 8 9Note that these tools must be executed serially. 10 11# sysctl 12Usage: 13``` 14sysctl -p <f-stack proc_id> [-bdehiNnoqTtWx] [ -B <bufsize> ] [-f filename] name[=value] ... 15sysctl -p <f-stack proc_id> [-bdehNnoqTtWx] [ -B <bufsize> ] -a 16``` 17For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?sysctl). 18 19# ifconfig 20Usage: 21``` 22ifconfig -p <f-stack proc_id> [-f type:format] %sinterface address_family 23 [address [dest_address]] [parameters] 24 ifconfig -p <f-stack proc_id> interface create 25 ifconfig -p <f-stack proc_id> -a %s[-d] [-m] [-u] [-v] [address_family] 26 ifconfig -p <f-stack proc_id> -l [-d] [-u] [address_family] 27 ifconfig -p <f-stack proc_id> %s[-d] [-m] [-u] [-v] 28``` 29Unsupported interfaces or parameters: 30``` 31inet6 32MAC(Mandatory Access Control) 33media 34SFP/SFP+ 35IEEE80211 Wireless 36pfsync 37LAGG LACP 38jail 39``` 40For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ifconfig). 41 42# route 43Usage: 44``` 45route -p <f-stack proc_id> [-46dnqtv] command [[modifiers] args] 46``` 47Examples: 48``` 49 Add a default route: 50 51 ./route -p 0 add -net 0.0.0.0/0 192.168.1.1 52 53 A shorter version of adding a default route can also be written as: 54 55 ./route -p 0 add default 192.168.1.1 56 57 Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gate- 58 way: 59 60 ./route -p 0 add -net 172.16.10.0/24 172.16.1.1 61 62 Change the gateway of an already established static route in the routing 63 table: 64 65 ./route -p 0 change -net 172.16.10.0/24 172.16.1.2 66 67 Display the route for a destination network: 68 69 ./route -p 0 show 172.16.10.0 70 71 Delete a static route from the routing table: 72 73 ./route -p 0 delete -net 172.16.10.0/24 172.16.1.2 74 75 Remove all routes from the routing table: 76 77 ./route -p 0 flush 78 79 FreeBSD uses `netstat -rn ` to list the route table which we havn't ported, 80 you can execute the following command instead, `-d` means debug mode, `-v` 81 means verbose. 82 ./route -p 0 -d -v flush 83``` 84Note that, if you want to modify the route table, you must use `-p` to execute the same command for each f-stack process. 85 86For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?route). 87 88# top 89Usage: 90``` 91top [-p <f-stack proc_id>] [-d <secs>] [-n num] 92``` 93Examples: 94``` 95./tools/top/top 96 97|---------|---------|---------|---------------| 98| idle| sys| usr| loop| 99|---------|---------|---------|---------------| 100| 99.69%| 0.00%| 0.31%| 8214640| 101| 99.77%| 0.00%| 0.23%| 8205713| 102| 5.02%| 45.19%| 49.79%| 769435| 103| 0.00%| 19.88%| 80.12%| 393| 104| 0.00%| 20.28%| 79.72%| 395| 105| 0.00%| 15.50%| 84.50%| 403| 106| 0.00%| 31.31%| 68.69%| 427| 107| 32.07%| 8.78%| 59.15%| 2342862| 108| 99.79%| 0.00%| 0.21%| 9974439| 109| 99.81%| 0.00%| 0.19%| 7336153| 110| 99.79%| 0.00%| 0.21%| 8147676| 111``` 112 113# netstat 114Usage: 115``` 116 netstat -P <f-stack proc_id> [-46AaLnRSTWx] [-f protocol_family | -p protocol] 117 netstat -P <f-stack proc_id> -i | -I interface [-46abdhnW] [-f address_family] 118 netstat -P <f-stack proc_id> -w wait [-I interface] [-46d] [-q howmany] 119 netstat -P <f-stack proc_id> -s [-46sz] [-f protocol_family | -p protocol] 120 netstat -P <f-stack proc_id> -i | -I interface -s [-46s] 121 [-f protocol_family | -p protocol] 122 netstat -P <f-stack proc_id> -B [-z] [-I interface] 123 netstat -P <f-stack proc_id> -r [-46AnW] [-F fibnum] [-f address_family] 124 netstat -P <f-stack proc_id> -rs [-s] 125 netstat -P <f-stack proc_id> -g [-46W] [-f address_family] 126 netstat -P <f-stack proc_id> -gs [-46s] [-f address_family] 127 netstat -P <f-stack proc_id> -Q 128``` 129 130Unsupported commands or features: 131``` 132-M 133-N 134-m 135ipv6 136netgraph 137ipsec 138``` 139 140For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?netstat). 141 142# ngctl 143Usage: 144``` 145ngctl -p <f-stack proc_id> [-d] [-f file] [-n name] [command ...] 146``` 147 148About interactive mode: 149- if you have `libedit` in your system, you can turn on `MK_HAVE_LIBEDIT` in `opts.mk`, 150 the interactive mode will support generic line editing, history functions. 151 152 153For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ngctl). 154 155# ipfw 156Usage: 157``` 158ipfw -P <f-stack proc_id> [-abcdefhnNqStTv] <command> 159 160where <command> is one of the following: 161 162add [num] [set N] [prob x] RULE-BODY 163{pipe|queue} N config PIPE-BODY 164[pipe|queue] {zero|delete|show} [N{,N}] 165nat N config {ip IPADDR|if IFNAME|log|deny_in|same_ports|unreg_only|reset| 166 reverse|proxy_only|redirect_addr linkspec| 167 redirect_port linkspec|redirect_proto linkspec} 168set [disable N... enable N...] | move [rule] X to Y | swap X Y | show 169set N {show|list|zero|resetlog|delete} [N{,N}] | flush 170table N {add ip[/bits] [value] | delete ip[/bits] | flush | list} 171table all {flush | list} 172 173RULE-BODY: check-state [PARAMS] | ACTION [PARAMS] ADDR [OPTION_LIST] 174ACTION: check-state | allow | count | deny | unreach{,6} CODE | 175 skipto N | {divert|tee} PORT | forward ADDR | 176 pipe N | queue N | nat N | setfib FIB | reass 177PARAMS: [log [logamount LOGLIMIT]] [altq QUEUE_NAME] 178ADDR: [ MAC dst src ether_type ] 179 [ ip from IPADDR [ PORT ] to IPADDR [ PORTLIST ] ] 180 [ ipv6|ip6 from IP6ADDR [ PORT ] to IP6ADDR [ PORTLIST ] ] 181IPADDR: [not] { any | me | ip/bits{x,y,z} | table(t[,v]) | IPLIST } 182IP6ADDR: [not] { any | me | me6 | ip6/bits | IP6LIST } 183IP6LIST: { ip6 | ip6/bits }[,IP6LIST] 184IPLIST: { ip | ip/bits | ip:mask }[,IPLIST] 185OPTION_LIST: OPTION [OPTION_LIST] 186OPTION: bridged | diverted | diverted-loopback | diverted-output | 187 {dst-ip|src-ip} IPADDR | {dst-ip6|src-ip6|dst-ipv6|src-ipv6} IP6ADDR | 188 {dst-port|src-port} LIST | 189 estab | frag | {gid|uid} N | icmptypes LIST | in | out | ipid LIST | 190 iplen LIST | ipoptions SPEC | ipprecedence | ipsec | iptos SPEC | 191 ipttl LIST | ipversion VER | keep-state | layer2 | limit ... | 192 icmp6types LIST | ext6hdr LIST | flow-id N[,N] | fib FIB | 193 mac ... | mac-type LIST | proto LIST | {recv|xmit|via} {IF|IPADDR} | 194 setup | {tcpack|tcpseq|tcpwin} NN | tcpflags SPEC | tcpoptions SPEC | 195 tcpdatalen LIST | verrevpath | versrcreach | antispoof 196``` 197Note [dummynet](https://www.freebsd.org/cgi/man.cgi?query=dummynet) is not supported yet. 198 199For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ipfw) or [handbook](https://www.freebsd.org/doc/handbook/firewalls-ipfw.html). 200 201# how to implement a custom tool for communicating with F-Stack process 202 203Add a new FF_MSG_TYPE in ff_msg.h: 204``` 205enum FF_MSG_TYPE { 206 FF_UNKNOWN = 0, 207 FF_SYSCTL, 208 FF_HELLOWORLD, 209}; 210``` 211 212Define a structure used to communicate: 213``` 214struct ff_helloworld_args { 215 void *request; 216 size_t req_len; 217 void *reply; 218 size_t rep_len; 219}; 220``` 221Note 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)). 222 223And add it to ff_msg: 224``` 225struct ff_msg { 226 ... 227 union { 228 struct ff_sysctl_args sysctl; 229 struct ff_helloworld_args helloworld; 230 }; 231}; 232``` 233 234Modify ff_dpdk_if.c, add a handle function: 235``` 236static inline void 237handle_helloworld_msg(struct ff_msg *msg, uint16_t proc_id) 238{ 239 printf("helloworld msg recved.\n"); 240 msg->result = 0; 241 rte_ring_enqueue(msg_ring[proc_id].ring[1], msg); 242} 243 244static inline void 245handle_msg(struct ff_msg *msg, uint16_t proc_id) 246{ 247 switch (msg->msg_type) { 248 case FF_SYSCTL: 249 handle_sysctl_msg(msg, proc_id); 250 break; 251 case FF_HELLOWORLD: 252 handle_helloworld_msg(msg, proc_id); 253 default: 254 handle_default_msg(msg, proc_id); 255 break; 256 } 257} 258``` 259 260Create helloworld.c: 261 262``` 263int main() 264{ 265 struct ff_msg *msg = ff_ipc_msg_alloc(); 266 267 char *buf = msg->buf_addr; 268 269 msg->helloworld.request = buf; 270 memcpy(msg->helloworld.request, "hello", 5); 271 msg->helloworld.req_len = 5; 272 buf += 5; 273 274 msg->helloworld.reply = buf; 275 msg->helloworld.rep_len = 10; 276 277 ff_ipc_send(msg, 0); 278 279 struct ff_msg *retmsg; 280 ff_ipc_recv(retmsg, 0); 281 assert(remsg==msg); 282 283 ff_ipc_msg_free(msg); 284} 285 286``` 287 288The Makefile may like this: 289``` 290TOPDIR?=${CURDIR}/../.. 291 292PROG=helloworld 293 294include ${TOPDIR}/tools/prog.mk 295``` 296