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