BPFC(8)

✨ NAME ✨

okay so bestie, this is BPFC(8) — the manual page for bpfc, which is a Berkeley Packet Filter assembler and compiler. It's part of the netsniff-ng toolkit, and it is literally here to translate your BPF vibes into something the kernel can read. 💖

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

okay so bpfc is a small Berkeley Packet Filter assembler and compiler, and it is able to translate BPF assembler-like mnemonics into a numerical or C-like format. That format 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. slay. 🦋

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. it's giving efficiency. Meanwhile, BPF constructs also find application in other areas such as in the communication between user and kernel space like system call sandboxing. 💅

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. iykyk. 👑

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. periodt. 🔥

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. main character energy fr fr. ✨

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. vibe check passed. 🎀

---

🎀 OPTIONS 🎀

okay bestie, here are the flags. each one is a little lewk. 💅

• -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.
• -D <name>=<definition>, --define <name>=<definition> — Add macro definition for the C preprocessor to use it within bpf file. This option is used in combination with the -p/--cpp option.
• -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:

• 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:

• ld — addressing mode: 1, 2, 3, 4, 10 — Load word into A
• ldi — addressing mode: 4 — Load word into A
• ldh — addressing mode: 1, 2 — Load half-word into A
• ldb — addressing mode: 1, 2 — Load byte into A
• ldx — addressing mode: 3, 4, 5, 10 — Load word into X
• ldxi — addressing mode: 4 — Load word into X
• ldxb — addressing mode: 5 — Load byte into X
• st — addressing mode: 3 — Copy A into M[]
• stx — addressing mode: 3 — Copy X into M[]
• jmp — addressing mode: 6 — Jump to label
• ja — addressing mode: 6 — Jump to label
• jeq — addressing mode: 7, 8 — Jump on k == A
• jneq — addressing mode: 8 — Jump on k != A
• jne — addressing mode: 8 — Jump on k != A
• jlt — addressing mode: 8 — Jump on k < A
• jle — addressing mode: 8 — Jump on k <= A
• jgt — addressing mode: 7, 8 — Jump on k > A
• jge — addressing mode: 7, 8 — Jump on k >= A
• jset — addressing mode: 7, 8 — Jump on k & A
• add — addressing mode: 0, 4 — A + <x>
• sub — addressing mode: 0, 4 — A - <x>
• mul — addressing mode: 0, 4 — A * <x>
• div — addressing mode: 0, 4 — A / <x>
• mod — addressing mode: 0, 4 — A % <x>
• neg — addressing mode: 0, 4 — !A
• and — addressing mode: 0, 4 — A & <x>
• or — addressing mode: 0, 4 — A | <x>
• xor — addressing mode: 0, 4 — A ^ <x>
• lsh — addressing mode: 0, 4 — A << <x>
• rsh — addressing mode: 0, 4 — A >> <x>
• tax — Copy A into X
• txa — Copy X into A
• ret — addressing mode: 4, 9 — Return

And the addressing modes are giving:

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

The extensions (and aliases) are:

• #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 (**):

For #type, type:

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

For #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 ✨

okay so bestie, in this section we're serving up a couple of examples of bpfc source files — in other words, some small example filter programs. let's get into it:

just return packet headers (truncate packets) — it's giving minimalism:

ld poff
ret a

only allow ARP packets, no cap:

ldh [12]
jne #0x806, drop
ret #-1
drop: ret #0

only allow IPv4 TCP packets, periodt:

ldh [12]
jne #0x800, drop
ldb [23]
jneq #6, drop
ret #-1
drop: ret #0

only allow IPv4 TCP SSH traffic, because we're picky like that:

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 that allows a given set of syscalls, highkey iconic:

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, slay:

ld vlanp
jeq #0, drop
ret #-1
drop: ret #0

only allow traffic for (hardware accelerated) VLAN 10, specifically:

ld vlant
jneq #10, drop
ret #-1
drop: ret #0

a more pedantic check for the above VLAN example, because we love attention to detail:

ld vlanp
jeq #0, drop
ld vlant
jneq #10, drop
ret #-1
drop: ret #0

filter rtnetlink messages, iykyk:

ldh #proto       /* A = skb->protocol */

jneq #0, skip    /* check for NETLINK_ROUTE */
ldb [4]          /* A = nlmsg_type */

jneq #0x10, skip /* check type == RTNL_NEWLINK */
ldx #16          /* X = offset(ifinfomsg) */

ldb [x + 4]      /* offset(ifi_index) */
jneq #0x3, skip  /* check ifindex == 3 */

ld #32           /* A = len(nlmsghdr) + len(ifinfomsg), payload offset
*/
ldx #16          /* X = IFLA_OPERSTATE */
ld #nla          /* A = offset(IFLA_OPERSTATE) */
jeq #0, skip
tax
ldb [x + 4]      /* A = value(IFLA_OPERSTATE) */
jneq #0x6, skip  /* check oper state is UP */

ret #-1
skip: ret #0

---

✨ USAGE EXAMPLE ✨

okay so here's how you actually use this thing, bestie:

bpfc fubar

compile the source file fubar into BPF opcodes. opcodes will be directed to stdout. easy.

bpfc -f xt_bpf -b -p -i fubar, resp. iptables -A INPUT -m bpf --bytecode
`bpfc -f xt_bpf -i fubar` -j LOG

compile fubar into BPF opcodes, skip the basic filter validation, and emit opcodes in netfilter's xt_bpf readable format. also note: fubar gets passed to the C preprocessor first for textual replacements before it goes to the bpfc compiler. 💅

cat fubar | bpfc -

read bpfc instructions from stdin and emit opcodes to stdout. simple.

bpfc foo > bar && netsniff-ng -f bar ...

compile filter instructions from file foo and redirect bpfc's output into file bar, which can then be read by netsniff-ng(8) using option -f.

bpfc -f tcpdump -i fubar

output opcodes from source file fubar with the same behavior as tcpdump -ddd. iykyk.

---

✨ LEGAL ✨

bpfc is licensed under the GNU GPL version 2.0. periodt. 💅

---

✨ 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>. we stan. 👑

---

✨ 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/.

---

💖 that's a wrap on BPFC(8) from Linux, dated 03 March 2013. stay slaying! 💅