| blob | 2d235ac5c3a35e6784fb132618ad198fed6211c3 |
1 .\" netsniff-ng - the packet sniffing beast
2 .\" Copyright 2013 Daniel Borkmann.
3 .\" Subject to the GPL, version 2.
4 .PP
5 .TH BPFC 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
6 .SH NAME
7 bpfc \- a Berkeley Packet Filter assembler and compiler
8 .PP
9 .SH SYNOPSIS
10 .PP
11 \fB bpfc\fR { [\fIoptions\fR] | [\fIsource-file\fR] }
12 .PP
13 .SH DESCRIPTION
14 .PP
15 bpfc is a small Berkeley Packet Filter assembler and compiler which is able to
16 translate BPF assembler-like mnemonics into a numerical or C-like format,
17 that can be read by tools such as netsniff-ng, iptables (xt_bpf) and many
18 others. BPF is the one and only upstream filtering construct that is used
19 in combination with packet(7) sockets. The Linux kernel and also BSD kernels
20 implement "virtual machine" like constructs and JIT compilers that mimic
21 a small register-based machine in BPF architecture and execute filter code
22 that is, for example, composed by bpfc on a data buffer that is given by network
23 packets. The purpose of this is to shift computation in time, so that the
24 kernel can drop or truncate incoming packets as early as possible without
25 having to push them to user space for further analysis first. Meanwhile,
26 BPF constructs also find application in other areas such as in the
27 communication between user and kernel space like system call sand-boxing.
28 .PP
29 At the time of writing this man page, the only available BPF compiler is
30 part of the pcap(3) library and accessible through a high-level filter
31 language that might be familiar to many people as tcpdump-like filters.
32 .PP
33 However, it is quite often useful to bypass that compiler and write
34 optimized code that cannot be produced by the pcap(3) compiler, or is
35 wrongly optimized, or is defective on purpose in order to debug test kernel
36 code. Also, a reason to use bpfc could be to try out some new BPF extensions
37 that are not supported by other compilers. Furthermore, bpfc can be useful
38 to verify JIT compiler behavior or to find possible bugs that need
39 to be fixed.
40 .PP
41 bpfc is implemented with the help of flex(1) and bison(1), tokenizes the
42 source file in the first stage and parses its content into an AST. In two
43 code generation stages it emits target opcodes. bpfc furthermore supports
44 Linux kernel BPF extensions. More about that can be found in the syntax
45 section.
46 .PP
47 The Linux kernel BPF JIT compiler is automatically turned on if detected
48 by netsniff-ng. However, it can also be manually turned on through the
49 command ''echo "1" > /proc/sys/net/core/bpf_jit_enable'' (normal working
50 mode) or ''echo "2" > /proc/sys/net/core/bpf_jit_enable'' (debug mode
51 where emitted opcodes of the image are printed to the kernel log). An
52 architecture agnostic BPF JIT image disassembler can be found in the kernel
53 source tree under: tools/net/bpf_jit_disasm.c
54 .PP
55 .SH OPTIONS
56 .PP
57 .SS -i <source-file/->, --input <source-file/->
58 Read BPF assembly instruction from an input file or from stdin.
59 .PP
60 .SS -p, --cpp
61 Pass the bpf program through the C preprocessor before reading it in
62 bpfc. This allows #define and #include directives (e.g. to include
63 definitions from system headers) to be used in the bpf program.
64 .PP
65 .SS -f <format>, --format <format>
66 Specify a different output format than the default that is netsniff-ng
67 compatible. The <format> specifier can be: C, netsniff-ng, xt_bpf, tcpdump.
68 .PP
69 .SS -b, --bypass
70 Bypass basic filter validation when emitting opcodes. This can be useful
71 for explicitly creating malformed BPF expressions for injecting
72 into the kernel, for example, for bug testing.
73 .PP
74 .SS -V, --verbose
75 Be more verbose and display some bpfc debugging information.
76 .PP
77 .SS -d, --dump
78 Dump all supported instructions to stdout.
79 .PP
80 .SS -v, --version
81 Show version information and exit.
82 .PP
83 .SS -h, --help
84 Show user help and exit.
85 .PP
86 .SH SYNTAX
87 .PP
88 The BPF architecture resp. register machine consists of the following
89 elements:
90 .PP
91 Element Description
92 .PP
93 A 32 bit wide accumulator
94 X 32 bit wide X register
95 M[] 16 x 32 bit wide misc registers aka \[lq]scratch
96 memory store\[rq], addressable from 0 to 15
97 .PP
98 A program, that is translated by bpfc into ''opcodes'' is an array that
99 consists of the following elements:
100 .PP
101 o:16, jt:8, jf:8, k:32
102 .PP
103 The element o is a 16 bit wide opcode that has a particular instruction
104 encoded, jt and jf are two 8 bit wide jump targets, one for condition
105 ''true'', one for condition ''false''. Last but not least the 32 bit wide
106 element k contains a miscellaneous argument that can be interpreted in
107 different ways depending on the given instruction resp. opcode.
108 .PP
109 The instruction set consists of load, store, branch, alu, miscellaneous
110 and return instructions that are also represented in bpfc syntax. This
111 table also includes bpfc's own extensions. All operations are based on
112 unsigned data structures:
113 .PP
114 Instruction Addressing mode Description
115 .PP
116 ld 1, 2, 3, 4, 10 Load word into A
117 ldi 4 Load word into A
118 ldh 1, 2 Load half-word into A
119 ldb 1, 2 Load byte into A
120 ldx 3, 4, 5, 10 Load word into X
121 ldxi 4 Load word into X
122 ldxb 5 Load byte into X
123 .PP
124 st 3 Copy A into M[]
125 stx 3 Copy X into M[]
126 .PP
127 jmp 6 Jump to label
128 ja 6 Jump to label
129 jeq 7, 8 Jump on k == A
130 jneq 8 Jump on k != A
131 jne 8 Jump on k != A
132 jlt 8 Jump on k < A
133 jle 8 Jump on k <= A
134 jgt 7, 8 Jump on k > A
135 jge 7, 8 Jump on k >= A
136 jset 7, 8 Jump on k & A
137 .PP
138 add 0, 4 A + <x>
139 sub 0, 4 A - <x>
140 mul 0, 4 A * <x>
141 div 0, 4 A / <x>
142 mod 0, 4 A % <x>
143 neg 0, 4 !A
144 and 0, 4 A & <x>
145 or 0, 4 A | <x>
146 xor 0, 4 A ^ <x>
147 lsh 0, 4 A << <x>
148 rsh 0, 4 A >> <x>
149 .PP
150 tax Copy A into X
151 txa Copy X into A
152 .PP
153 ret 4, 9 Return
154 .PP
155 Addressing mode Syntax Description
156 .PP
157 0 x Register X
158 1 [k] BHW at byte offset k in the packet
159 2 [x + k] BHW at the offset X + k in the packet
160 3 M[k] Word at offset k in M[]
161 4 #k Literal value stored in k
162 5 4*([k]&0xf) Lower nibble * 4 at byte offset k in the packet
163 6 L Jump label L
164 7 #k,Lt,Lf Jump to Lt if true, otherwise jump to Lf
165 8 #k,Lt Jump to Lt if predicate is true
166 9 a Accumulator A
167 10 extension BPF extension (see next table)
168 .PP
169 Extension (and alias) Description
170 .PP
171 #len, len, #pktlen, pktlen Length of packet (skb->len)
172 #pto, pto, #proto, proto Ethernet type field (skb->protocol)
173 #type, type Packet type (**) (skb->pkt_type)
174 #poff, poff Detected payload start offset
175 #ifx, ifx, #ifidx, ifidx Interface index (skb->dev->ifindex)
176 #nla, nla Netlink attribute of type X with offset A
177 #nlan, nlan Nested Netlink attribute of type X with offset A
178 #mark, mark Packet mark (skb->mark)
179 #que, que, #queue, queue, #Q, Q NIC queue index (skb->queue_mapping)
180 #hat, hat, #hatype, hatype NIC hardware type (**) (skb->dev->type)
181 #rxh, rxh, #rxhash, rxhash Receive hash (skb->rxhash)
182 #cpu, cpu Current CPU (raw_smp_processor_id())
183 #vlant, vlant, #vlan_tci, vlan_tci VLAN TCI value (vlan_tx_tag_get(skb))
184 #vlanp, vlanp VLAN present (vlan_tx_tag_present(skb))
185 .PP
186 Further extension details (**) Value
187 .PP
188 #type, type 0 - to us / host
189 1 - to all / broadcast
190 2 - to group / multicast
191 3 - to others (promiscuous mode)
192 4 - outgoing of any type
193 .PP
194 #hat, hat, #hatype, hatype 1 - Ethernet 10Mbps
195 8 - APPLEtalk
196 19 - ATM
197 24 - IEEE 1394 IPv4 - RFC 2734
198 32 - InfiniBand
199 768 - IPIP tunnel
200 769 - IP6IP6 tunnel
201 772 - Loopback device
202 778 - GRE over IP
203 783 - Linux-IrDA
204 801 - IEEE 802.11
205 802 - IEEE 802.11 + Prism2 header
206 803 - IEEE 802.11 + radiotap header
207 823 - GRE over IP6
208 [...] See include/uapi/linux/if_arp.h
209 .PP
210 Note that the majority of BPF extensions are available on Linux only.
211 .PP
212 There are two types of comments in bpfc source-files:
213 .PP
214 1. Multi-line C-style comments: /* put comment here */
215 2. Single-line ASM-style comments: ; put comment here
216 .PP
217 Used Abbreviations:
218 .PP
219 BHW: byte, half-word, or word
220 .PP
221 .SH SOURCE EXAMPLES
222 .PP
223 In this section, we give a couple of examples of bpfc source files, in other
224 words, some small example filter programs:
225 .PP
226 .SS Only return packet headers (truncate packets):
227 .PP
228 ld poff
229 ret a
230 .PP
231 .SS Only allow ARP packets:
232 .PP
233 ldh [12]
234 jne #0x806, drop
235 ret #-1
236 drop: ret #0
237 .PP
238 .SS Only allow IPv4 TCP packets:
239 .PP
240 ldh [12]
241 jne #0x800, drop
242 ldb [23]
243 jneq #6, drop
244 ret #-1
245 drop: ret #0
246 .PP
247 .SS Only allow IPv4 TCP SSH traffic:
248 .PP
249 ldh [12]
250 jne #0x800, drop
251 ldb [23]
252 jneq #6, drop
253 ldh [20]
254 jset #0x1fff, drop
255 ldxb 4 * ([14] & 0xf)
256 ldh [x + 14]
257 jeq #0x16, pass
258 ldh [x + 16]
259 jne #0x16, drop
260 pass: ret #-1
261 drop: ret #0
262 .PP
263 .SS Allow any (hardware accelerated) VLAN:
264 .PP
265 ld vlanp
266 jeq #0, drop
267 ret #-1
268 drop: ret #0
269 .PP
270 .SS Only allow traffic for (hardware accelerated) VLAN 10:
271 .PP
272 ld vlant
273 jneq #10, drop
274 ret #-1
275 drop: ret #0
276 .PP
277 .SS More pedantic check for the above VLAN example:
278 .PP
279 ld vlanp
280 jeq #0, drop
281 ld vlant
282 jneq #10, drop
283 ret #-1
284 drop: ret #0
285 .PP
286 .SH USAGE EXAMPLE
287 .PP
288 .SS bpfc fubar
289 Compile the source file ''fubar'' into BPF opcodes. Opcodes will be
290 directed to stdout.
291 .PP
292 .SS bpfc -f xt_bpf -b -p -i fubar, resp. iptables -A INPUT -m bpf --bytecode "`bpfc -f xt_bpf -i fubar`" -j LOG
293 Compile the source file ''fubar'' into BPF opcodes, bypass basic filter
294 validation and emit opcodes in netfilter's xt_bpf readable format. Note
295 that the source file ''fubar'' is first passed to the C preprocessor for
296 textual replacements before handing over to the bpfc compiler.
297 .PP
298 .SS bpfc -
299 Read bpfc instruction from stdin and emit opcodes to stdout.
300 .PP
301 .SS bpfc foo > bar, resp. netsniff-ng -f bar ...
302 Compile filter instructions from file foo and redirect bpfc's output into
303 the file bar, that can then be read by netsniff-ng(8) through option \-f.
304 .PP
305 .SS bpfc -f tcpdump -i fubar
306 Output opcodes from source file fubar in the same behavior as ''tcpdump \-ddd''.
307 .PP
308 .SH LEGAL
309 bpfc is licensed under the GNU GPL version 2.0.
310 .PP
311 .SH HISTORY
312 .B bpfc
313 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
314 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
315 Borkmann <dborkma@tik.ee.ethz.ch>.
316 .PP
317 .SH SEE ALSO
318 .BR netsniff-ng (8),
319 .BR trafgen (8),
320 .BR mausezahn (8),
321 .BR ifpps (8),
322 .BR flowtop (8),
323 .BR astraceroute (8),
324 .BR curvetun (8)
325 .PP
326 .SH AUTHOR
327 Manpage was written by Daniel Borkmann.