bpfc man page on RedHat

Man page or keyword search:  
man Server   29550 pages
apropos Keyword Search (all sections)
Output format
RedHat logo
[printable version]

BPFC(8)			      netsniff-ng toolkit		       BPFC(8)

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,  com‐
       posed  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 communi‐
       cation between user and kernel space like system call sand-boxing.

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

       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  reposi‐
       tory.

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 def‐
       initions 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, tcp‐
       dump.

   -b, --bypass
       Bypass  basic filter validation when emitting opcodes. This can be use‐
       ful 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  mem‐
       ory 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
       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			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  off‐
       set 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			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->pro‐
       tocol)
	  #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_proces‐
       sor_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 Bork‐
       mann.  It  is  currently	 maintained  by	 Tobias Klauser <tklauser@dis‐
       tanz.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 descrip‐
       tion of the project, and information about reporting bugs, can be found
       at http://netsniff-ng.org/.

Linux				 03 March 2013			       BPFC(8)
[top]

List of man pages available for RedHat

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net