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