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