Provided by: netsniff-ng_0.6.0-1build2_i386 bug

NAME

       bpfc - a Berkeley Packet Filter assembler and compiler

SYNOPSIS

       bpfc { [options] | [source-file] }

DESCRIPTION

       bpfc  is a small Berkeley Packet Filter assembler and compiler which is
       able to translate BPF assembler-like mnemonics into a numerical  or  C-
       like  format,  that  can be read by tools such as netsniff-ng, iptables
       (xt_bpf) and many others. BPF is the one and  only  upstream  filtering
       construct  that is used in combination with packet(7) sockets, but also
       seccomp-BPF for system call sandboxing.

       The Linux kernel and also BSD kernels implement "virtual machine"  like
       constructs  and JIT compilers that mimic a small register-based machine
       in BPF architecture and execute  filter  code  that  is,  for  example,
       composed by bpfc on a data buffer that is given by network packets. The
       purpose of this is to shift computation in time, so that the kernel can
       drop  or  truncate incoming packets as early as possible without having
       to push them to user space for further analysis first.  Meanwhile,  BPF
       constructs  also  find  application  in  other  areas  such  as  in the
       communication between user and kernel  space  like  system  call  sand-
       boxing.

       At  the  time  of  writing  this man page, the only other available BPF
       compiler is part of the pcap(3) library and accessible through a  high-
       level filter language that might be familiar to many people as tcpdump-
       like filters.

       However, it is quite often useful to bypass  that  compiler  and  write
       optimized  code  that cannot be produced by the pcap(3) compiler, or is
       wrongly optimized, or is defective on purpose in order  to  debug  test
       kernel  code.  Also,  a reason to use bpfc could be to try out some new
       BPF extensions that are not supported by other compilers.  Furthermore,
       bpfc  can be useful to verify JIT compiler behavior or to find possible
       bugs that need to be fixed.

       bpfc is implemented with the help of flex(1)  and  bison(1),  tokenizes
       the  source file in the first stage and parses its content into an AST.
       In two code generation stages it emits target opcodes. bpfc furthermore
       supports  Linux  kernel BPF extensions. More about that can be found in
       the syntax section.

       The Linux kernel  BPF  JIT  compiler  is  automatically  turned  on  if
       detected  by  netsniff-ng.  However,  it can also be manually turned on
       through the command ''echo  "1"  >  /proc/sys/net/core/bpf_jit_enable''
       (normal       working       mode)       or       ''echo      "2"      >
       /proc/sys/net/core/bpf_jit_enable'' (debug mode where  emitted  opcodes
       of  the  image are printed to the kernel log). An architecture agnostic
       BPF JIT image disassembler can be found in the kernel source tree under
       ''tools/net/bpf_jit_disasm.c''    or   within   the   netsniff-ng   Git
       repository.

OPTIONS

   -i <source-file/->, --input <source-file/->
       Read BPF assembly instruction from an input file or from stdin.

   -p, --cpp
       Pass the bpf program through the C preprocessor before  reading  it  in
       bpfc.  This  allows  #define  and  #include directives (e.g. to include
       definitions from system headers) to be used in the bpf program.

   -f <format>, --format <format>
       Specify a different output format than the default that is  netsniff-ng
       compatible.  The  <format>  specifier  can  be: C, netsniff-ng, xt_bpf,
       tcpdump.

   -b, --bypass
       Bypass basic filter validation  when  emitting  opcodes.  This  can  be
       useful  for explicitly creating malformed BPF expressions for injecting
       into the kernel, for example, for bug testing.

   -V, --verbose
       Be more verbose and display some bpfc debugging information.

   -d, --dump
       Dump all supported instructions to stdout.

   -v, --version
       Show version information and exit.

   -h, --help
       Show user help and exit.

