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