flowtop: Refactor walking for each flow node by presenter
[netsniff-ng.git] / bpfc.8
blob1cde888bb322684bf05fdcce1d0679367b0168ca
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
101 A program, that is translated by bpfc into ''opcodes'' is an array that
102 consists of the following elements:
104     o:16, jt:8, jf:8, k:32
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.
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:
117    Instruction      Addressing mode      Description
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
127    st               3                    Copy A into M[]
128    stx              3                    Copy X into M[]
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
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>
153    tax                                   Copy A into X
154    txa                                   Copy X into A
156    ret              4, 9                 Return
158    Addressing mode  Syntax               Description
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)
172    Extension (and alias)                 Description
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))
189    Further extension details (**)        Value
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
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
214 Note that the majority of BPF extensions are available on Linux only.
216 There are two types of comments in bpfc source-files:
218   1. Multi-line C-style comments:        /* put comment here */
219   2. Single-line ASM-style comments:     ;  put comment here
221 Used Abbreviations:
223   BHW: byte, half-word, or word
225 .SH SOURCE EXAMPLES
227 In this section, we give a couple of examples of bpfc source files, in other
228 words, some small example filter programs:
230 .SS Only return packet headers (truncate packets):
232   ld poff
233   ret a
235 .SS Only allow ARP packets:
237   ldh [12]
238   jne #0x806, drop
239   ret #-1
240   drop: ret #0
242 .SS Only allow IPv4 TCP packets:
244   ldh [12]
245   jne #0x800, drop
246   ldb [23]
247   jneq #6, drop
248   ret #-1
249   drop: ret #0
251 .SS Only allow IPv4 TCP SSH traffic:
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
267 .SS A loadable x86_64 seccomp-BPF filter to allow a given set of syscalls:
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 */
285 .SS Allow any (hardware accelerated) VLAN:
287   ld vlanp
288   jeq #0, drop
289   ret #-1
290   drop: ret #0
292 .SS Only allow traffic for (hardware accelerated) VLAN 10:
294   ld vlant
295   jneq #10, drop
296   ret #-1
297   drop: ret #0
299 .SS More pedantic check for the above VLAN example:
301   ld vlanp
302   jeq #0, drop
303   ld vlant
304   jneq #10, drop
305   ret #-1
306   drop: ret #0
308 .SH USAGE EXAMPLE
310 .SS bpfc fubar
311 Compile the source file ''fubar'' into BPF opcodes. Opcodes will be
312 directed to stdout.
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.
320 .SS bpfc -
321 Read bpfc instruction from stdin and emit opcodes to stdout.
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.
327 .SS bpfc -f tcpdump -i fubar
328 Output opcodes from source file fubar in the same behavior as ''tcpdump \-ddd''.
330 .SH LEGAL
331 bpfc is licensed under the GNU GPL version 2.0.
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>.
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)
348 .SH AUTHOR
349 Manpage was written by Daniel Borkmann.
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/.