SYNTAX

       The BPF architecture resp. register machine consists of  the  following
       elements:

           Element          Description

           A                32 bit wide accumulator
           X                32 bit wide X register
           M[]               16  x  32  bit  wide  misc registers aka “scratch
       memory store”, addressable from 0 to 15

       A program, that is translated by bpfc into ''opcodes'' is an array that
       consists of the following elements:

           o:16, jt:8, jf:8, k:32

       The element o is a 16 bit wide opcode that has a particular instruction
       encoded, jt and jf are two 8 bit wide jump targets, one for condition
        ''true'', one for condition ''false''. Last but not least the  32  bit
       wide   element   k  contains  a  miscellaneous  argument  that  can  be
       interpreted in different ways depending on the given instruction  resp.
       opcode.

       The instruction set consists of load, store, branch, alu, miscellaneous
       and return instructions that are also represented in bpfc syntax.  This
       table  also includes bpfc's own extensions. All operations are based on
       unsigned data structures:

          Instruction      Addressing mode      Description

          ld               1, 2, 3, 4, 10       Load word into A
          ldi              4                    Load word into A
          ldh              1, 2                 Load half-word into A
          ldb              1, 2                 Load byte into A
          ldx              3, 4, 5, 10          Load word into X
          ldxi             4                    Load word into X
          ldxb             5                    Load byte into X

          st               3                    Copy A into M[]
          stx              3                    Copy X into M[]

          jmp              6                    Jump to label
          ja               6                    Jump to label
          jeq              7, 8                 Jump on k == A
          jneq             8                    Jump on k != A
          jne              8                    Jump on k != A
          jlt              8                    Jump on k < A
          jle              8                    Jump on k <= A
          jgt              7, 8                 Jump on k > A
          jge              7, 8                 Jump on k >= A
          jset             7, 8                 Jump on k & A

          add              0, 4                 A + <x>
          sub              0, 4                 A - <x>
          mul              0, 4                 A * <x>
          div              0, 4                 A / <x>
          mod              0, 4                 A % <x>
          neg              0, 4                 !A
          and              0, 4                 A & <x>
          or               0, 4                 A | <x>
          xor              0, 4                 A ^ <x>
          lsh              0, 4                 A << <x>
          rsh              0, 4                 A >> <x>

          tax                                   Copy A into X
          txa                                   Copy X into A

          ret              4, 9                 Return

          Addressing mode  Syntax               Description

           0               x/%x                 Register X
           1               [k]                  BHW at byte offset  k  in  the
       packet
           2               [x + k]              BHW at the offset X + k in the
       packet
           3               M[k]                 Word at offset k in M[]
           4               #k                   Literal value stored in k
           5               4*([k]&0xf)           Lower  nibble  *  4  at  byte
       offset k in the packet
           6               L                    Jump label L
           7                #k,Lt,Lf             Jump to Lt if true, otherwise
       jump to Lf
           8               #k,Lt                Jump to  Lt  if  predicate  is
       true
           9               a/%a                 Accumulator A
          10               extension            BPF extension (see next table)

          Extension (and alias)                 Description

          #len, len, #pktlen, pktlen            Length of packet (skb->len)
          #pto,   pto,   #proto,   proto                Ethernet   type  field
       (skb->protocol)
          #type,    type                              Packet     type     (**)
       (skb->pkt_type)
          #poff, poff                           Detected payload start offset
          #ifx,    ifx,    #ifidx,    ifidx                 Interface    index
       (skb->dev->ifindex)
          #nla, nla                             Netlink attribute  of  type  X
       with offset A
          #nlan,  nlan                            Nested  Netlink attribute of
       type X with offset A
          #mark, mark                           Packet mark (skb->mark)
          #que,  que,   #queue,   queue,   #Q,   Q         NIC   queue   index
       (skb->queue_mapping)
          #hat,   hat,  #hatype,  hatype             NIC  hardware  type  (**)
       (skb->dev->type)
          #rxh, rxh, #rxhash, rxhash            Receive hash (skb->rxhash)
          #cpu,       cpu                                   Current        CPU
       (raw_smp_processor_id())
          #vlant,    vlant,    #vlan_tci,    vlan_tci       VLAN   TCI   value
       (vlan_tx_tag_get(skb))
          #vlanp,       vlanp                               VLAN       present
       (vlan_tx_tag_present(skb))

          Further extension details (**)        Value

          #type, type                           0 - to us / host
                                                1 - to all / broadcast
                                                2 - to group / multicast
                                                3  -  to  others  (promiscuous
       mode)
                                                4 - outgoing of any type

          #hat, hat, #hatype, hatype            1 - Ethernet 10Mbps
                                                8 - APPLEtalk
                                               19 - ATM
                                               24 - IEEE 1394 IPv4 - RFC 2734
                                               32 - InfiniBand
                                              768 - IPIP tunnel
                                              769 - IP6IP6 tunnel
                                              772 - Loopback device
                                              778 - GRE over IP
                                              783 - Linux-IrDA
                                              801 - IEEE 802.11
                                              802  -  IEEE  802.11  +   Prism2
       header
                                              803  -  IEEE  802.11  + radiotap
       header
                                              823 - GRE over IP6
                                              824 - Netlink
                                              [...]                        See
       include/uapi/linux/if_arp.h

       Note that the majority of BPF extensions are available on Linux only.

       There are two types of comments in bpfc source-files:

         1. Multi-line C-style comments:        /* put comment here */
         2. Single-line ASM-style comments:     ;  put comment here

       Used Abbreviations:

         BHW: byte, half-word, or word

