-
Notifications
You must be signed in to change notification settings - Fork 30
/
Copy pathREADME.txt
290 lines (230 loc) · 11.6 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
README
======
Packet Bricks is a Linux/FreeBSD daemon that is capable of receiving
and distributing ingress traffic to userland applications. Its main
responsibilities may include (i) load-balancing, (ii) duplicating
and/or (iii) filtering ingress traffic across all registered
applications. The distribution is flow-aware (i.e. packets of one
connection will always end up in the same application). At the moment,
packet-bricks uses netmap packet I/O framework for receiving packets.
It employs netmap pipes to forward packets to end host applications.
Before running packet-bricks, please make sure that you have
installed the netmap driver successfully. You should first try
running the sample pkt-gen binary (that is available in the netmap's
examples/) directory to see if the driver is operational. The netmap
module is continuously being updated with enhancements and bug fixes
(as is common for all open source tools including packet bricks). Before
using packet bricks, please make sure that you have downloaded and
updated the netmap kernel module with its latest version. The netmap
authors suggest building the netmap module into the kernel for
performance reasons. You can download the latest netmap driver from
the following link: https://github.com/luigirizzo/netmap.
The following guide provides a walkthrough of the
/usr/local/etc/bricks-scripts/startup-*.lua files and also explains
what this system is capable of.
_________
| |
| APP 1 |
|_________|
eth3}0 /
______________/
|
| _________
| eth3}1 | |
| ____________| APP 2 |
| | |_________|
1/10 Gbps link | |
|||||||||||||| ------->eth3{PACKET-BRICKS} _________
| | eth3}2 | |
| |____________| APP 3 |
| |_________|
|
| eth3}3
|_____________
\
\_________
| |
| APP 4 |
|_________|
Figure 1: A sample packet-bricks instance redirecting ingress
traffic from eth3 to 4 userland applications using
a LoadBalancer brick
User can start the program by running the following command:
# bricks [-f startup_script_file]
To start the program as a daemon, either type:
# bricks -d [-f startup_script_file]
OR
# bricks-server [-f startup_script_file]
If the system is executed as a non-daemon, it opens a
LUA-based shell. Type the following command to print the help menu:
_________________________________________________________________
bricks> BRICKS.help()
BRICKS Commands:
help()
print_status()
show_stats()
shutdown()
Available subsystems within BRICKS have their own help() methods:
pkteng
_________________________________________________________________
Alternatively, the user can run `bricks-shell` to access the
interface shell to communicate with daemonized bricks-server.
You can hit Ctrl+D to exit the bricks-shell client. To gracefully
turn the daemon off, the user may enter the following command to
exit the program:
_________________________________________________________________
bricks> BRICKS.shutdown()
Goodbye!
_________________________________________________________________
Packet bricks relies on netmap pipes to distribute traffic across
multiple applications. Some OSes have netmap pipes disabled by
default. Please use the following command to enable netmap pipes
(if needed) in a packet bricks session:
_________________________________________________________________
bricks> utilObj:enable_nmpipes()
_________________________________________________________________
In packet-bricks, the most important component is the pkteng module.
It manages the reception and distribution of ingress traffic coming
through an interface. Once instantiated, the pkteng module spawns a
thread that starts the packet reception process. After running
packet-bricks again, use the following command to create a pkteng
instance, pe:
_________________________________________________________________
bricks> pe = PktEngine.new("e0")
_________________________________________________________________
The "e0" field is internally used by packet-bricks as pkteng's ID.
You can delete the pkteng instance by running the following command:
_________________________________________________________________
bricks> pe:delete()
_________________________________________________________________
The pkteng instance can be instantiated with the possibility of
affinitizing the engine thread to an arbitrary cpu core id:
_________________________________________________________________
bricks> pe = PktEngine.new("e0", 1024, 1)
_________________________________________________________________
The last parameter affinitizes the module to CPU 1 once the engine
thread starts reading packets.
In packet-bricks, ingress traffic can be manipulated with packet
engine constructs called "bricks". Currently packet-bricks has
the following built-in bricks that are available for use:
1- LoadBalancer: Brick that may be used to split flow-wise
traffic to different applications using netmap
pipes.
2- Duplicator: Brick that may be used to duplicate traffic
across each registered netmap pipe.
3- Merge: Brick that may be used to combine traffic between
2 or more netmap pipes.
4- PcapReader: Brick that may be used to read ingress traffic
from a pcap dump file.
5- PcapWriter: Brick that may be used to redirect ingress
traffic to a pcap dump file.
6- Filter: Brick that can be used for traffic shaping. It
accepts remote requests over the network using
Bro's broker library. The message bundle is created
using the NetControl protocol. This can only be used
when Packet bricks is compiled with broker plugin.
A packet engine can be linked to any of these bricks with
any combination/configuration of user's liking. Please see the
scripts/ example directory to see how bricks can be used to
run variants of such packet engines.
The succeeding text uses a simple load balancing brick
("LoadBalancer") to show how packet-bricks runs. A freshly
instantiated packet engine can be used to link the LoadBalancer
as:
_________________________________________________________________
bricks> lb = Brick.new("LoadBalancer", 2)
bricks> lb:connect_input("eth3")
bricks> lb:connect_output("eth3{0", "eth3{1",
"eth3{2", "eth3{3", "eth2")
bricks> pe:link(lb)
_________________________________________________________________
This binds pkteng pe with LoadBalancer brick and asks the system
to read ingress packets from eth3 and split them flow-wise based on
the 2-tuple (src & dst IP addresses) metadata of the packet header.
The "lb:connect_output(...)" command creates four netmap-specific
pipes named "netmap:eth3{x" where 0 <= x < 4 and an egress
interface named "eth2". The traffic is evenly split between all five
channels based on the 2 tuple header as previously mentioned.
Userland applications can now use packet-bricks to get their fair
share of ingress traffic. The brick is finally linked with the
packet engine.
One can always unlink the brick by running the following command:
_________________________________________________________________
bricks> pe:unlink()
_________________________________________________________________
If the user is content with the packet engine setup, he/she can
bypass unlinking and start the engine:
_________________________________________________________________
bricks> pe:start()
_________________________________________________________________
The engine will start sniffing for packets from the interface
promiscuously. You can use the following command to get the run-time
packets-related statistics from the engine:
_________________________________________________________________
bricks> pe.show_stats()
_________________________________________________________________
Sample applications (e.g. netmap's pkt-gen) can read ingress
traffic from packet-bricks using following command line arguments:
_________________________________________________________________
$ sudo ./pkt-gen -i netmap:eth3}0 -f rx &
$ sudo ./pkt-gen -i netmap:eth3}1 -f rx &
$ sudo ./pkt-gen -i netmap:eth3}2 -f rx &
$ sudo ./pkt-gen -i netmap:eth3}3 -f rx &
_________________________________________________________________
Please note that you cannot unlink a brick from the pkteng
while the engine is running. To stop the engine, please run the
following command:
_________________________________________________________________
bricks> pe:stop()
_________________________________________________________________
For user's convenience, the packet-bricks package comes with a
reference LUA script file: please see scripts/startup-*.lua files for
details. You can also use the following command to load the script
file in packet-bricks at startup:
# bricks -f /usr/local/etc/bricks-scripts/startup-one-thread.lua, OR
# bricks-server -f /usr/local/etc/bricks-scripts/startup-one-thread.lua
The user is recommended to skim through the script file. It is
heavily documented. The scripts directory also contains code for
running a 4-threaded version of the pkteng (see
/usr/local/etc/bricks-scripts/startup-multi-threads.lua).
=======================================================================
~:NEW:~
We have created 2 new tools that can quickly set up (i) load-balancer,
and (ii) duplicator.
i) The user can use bricks-load-balance to split traffic for a given
interface. Example usage:
$ bricks-load-balance eth3 4
The example above will split traffic on netmap-enabled interface, eth3,
to 4 netmap pipe channels named eth3}0, eth3}1, eth3}2 and eth3}3.
ii) The user can use bricks-duplicate to duplicate ingress traffic
for the given interface. Example usage:
$ bricks-duplicate eth3 4
The example above will duplicate traffic on netmap-enabled interface,
eth3, to 4 netmap pipe channels named eth3}0, eth3}1, eth3}2 and eth3}3.
~:Connecting with broker:~
Packet bricks can be configured to accept remote requests via the
broker communication module. Users can perform simple traffic shaping
tasks by issuing requests to specific Filter bricks. Packet bricks uses
NetControl protocol for this purpose. A user can refer to each Filter
via the output netmap pipe name of the brick.
=======================================================================
-:TROUBLESHOOTING:-
Packet bricks is still in development stages. While we welcome
feedback, we suggest that you refer to the following pointers before
contacting the authors for bug reports.
1- Please install the required libraries mentioned in INSTALL file.
As the system is still under active development, the program may
exhibit unexpected behavior if libraries are not installed.
2- The README file in the netmap/ directory contains pointers
on how to enhance packet I/O performance. We suggest you to follow
their guide for extracting maximum performance out of packet
bricks as well.
3- Some users have reported erroneous behavior when executing
tcpdump with netmap-libpcap patch. tcpdump has compatibility
constraints with libpcap. Please refer to
http://www.tcpdump.org/#old-releases to verify which tcpdump
version should be linked with the latest netmap-libpcap
release. At the time of writing, the latest netmap-libpcap
version is 1.6.0. The compatible tcpdump version for this
release is 4.6.0.
4. Please report further bugs to: ajamshed@icsi.berkeley.edu