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