bpfc.8

   1 .\" netsniff-ng - the packet sniffing beast
   2 .\" Copyright 2013 Daniel Borkmann.
   3 .\" Subject to the GPL, version 2.
   4
   5 .TH BPFC 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
   6 .SH NAME
   7 bpfc \- a Berkeley Packet Filter assembler/compiler
   8
   9 .SH SYNOPSIS
  10
  11 \fB bpfc\fR { [\fIoptions\fR] | [\fIsource-file\fR] }
  12
  13 .SH DESCRIPTION
  14
  15 bpfc is a small Berkeley Packet Filter assembler/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 e.g. 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 like the communication
  27 between user and kernel space.
  28
  29 By 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 for many people as tcpdump-like filters.
  32
  33 However, quite often, it is useful to bypass that compiler and write
  34 optimized code that couldn't be produced by the pcap(3) compiler, was
  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 of good
  38 use to verify JIT compiler behaviour or to find possible bugs that need
  39 to be fixed.
  40
  41 bpfc is implemented with the help of flex(1) and bison(1), tokenizes the
  42 source file in a first stage and parses it's 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
  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 generic BPF JIT image disassembler can be found in the kernel
  53 source tree under: tools/net/bpf_jit_disasm.c
  54
  55 .SH OPTIONS
  56
  57 .SS -i <source-file/->, --input <source-file/->
  58 Read BPF assembly instruction from an input file or from stdin.
  59
  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
  64 .SS -b, --bypass
  65 Bypass basic filter validation when emitting opcodes. This can be useful
  66 for explicitly creating malformed BPF expressions that should be injected
  67 into the kernel, e.g. for bug testing.
  68
  69 .SS -V, --verbose
  70 Be more verbose and display some bpfc debugging information.
  71
  72 .SS -d, --dump
  73 Dump all supported instructions to stdout.
  74
  75 .SS -v, --version
  76 Show versioning information.
  77
  78 .SS -h, --help
  79 Show user help.
  80
  81 .SH SYNTAX
  82
  83 The BPF architecture resp. register machine consists of the following
  84 elements:
  85
  86     Element          Description
  87
  88     A                32 bit wide accumulator
  89     X                32 bit wide X register
  90     M[]              16 x 32 bit wide misc registers aka ``scratch
  91 memory store'', addressable from 0 to 15
  92
  93 A program, that is translated by bpfc into ``opcodes'' is an array that
  94 consists of the following elements:
  95
  96     o:16, jt:8, jf:8, k:32
  97
  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
 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 own bpfc extensions. All operations are based on
 107 unsigned data structures:
 108
 109    Instruction      Addressing mode      Description
 110
 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
 119    st               3                    Copy A into M[]
 120    stx              3                    Copy X into M[]
 121
 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
 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
 145    tax                                   Copy A into X
 146    txa                                   Copy X into A
 147
 148    ret              4, 9                 Return
 149
 150    Addressing mode  Syntax               Description
 151
 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
 164    Extension (and alias)                 Description
 165
 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
 181    Further extension details (**)        Value
 182
 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
 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
 205 Note that the majority of BPF extensions are available on Linux only.
 206
 207 There are two types of comments in bpfc source-files:
 208
 209   1. Multi-line C-style comments:        /* put comment here */
 210   2. Single-line ASM-style comments:     ;  put comment here
 211
 212 Used Abbreviations:
 213
 214   BHW: byte, half-word, or word
 215
 216 .SH SOURCE EXAMPLES
 217
 218 In this section, we give a couple of examples for bpfc source-files, in other
 219 words, some small example filter programs:
 220
 221 .SS Only return packet headers (truncate packets):
 222
 223   ld poff
 224   ret a
 225
 226 .SS Only allow ARP packets:
 227
 228   ldh [12]
 229   jne #0x806, drop
 230   ret #-1
 231   drop: ret #0
 232
 233 .SS Only allow IPv4 TCP packets:
 234
 235   ldh [12]
 236   jne #0x800, drop
 237   ldb [23]
 238   jneq #6, drop
 239   ret #-1
 240   drop: ret #0
 241
 242 .SS Only allow IPv4 TCP, SSH traffic:
 243
 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
 258 .SS Allow any (hardware accelerated) VLAN:
 259
 260   ld vlanp
 261   jeq #0, drop
 262   ret #-1
 263   drop: ret #0
 264
 265 .SS Only allow traffic for (hardware accelerated) VLAN 10:
 266
 267   ld vlant
 268   jneq #10, drop
 269   ret #-1
 270   drop: ret #0
 271
 272 .SS More pedantic check for the above VLAN example:
 273
 274   ld vlanp
 275   jeq #0, drop
 276   ld vlant
 277   jneq #10, drop
 278   ret #-1
 279   drop: ret #0
 280
 281 .SH USAGE EXAMPLE
 282
 283 .SS bpfc fubar
 284 Compile the source file ``fubar'' into BPF opcodes. Opcodes will be
 285 directed to stdout.
 286
 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
 291 .SS bpfc -
 292 Read bpfc instruction from stdin and emit opcodes to stdout.
 293
 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
 298 .SS bpfc -f tcpdump -i fubar
 299 Output opcodes from source file fubar in the same behaviour as ``tcpdump -ddd''.
 300
 301 .SH LEGAL
 302 bpfc is licensed under the GNU GPL version 2.0.
 303
 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
 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
 319 .SH AUTHOR
 320 Manpage was written by Daniel Borkmann.