| blob | 3456e1e7ca1fbc78cd1733ab72263f24e826c00b |
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 -D <name>=<definition>, --define <name>=<definition>
69 Add macro definition for the C preprocessor to use it within bpf file. This
70 option is used in combination with the -p,--cpp option.
71 .PP
72 .SS -f <format>, --format <format>
73 Specify a different output format than the default that is netsniff-ng
74 compatible. The <format> specifier can be: C, netsniff-ng, xt_bpf, tcpdump.
75 .PP
76 .SS -b, --bypass
77 Bypass basic filter validation when emitting opcodes. This can be useful
78 for explicitly creating malformed BPF expressions for injecting
79 into the kernel, for example, for bug testing.
80 .PP
81 .SS -V, --verbose
82 Be more verbose and display some bpfc debugging information.
83 .PP
84 .SS -d, --dump
85 Dump all supported instructions to stdout.
86 .PP
87 .SS -v, --version
88 Show version information and exit.
89 .PP
90 .SS -h, --help
91 Show user help and exit.
92 .PP
93 .SH SYNTAX
94 .PP
95 The BPF architecture resp. register machine consists of the following
96 elements:
97 .PP
98 Element Description
99 .PP
100 A 32 bit wide accumulator
101 X 32 bit wide X register
102 M[] 16 x 32 bit wide misc registers aka \[lq]scratch
103 memory store\[rq], addressable from 0 to 15
104 .PP
105 A program, that is translated by bpfc into ''opcodes'' is an array that
106 consists of the following elements:
107 .PP
108 o:16, jt:8, jf:8, k:32
109 .PP
110 The element o is a 16 bit wide opcode that has a particular instruction
111 encoded, jt and jf are two 8 bit wide jump targets, one for condition
112 ''true'', one for condition ''false''. Last but not least the 32 bit wide
113 element k contains a miscellaneous argument that can be interpreted in
114 different ways depending on the given instruction resp. opcode.
115 .PP
116 The instruction set consists of load, store, branch, alu, miscellaneous
117 and return instructions that are also represented in bpfc syntax. This
118 table also includes bpfc's own extensions. All operations are based on
119 unsigned data structures:
120 .PP
121 Instruction Addressing mode Description
122 .PP
123 ld 1, 2, 3, 4, 10 Load word into A
124 ldi 4 Load word into A
125 ldh 1, 2 Load half-word into A
126 ldb 1, 2 Load byte into A
127 ldx 3, 4, 5, 10 Load word into X
128 ldxi 4 Load word into X
129 ldxb 5 Load byte into X
130 .PP
131 st 3 Copy A into M[]
132 stx 3 Copy X into M[]
133 .PP
134 jmp 6 Jump to label
135 ja 6 Jump to label
136 jeq 7, 8 Jump on k == A
137 jneq 8 Jump on k != A
138 jne 8 Jump on k != A
139 jlt 8 Jump on k < A
140 jle 8 Jump on k <= A
141 jgt 7, 8 Jump on k > A
142 jge 7, 8 Jump on k >= A
143 jset 7, 8 Jump on k & A
144 .PP
145 add 0, 4 A + <x>
146 sub 0, 4 A - <x>
147 mul 0, 4 A * <x>
148 div 0, 4 A / <x>
149 mod 0, 4 A % <x>
150 neg 0, 4 !A
151 and 0, 4 A & <x>
152 or 0, 4 A | <x>
153 xor 0, 4 A ^ <x>
154 lsh 0, 4 A << <x>
155 rsh 0, 4 A >> <x>
156 .PP
157 tax Copy A into X
158 txa Copy X into A
159 .PP
160 ret 4, 9 Return
161 .PP
162 Addressing mode Syntax Description
163 .PP
164 0 x/%x Register X
165 1 [k] BHW at byte offset k in the packet
166 2 [x + k] BHW at the offset X + k in the packet
167 3 M[k] Word at offset k in M[]
168 4 #k Literal value stored in k
169 5 4*([k]&0xf) Lower nibble * 4 at byte offset k in the packet
170 6 L Jump label L
171 7 #k,Lt,Lf Jump to Lt if true, otherwise jump to Lf
172 8 #k,Lt Jump to Lt if predicate is true
173 9 a/%a Accumulator A
174 10 extension BPF extension (see next table)
175 .PP
176 Extension (and alias) Description
177 .PP
178 #len, len, #pktlen, pktlen Length of packet (skb->len)
179 #pto, pto, #proto, proto Ethernet type field (skb->protocol)
180 #type, type Packet type (**) (skb->pkt_type)
181 #poff, poff Detected payload start offset
182 #ifx, ifx, #ifidx, ifidx Interface index (skb->dev->ifindex)
183 #nla, nla Netlink attribute of type X with offset A
184 #nlan, nlan Nested Netlink attribute of type X with offset A
185 #mark, mark Packet mark (skb->mark)
186 #que, que, #queue, queue, #Q, Q NIC queue index (skb->queue_mapping)
187 #hat, hat, #hatype, hatype NIC hardware type (**) (skb->dev->type)
188 #rxh, rxh, #rxhash, rxhash Receive hash (skb->rxhash)
189 #cpu, cpu Current CPU (raw_smp_processor_id())
190 #vlant, vlant, #vlan_tci, vlan_tci VLAN TCI value (vlan_tx_tag_get(skb))
191 #vlanp, vlanp VLAN present (vlan_tx_tag_present(skb))
192 .PP
193 Further extension details (**) Value
194 .PP
195 #type, type 0 - to us / host
196 1 - to all / broadcast
197 2 - to group / multicast
198 3 - to others (promiscuous mode)
199 4 - outgoing of any type
200 .PP
201 #hat, hat, #hatype, hatype 1 - Ethernet 10Mbps
202 8 - APPLEtalk
203 19 - ATM
204 24 - IEEE 1394 IPv4 - RFC 2734
205 32 - InfiniBand
206 768 - IPIP tunnel
207 769 - IP6IP6 tunnel
208 772 - Loopback device
209 778 - GRE over IP
210 783 - Linux-IrDA
211 801 - IEEE 802.11
212 802 - IEEE 802.11 + Prism2 header
213 803 - IEEE 802.11 + radiotap header
214 823 - GRE over IP6
215 824 - Netlink
216 [...] See include/uapi/linux/if_arp.h
217 .PP
218 Note that the majority of BPF extensions are available on Linux only.
219 .PP
220 There are two types of comments in bpfc source-files:
221 .PP
222 1. Multi-line C-style comments: /* put comment here */
223 2. Single-line ASM-style comments: ; put comment here
224 .PP
225 Used Abbreviations:
226 .PP
227 BHW: byte, half-word, or word
228 .PP
229 .SH SOURCE EXAMPLES
230 .PP
231 In this section, we give a couple of examples of bpfc source files, in other
232 words, some small example filter programs:
233 .PP
234 .SS Only return packet headers (truncate packets):
235 .PP
236 ld poff
237 ret a
238 .PP
239 .SS Only allow ARP packets:
240 .PP
241 ldh [12]
242 jne #0x806, drop
243 ret #-1
244 drop: ret #0
245 .PP
246 .SS Only allow IPv4 TCP packets:
247 .PP
248 ldh [12]
249 jne #0x800, drop
250 ldb [23]
251 jneq #6, drop
252 ret #-1
253 drop: ret #0
254 .PP
255 .SS Only allow IPv4 TCP SSH traffic:
256 .PP
257 ldh [12]
258 jne #0x800, drop
259 ldb [23]
260 jneq #6, drop
261 ldh [20]
262 jset #0x1fff, drop
263 ldxb 4 * ([14] & 0xf)
264 ldh [x + 14]
265 jeq #0x16, pass
266 ldh [x + 16]
267 jne #0x16, drop
268 pass: ret #-1
269 drop: ret #0
270 .PP
271 .SS A loadable x86_64 seccomp-BPF filter to allow a given set of syscalls:
272 .PP
273 ld [4] /* offsetof(struct seccomp_data, arch) */
274 jne #0xc000003e, bad /* AUDIT_ARCH_X86_64 */
275 ld [0] /* offsetof(struct seccomp_data, nr) */
276 jeq #15, good /* __NR_rt_sigreturn */
277 jeq #231, good /* __NR_exit_group */
278 jeq #60, good /* __NR_exit */
279 jeq #0, good /* __NR_read */
280 jeq #1, good /* __NR_write */
281 jeq #5, good /* __NR_fstat */
282 jeq #9, good /* __NR_mmap */
283 jeq #14, good /* __NR_rt_sigprocmask */
284 jeq #13, good /* __NR_rt_sigaction */
285 jeq #35, good /* __NR_nanosleep */
286 bad: ret #0 /* SECCOMP_RET_KILL */
287 good: ret #0x7fff0000 /* SECCOMP_RET_ALLOW */
288 .PP
289 .SS Allow any (hardware accelerated) VLAN:
290 .PP
291 ld vlanp
292 jeq #0, drop
293 ret #-1
294 drop: ret #0
295 .PP
296 .SS Only allow traffic for (hardware accelerated) VLAN 10:
297 .PP
298 ld vlant
299 jneq #10, drop
300 ret #-1
301 drop: ret #0
302 .PP
303 .SS More pedantic check for the above VLAN example:
304 .PP
305 ld vlanp
306 jeq #0, drop
307 ld vlant
308 jneq #10, drop
309 ret #-1
310 drop: ret #0
311 .PP
312 .SS Filter rtnetlink messages
313 .PP
314 ldh #proto /* A = skb->protocol */
316 jneq #0, skip /* check for NETLINK_ROUTE */
317 ldb [4] /* A = nlmsg_type */
319 jneq #0x10, skip /* check type == RTNL_NEWLINK */
320 ldx #16 /* X = offset(ifinfomsg) */
322 ldb [x + 4] /* offset(ifi_index) */
323 jneq #0x3, skip /* check ifindex == 3 */
325 ld #32 /* A = len(nlmsghdr) + len(ifinfomsg), payload offset */
326 ldx #16 /* X = IFLA_OPERSTATE */
327 ld #nla /* A = offset(IFLA_OPERSTATE) */
328 jeq #0, skip
329 tax
330 ldb [x + 4] /* A = value(IFLA_OPERSTATE) */
331 jneq #0x6, skip /* check oper state is UP */
333 ret #-1
334 skip: ret #0
335 .PP
336 .SH USAGE EXAMPLE
337 .PP
338 .SS bpfc fubar
339 Compile the source file ''fubar'' into BPF opcodes. Opcodes will be
340 directed to stdout.
341 .PP
342 .SS bpfc -f xt_bpf -b -p -i fubar, resp. iptables -A INPUT -m bpf --bytecode "`bpfc -f xt_bpf -i fubar`" -j LOG
343 Compile the source file ''fubar'' into BPF opcodes, bypass basic filter
344 validation and emit opcodes in netfilter's xt_bpf readable format. Note
345 that the source file ''fubar'' is first passed to the C preprocessor for
346 textual replacements before handing over to the bpfc compiler.
347 .PP
348 .SS bpfc -
349 Read bpfc instruction from stdin and emit opcodes to stdout.
350 .PP
351 .SS bpfc foo > bar, resp. netsniff-ng -f bar ...
352 Compile filter instructions from file foo and redirect bpfc's output into
353 the file bar, that can then be read by netsniff-ng(8) through option \-f.
354 .PP
355 .SS bpfc -f tcpdump -i fubar
356 Output opcodes from source file fubar in the same behavior as ''tcpdump \-ddd''.
357 .PP
358 .SH LEGAL
359 bpfc is licensed under the GNU GPL version 2.0.
360 .PP
361 .SH HISTORY
362 .B bpfc
363 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
364 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
365 Borkmann <dborkma@tik.ee.ethz.ch>.
366 .PP
367 .SH SEE ALSO
368 .BR netsniff-ng (8),
369 .BR trafgen (8),
370 .BR mausezahn (8),
371 .BR ifpps (8),
372 .BR flowtop (8),
373 .BR astraceroute (8),
374 .BR curvetun (8)
375 .PP
376 .SH AUTHOR
377 Manpage was written by Daniel Borkmann.
378 .PP
379 .SH COLOPHON
380 This page is part of the Linux netsniff-ng toolkit project. A description of the project,
381 and information about reporting bugs, can be found at http://netsniff-ng.org/.