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