SOURCE EXAMPLES

       In  this section, we give a couple of examples of bpfc source files, in
       other words, some small example filter programs:

   Only return packet headers (truncate packets):
         ld poff
         ret a

   Only allow ARP packets:
         ldh [12]
         jne #0x806, drop
         ret #-1
         drop: ret #0

   Only allow IPv4 TCP packets:
         ldh [12]
         jne #0x800, drop
         ldb [23]
         jneq #6, drop
         ret #-1
         drop: ret #0

   Only allow IPv4 TCP SSH traffic:
         ldh [12]
         jne #0x800, drop
         ldb [23]
         jneq #6, drop
         ldh [20]
         jset #0x1fff, drop
         ldxb 4 * ([14] & 0xf)
         ldh [x + 14]
         jeq #0x16, pass
         ldh [x + 16]
         jne #0x16, drop
         pass: ret #-1
         drop: ret #0

   A loadable x86_64 seccomp-BPF filter to allow a given set of syscalls:
         ld [4]                  /* offsetof(struct seccomp_data, arch) */
         jne #0xc000003e, bad    /* AUDIT_ARCH_X86_64 */
         ld [0]                  /* offsetof(struct seccomp_data, nr) */
         jeq #15, good           /* __NR_rt_sigreturn */
         jeq #231, good          /* __NR_exit_group */
         jeq #60, good           /* __NR_exit */
         jeq #0, good            /* __NR_read */
         jeq #1, good            /* __NR_write */
         jeq #5, good            /* __NR_fstat */
         jeq #9, good            /* __NR_mmap */
         jeq #14, good           /* __NR_rt_sigprocmask */
         jeq #13, good           /* __NR_rt_sigaction */
         jeq #35, good           /* __NR_nanosleep */
         bad: ret #0             /* SECCOMP_RET_KILL */
         good: ret #0x7fff0000   /* SECCOMP_RET_ALLOW */

   Allow any (hardware accelerated) VLAN:
         ld vlanp
         jeq #0, drop
         ret #-1
         drop: ret #0

   Only allow traffic for (hardware accelerated) VLAN 10:
         ld vlant
         jneq #10, drop
         ret #-1
         drop: ret #0

   More pedantic check for the above VLAN example:
         ld vlanp
         jeq #0, drop
         ld vlant
         jneq #10, drop
         ret #-1
         drop: ret #0

USAGE EXAMPLE

   bpfc fubar
       Compile the source file ''fubar'' into BPF  opcodes.  Opcodes  will  be
       directed to stdout.

   bpfc  -f  xt_bpf  -b -p -i fubar, resp. iptables -A INPUT -m bpf --bytecode
       `bpfc -f xt_bpf -i fubar` -j LOG
       Compile the source file ''fubar'' into BPF opcodes, bypass basic filter
       validation and emit opcodes in netfilter's xt_bpf readable format. Note
       that the source file ''fubar'' is first passed to  the  C  preprocessor
       for textual replacements before handing over to the bpfc compiler.

   bpfc -
       Read bpfc instruction from stdin and emit opcodes to stdout.

   bpfc foo > bar, resp. netsniff-ng -f bar ...
       Compile  filter  instructions  from file foo and redirect bpfc's output
       into the file bar, that can then  be  read  by  netsniff-ng(8)  through
       option -f.

   bpfc -f tcpdump -i fubar
       Output opcodes from source file fubar in the same behavior as ''tcpdump
       -ddd''.

LEGAL

       bpfc is licensed under the GNU GPL version 2.0.

HISTORY

       bpfc was originally written  for  the  netsniff-ng  toolkit  by  Daniel
       Borkmann.    It    is    currently   maintained   by   Tobias   Klauser
       <tklauser@distanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.

SEE ALSO

       netsniff-ng(8),   trafgen(8),   mausezahn(8),   ifpps(8),   flowtop(8),
       astraceroute(8), curvetun(8)

AUTHOR

       Manpage was written by Daniel Borkmann.

COLOPHON

       This  page  is  part  of  the  Linux  netsniff-ng  toolkit  project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://netsniff-ng.org/.