man/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 -v, --version
  73 Show versioning information.
  74
  75 .SS -h, --help
  76 Show user help.
  77
  78 .SH SYNTAX
  79
  80 .SH SOURCE EXAMPLES
  81
  82 .SH USAGE EXAMPLE
  83
  84 .SS bpfc fubar
  85 Compile the source file ``fubar'' into BPF opcodes. Opcodes will be
  86 directed to stdout.
  87
  88 .SS bpfc -f xt_bpf -b -i fubar, resp. iptables -A INPUT -m bpf --bytecode "`bpfc -f xt_bpf -i fubar`" -j LOG
  89 Compile the source file ``fubar'' into BPF opcodes, bypass basic filter
  90 validation and emit opcodes in netfilter's xt_bpf readable format.
  91
  92 .SS bpfc -
  93 Read bpfc instruction from stdin and emit opcodes to stdout.
  94
  95 .SS bpfc foo > bar, resp. netsniff-ng -f bar ...
  96 Compile filter instructions from file foo and redirect bpfc's output into
  97 the file bar, that can then be read by netsniff-ng(8) through option -f.
  98
  99 .SS bpfc -f tcpdump -i fubar
 100 Output opcodes from source file fubar in the same behaviour as ``tcpdump -ddd''.
 101
 102 .SH LEGAL
 103 bpfc is licensed under the GNU GPL version 2.0.
 104
 105 .SH HISTORY
 106 .B bpfc
 107 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
 108 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
 109 Borkmann <dborkma@tik.ee.ethz.ch>.
 110
 111 .SH SEE ALSO
 112 .BR netsniff-ng (8),
 113 .BR trafgen (8),
 114 .BR mausezahn (8),
 115 .BR ifpps (8),
 116 .BR flowtop (8),
 117 .BR astraceroute (8),
 118 .BR curvetun (8)
 119
 120 .SH AUTHOR
 121 Manpage was written by Daniel Borkmann.