Skip to content

Commit 6dbef5f

Browse files
rjarryrjarry
committed
readme: add quickstart
Signed-off-by: Robin Jarry <[email protected]>
1 parent be5144d commit 6dbef5f

File tree

1 file changed

+149
-27
lines changed

1 file changed

+149
-27
lines changed

‎README.md

+149-27
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,156 @@
1-
# `brouter`: *A sample DPDK router based on rte_graph*
1+
# *Boring Router*: a sample router based on DPDK
22

33
`brouter` stands for *Boring Router*. *Boring* because it should work in all
44
circumstances, without any fuss nor extended configuration/tuning.
55

6-
## Better ideas for project names?
7-
8-
| initials | full name | notes |
9-
|----------|-----------------|--------------------------------------------------|
10-
| tr | table router | woodworking joke (clash with `/usr/bin/tr`) |
11-
| hr | hand router | woodworking joke |
12-
| br | boring router | boring ssl reference, brouter joke in french |
13-
| vr | virtual router | even more boring than boring router |
14-
| ur | micro router | sounds nice, maybe misleading? |
15-
| rr | routing router | ends like frr, lion roar joke, makes no sense |
16-
17-
I lean on the JR acronym for several reasons:
18-
19-
- these are my initials (nobody needs to know).
20-
- `jr` and `jr-cli` are awesome.
21-
- nice reference to [J.R. Ewing](https://fr.wikipedia.org/wiki/J._R._Ewing).
22-
23-
| initials | full name | notes |
24-
|----------|-----------------|--------------------------------------------------|
25-
| jr | just (a) router | dinner de cons joke |
26-
| jr | jet router | short and cute, [PHP project homonym] |
27-
| jr | jumbo router | funnier yet not too extreme, jumbo frames hint |
28-
| jr | junk router | why not? |
29-
| jr | jump router | it jumps like a kangaroo |
30-
31-
[PHP project homonym]: https://github.com/sformisano/jetrouter
6+
*Boring Router* is a DPDK based network processing application. It uses the
7+
`rte_graph` library for data path processing.
8+
9+
It comes with a client library to configure it over a standard UNIX socket and
10+
a CLI that uses that library. The CLI can be used as an interactive shell, but
11+
also in scripts one command at a time, or by batches.
12+
13+
## Quick start
14+
15+
### System dependencies:
16+
17+
```sh
18+
dnf install gcc git libcmocka-devel libedit-devel libevent-devel make meson \
19+
ninja-build numactl-devel pkgconf python3-pyelftools scdoc
20+
```
21+
22+
or
23+
24+
```sh
25+
apt install build-essential gcovr libcmocka-dev libedit-dev libevent-dev \
26+
libnuma-dev meson ninja-build pkg-config python3-pyelftools scdoc
27+
```
28+
29+
Compiling:
30+
31+
```
32+
git clone https://github.com/rjarry/brouter
33+
cd brouter
34+
make
35+
```
36+
37+
### Running the router
38+
39+
```console
40+
~# taskset --cpu-list 6-19,26-39 ./build/br -v
41+
BR: dpdk_init: DPDK version: DPDK 23.11.0
42+
BR: dpdk_init: EAL arguments: -l 6 -a 0000:00:00.0 --in-memory --log-level=*:info
43+
EAL: Detected CPU lcores: 40
44+
EAL: Detected NUMA nodes: 1
45+
...
46+
BR: listen_api_socket: listening on API socket /run/br.sock
47+
```
48+
49+
### Starting the CLI
50+
51+
```console
52+
~# ./build/br-cli
53+
Welcome to the boring router CLI.
54+
Use ? for help and <tab> for command completion.
55+
br#
56+
quit Exit the CLI.
57+
route4 Manage IPv4 routes.
58+
nh4 Manage IPv4 next hops.
59+
stats Manage stack statistics.
60+
rxq Manage ports RX queues.
61+
port Manage ports.
62+
graph Get information about the packet processing graph.
63+
```
64+
65+
Multiple commands can be piped into standard input:
66+
67+
```console
68+
~# ./build/br-cli -ex < commands.list
69+
+ port add 0000:18:00.0
70+
Created port 0
71+
+ port add 0000:18:00.1
72+
Created port 1
73+
+ port set 0 qsize 4096
74+
+ port set 1 qsize 4096
75+
+ rxq set port 0 rxq 0 cpu 7
76+
+ rxq set port 1 rxq 0 cpu 27
77+
+ port list
78+
INDEX DEVICE RX_QUEUES RXQ_SIZE TX_QUEUES TXQ_SIZE MAC
79+
1 0000:18:00.1 1 4096 2 4096 b8:3f:d2:fa:53:87
80+
0 0000:18:00.0 1 4096 2 4096 b8:3f:d2:fa:53:86
81+
+ rxq list
82+
PORT RXQ_ID CPU_ID ENABLED
83+
0 0 7 1
84+
1 0 27 1
85+
+ nh4 add 172.16.0.1 mac b8:3f:d2:fa:53:7a port 0
86+
+ nh4 add 172.16.1.1 mac b8:3f:d2:fa:53:7b port 1
87+
+ route4 add 172.16.0.0/24 via 172.16.0.1
88+
+ route4 add 172.16.1.0/24 via 172.16.1.1
89+
+ route4 add 192.168.0.0/16 via 172.16.0.1
90+
+ route4 add 0.0.0.0/0 via 172.16.1.1
91+
```
92+
93+
The CLI can be used as a one-shot command (with bash completion built-in):
94+
95+
```console
96+
~# complete -C './build/br-cli --bash-complete' ./build/br-cli
97+
~# ./build/br-cli <TAB><TAB>
98+
-e (Abort on first error.)
99+
--err-exit (Abort on first error.)
100+
graph (Get information about the packet processing graph.)
101+
--help (Show usage help and exit.)
102+
-h (Show usage help and exit.)
103+
nh4 (Manage IPv4 next hops.)
104+
port (Manage ports.)
105+
quit (Exit the CLI.)
106+
route4 (Manage IPv4 routes.)
107+
rxq (Manage ports RX queues.)
108+
--socket (Path to the control plane API socket.)
109+
-s (Path to the control plane API socket.)
110+
stats (Manage stack statistics.)
111+
--trace-commands (Print executed commands.)
112+
-x (Print executed commands.)
113+
~# ./build/br-cli stats reset
114+
~# ./build/br-cli graph dump
115+
digraph "br-0037" {
116+
rankdir=LR;
117+
node [margin=0.02 fontsize=11 fontname=sans];
118+
"ipv4_rewrite_ttl_exceeded" [color=darkorange];
119+
"ipv4_rewrite_no_next_hop" [color=darkorange];
120+
"ipv4_rewrite";
121+
"ipv4_rewrite" -> "eth_tx";
122+
"ipv4_rewrite" -> "ipv4_rewrite_no_next_hop";
123+
"ipv4_rewrite" -> "ipv4_rewrite_ttl_exceeded";
124+
"ipv4_lookup_bad_length" [color=darkorange];
125+
"ipv4_lookup_no_route" [color=darkorange];
126+
"ipv4_lookup_bad_checksum" [color=darkorange];
127+
"ipv4_lookup";
128+
"ipv4_lookup" -> "ipv4_rewrite";
129+
"ipv4_lookup" -> "ipv4_lookup_bad_checksum";
130+
"ipv4_lookup" -> "ipv4_lookup_no_route";
131+
"ipv4_lookup" -> "ipv4_lookup_bad_length";
132+
"eth_tx_error" [color=darkorange];
133+
"eth_tx";
134+
"eth_tx" -> "eth_tx_error";
135+
"eth_rx" [color=blue style=bold];
136+
"eth_rx" -> "eth_classify" [color=blue style=bold];
137+
"eth_classify_unknown_ptype" [color=darkorange];
138+
"eth_classify";
139+
"eth_classify" -> "eth_classify_unknown_ptype";
140+
"eth_classify" -> "ipv4_lookup";
141+
}
142+
~# ./build/br-cli graph stats
143+
NODE CALLS PACKETS PKTS/CALL CYCLES/CALL CYCLES/PKT
144+
eth_tx 449804 114771409 255.2 79044.8 309.8
145+
ipv4_rewrite 449804 114771409 255.2 14291.0 56.0
146+
ipv4_lookup 449804 114771409 255.2 11872.2 46.5
147+
eth_rx 857824 114771409 133.8 4452.6 33.3
148+
eth_classify 449804 114771409 255.2 1818.2 7.1
149+
```
150+
151+
## License
152+
153+
BSD 3 clause.
32154

33155
## TODO
34156

0 commit comments

Comments
 (0)