1 .\" netsniff-ng - the packet sniffing beast
2 .\" Copyright 2013 Daniel Borkmann.
3 .\" Subject to the GPL, version 2.
5 .TH BPFC 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
7 bpfc \- a Berkeley Packet Filter assembler and compiler
11 \fB bpfc\fR { [\fIoptions\fR] | [\fIsource-file\fR] }
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.
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.
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
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
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
57 .SS -i <source-file/->, --input <source-file/->
58 Read BPF assembly instruction from an input file or from stdin.
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.
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.
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.
75 Be more verbose and display some bpfc debugging information.
78 Dump all supported instructions to stdout.
81 Show version information and exit.
84 Show user help and exit.
88 The BPF architecture resp. register machine consists of the following
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
98 A program, that is translated by bpfc into ''opcodes'' is an array that
99 consists of the following elements:
101 o:16, jt:8, jf:8, k:32
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.
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:
114 Instruction Addressing mode Description
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
125 stx 3 Copy X into M[]
129 jeq 7, 8 Jump on k == A
130 jneq 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
155 Addressing mode Syntax Description
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
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
167 10 extension BPF extension (see next table)
169 Extension (and alias) Description
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))
186 Further extension details (**) Value
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
194 #hat, hat, #hatype, hatype 1 - Ethernet 10Mbps
197 24 - IEEE 1394 IPv4 - RFC 2734
201 772 - Loopback device
205 802 - IEEE 802.11 + Prism2 header
206 803 - IEEE 802.11 + radiotap header
208 [...] See include/uapi/linux/if_arp.h
210 Note that the majority of BPF extensions are available on Linux only.
212 There are two types of comments in bpfc source-files:
214 1. Multi-line C-style comments: /* put comment here */
215 2. Single-line ASM-style comments: ; put comment here
219 BHW: byte, half-word, or word
223 In this section, we give a couple of examples of bpfc source files, in other
224 words, some small example filter programs:
226 .SS Only return packet headers (truncate packets):
231 .SS Only allow ARP packets:
238 .SS Only allow IPv4 TCP packets:
247 .SS Only allow IPv4 TCP SSH traffic:
255 ldxb 4 * ([14] & 0xf)
263 .SS Allow any (hardware accelerated) VLAN:
270 .SS Only allow traffic for (hardware accelerated) VLAN 10:
277 .SS More pedantic check for the above VLAN example:
289 Compile the source file ''fubar'' into BPF opcodes. Opcodes will be
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 replacments before handing over to the bpfc compiler.
299 Read bpfc instruction from stdin and emit opcodes to stdout.
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.
305 .SS bpfc -f tcpdump -i fubar
306 Output opcodes from source file fubar in the same behavior as ''tcpdump -ddd''.
309 bpfc is licensed under the GNU GPL version 2.0.
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>.
323 .BR astraceroute (8),
327 Manpage was written by Daniel Borkmann.