bpf(7)bpf(7)NAMEbpf - BSD Packet Filter Extensions
DESCRIPTION
The BSD Packet Filter (BPF) is similar to the Tru64 UNIX Packet Filter
facility (see packetfilter(7)), but provides a slightly different pro‐
gramming interface. The BPF Extensions to the Tru64 UNIX packet filter
provide nearly complete source-level compatibility with BPF.
The reader should be familiar with the packetfilter(7) reference page
before reading this reference page.
The most useful feature of the BPF Extensions is that packet filter
programs may be written in the BPF filter language, which is more effi‐
cient and more flexible than the original packet filter language. The
original language uses a stack-machine model, deals only in 16-bit
quantities, has minimal control flow primitives. It also does not sup‐
port indirect loads, which are necessary for parsing variable-length
headers. The BPF language uses a register-machine model, supports 1,
2, and 4 byte data, has a rich set of control flow primitives, and sup‐
ports indirection.
RESTRICTIONS
If BPF headers are used, data link protocols with variable length head‐
ers are not properly supported.
IOCTLS
The BPF Extensions consist of a set of ioctl commands that may be
applied to a packetfilter(7) file descriptor. The command codes below
are defined in <net/bpf.h>. All commands require these header files:
#include <sys/types.h> #include <sys/time.h> #include
<sys/ioctl.h> #include <net/bpf.h>
Additionally, BIOCGETIF and BIOCSETIF require <net/if.h>.
For the following commands, the third argument to the ioctl(2) system
call should be a pointer to the type indicated. Returns the required
buffer length for reads on bpf files. [Provided for compatibility only;
on Tru64 UNIX this may be ignored.] Sets the buffer length for reads
on bpf files. If the requested buffer size cannot be accommodated, the
closest allowable size will be set and returned in the argument. A read
call will result in EIO if it is passed a buffer that is not this size.
[Provided for compatibility only; on Tru64 UNIX this command has no
effect, and reads may specify any buffer size large enough to hold at
least one packet.] Returns the type of the data link layer underlying
the attached interface. EINVAL is returned if no interface has been
specified. The device types are defined in <net/bpf.h>. Forces the
interface into promiscuous mode. All packets, not just those destined
for the local host, are processed. Since more than one file can be lis‐
tening on a given interface, on some operating systems a listener that
opened its interface non-promiscuously may receive packets promiscu‐
ously. This problem can be remedied with an appropriate filter. [This
problem does not occur on Tru64 UNIX systems, but by assuming that it
might happen you will make your programs more portable.]
The interface remains in promiscuous mode until all files lis‐
tening promiscuously are closed. Flushes the buffer of incoming
packets, and resets the statistics that are returned by
BIOCGSTATS. Returns the name of the hardware interface that
file is listening on. The name is returned in the if_name field
of ifr. All other fields are undefined. Sets the hardware
interface associate with the file. This command must be per‐
formed before any packets can be read. The device is indicated
by name using the if_name field of the ifreq. Additionally,
performs the actions of BIOCFLUSH. Set or get the read timeout
parameter. The timeval specifies the length of time to wait
before timing out on a read request. This parameter is initial‐
ized to zero by open(2), indicating no timeout. [See the
description of EIOCSRTIMEOUT in packetfilter(7) for more details
on timeout values.] Returns the following structure of packet
statistics: struct bpf_stat {
u_int bs_recv;
u_int bs_drop; };
The fields are: The number of packets received by the descriptor
since opened or reset (including any buffered since the last
read call). The number of packets which were accepted by the
filter but dropped by the kernel because of buffer overflows
(i.e., because the application's reads are not keeping up with
the packet traffic). Enable or disable ``immediate mode'',
based on the truth value of the argument. When immediate mode is
enabled, reads return immediately upon packet reception. Other‐
wise, a read will block until either the kernel buffer becomes
full or a timeout occurs. The default for a new file is off. [On
Tru64 UNIX systems, this command has no effect. ``Immediate
mode'' is always in effect; a read will never block if there is
a received packet available.] Sets the filter program used by
the kernel to discard uninteresting packets. An array of
instructions and its length is passed in using the following
structure: struct bpf_program {
int bf_len;
struct bpf_insn *bf_insns; };
The filter program is pointed to by the bf_insns field while its
length in units of `struct bpf_insn' is given by the bf_len
field. Also, the actions of BIOCFLUSH are performed.
See section FILTER MACHINE for an explanation of the filter lan‐
guage.
In addition, the SIOCGIFADDR ioctl may be applied to packet fil‐
ter file descriptors.
BPF HEADER
By default, the Tru64 UNIX Packet Filter does not prepend a header to
each packet, while the BSD Packet Filter does. To request that the BPF
header be prepended to each packet returned by read(2), use the EIOCM‐
BIS ioctl command to set the ENBPFHDR mode bit (see packetfilter(7) for
details on the use of EIOCMBIS). If the ENBPFHDR and ENTSTAMP mode bits
are simultaneously set, the ENBPFHDR takes precedence. If the ENBPFHDR
mode bit is set, batch mode (see the description of ENBATCH in packet‐
filter(7)) is enabled, and the following structure is prepended to each
packet returned by read(2): struct bpf_hdr {
struct timeval bh_tstamp;
u_int bh_caplen;
u_int bh_datalen;
u_short bh_hdrlen; };
The fields, whose values are stored in host byte order, and are: The
time at which the packet was processed by the packet filter. The
length of the captured portion of the packet. This is the minimum of
the truncation amount specified by the filter and the length of the
packet. [On Tru64 UNIX systems, the truncation amount specified by the
filter is ignored, and the one specified by EIOCTRUNCATE (see packet‐
filter(7)) is used.] The length of the packet off the wire. This value
is independent of the truncation amount specified by the filter. The
length of the BPF header, which may not be equal to sizeof(struct
bpf_hdr).
The bh_hdrlen field exists to account for padding between the header
and the link level protocol. The purpose here is to guarantee proper
alignment of the packet data structures, which is required on align‐
ment-sensitive architectures and improves performance on many other
architectures. The packet filter insures that the bpf_hdr and the net‐
work layer header will be word-aligned. Suitable precautions must be
taken when accessing the link layer protocol fields on alignment
restricted machines. (This isn't a problem on an Ethernet, since the
type field is a short falling on an even offset, and the addresses are
probably accessed in a bytewise fashion).
Additionally, individual packets are padded so that each BPF header
starts on a word boundary. This requires that an application has some
knowledge of how to get from packet to packet. The macro BPF_WORDALIGN
is defined in <net/bpf.h> to facilitate this process. It rounds up its
argument to the nearest word aligned value (where a word is BPF_ALIGN‐
MENT bytes wide).
For example, if `p' points to the start of a packet (i.e., the start of
the prepended BPF header), this expression will advance it to the next
packet (BPF header): p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen +
p->bh_caplen)
For the alignment mechanisms to work properly, the buffer passed to
read(2) must itself be word aligned. malloc(3) will always return an
aligned buffer.
FILTER MACHINE
A filter program is an array of instructions, with all branches for‐
wardly directed, terminated by a return instruction. Each instruction
performs some action on the pseudo-machine state, which consists of an
accumulator, index register, scratch memory store, and implicit program
counter.
The following structure defines the instruction format: struct bpf_insn
{
u_short code;
u_char jt;
u_char jf;
int k; };
The k field is used in different ways by different instructions, and
the jt and jf fields are used as offsets by the branch instructions.
The opcodes are encoded in a semi-hierarchical fashion. There are
eight classes of instructions: BPF_LD, BPF_LDX, BPF_ST, BPF_STX,
BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC. Various other mode and opera‐
tor bits are or'd with the class bits to give the actual instructions.
The classes and modes are defined in <net/bpf.h>.
Below is given the semantics for each defined BPF instruction. We use
the convention that A is the accumulator, X is the index register, P[]
packet data, and M[] scratch memory store. P[i:n] gives the data at
byte offset ``i'' in the packet, interpreted as a word (n=4), unsigned
halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the
scratch memory store, which is only addressed in word units. The mem‐
ory store is indexed from 0 to BPF_MEMWORDS-1. k, jt, and jf are the
corresponding fields in the instruction definition. ``len'' refers to
the length of the packet. These instructions copy a value into the
accumulator. The type of the source operand is specified by an
``addressing mode'' and can be a constant (BPF_IMM), packet data at a
fixed offset (BPF_ABS), packet data at a variable offset (BPF_IND), the
packet length (BPF_LEN), or a word in the scratch memory store
(BPF_MEM). For BPF_IND and BPF_ABS, the data size must be specified as
a word (BPF_W), halfword (BPF_H), or byte (BPF_B). The semantics of all
the recognized BPF_LD instructions followings: A <- P[k:4] A <- P[k:2]
A <- P[k:1] A <- P[X+k:4] A <- P[X+k:2] A <- P[X+k:1] A <- len A <- k A
<- M[k] These instructions load a value into the index register. Note
that the addressing modes are more restricted than those of the accumu‐
lator loads, but they include BPF_MSH, a hack for efficiently loading
the IP header length. X <- k X <- M[k] X <- len X <- 4*(P[k:1]&0xf)
This instruction stores the accumulator into the scratch memory. We do
not need an addressing mode since there is only one possibility for the
destination. M[k] <- A This instruction stores the index register in
the scratch memory store. M[k] <- X The alu instructions perform oper‐
ations between the accumulator and index register or constant, and
store the result back in the accumulator. For binary operations, a
source mode is required (BPF_K or BPF_X). A <- A + k A <- A - k A <- A
* k A <- A / k A <- A & k A <- A | k A <- A << k A <- A >> k A <- A + X
A <- A - X A <- A * X A <- A / X A <- A & X A <- A | X A <- A << X A <-
A >> X A <- -A The jump instructions alter flow of control. Condi‐
tional jumps compare the accumulator against a constant (BPF_K) or the
index register (BPF_X). If the result is true (or non-zero), the true
branch is taken, otherwise the false branch is taken. Jump offsets are
encoded in 8 bits so the longest jump is 256 instructions. However, the
jump always (BPF_JA) opcode uses the 32 bit k field as the offset,
allowing arbitrarily distant destinations. All conditionals use
unsigned comparison conventions. pc += k pc += (A > k) ? jt : jf pc +=
(A >= k) ? jt : jf pc += (A == k) ? jt : jf pc += (A & k) ? jt : jf pc
+= (A > X) ? jt : jf pc += (A >= X) ? jt : jf pc += (A == X) ? jt : jf
pc += (A & X) ? jt : jf The return instructions terminate the filter
program and specify the amount of packet to accept (i.e., they return
the truncation amount). A return value of zero indicates that the
packet should be ignored. The return value is either a constant (BPF_K)
or the accumulator (BPF_A). accept A bytes accept k bytes [On Tru64
UNIX systems, the entire packet is accepted if and only if the return
value is non-zero; the truncation amount is controlled using EIOCTRUN‐
CATE.] The miscellaneous category was created for anything that
doesn't fit into the above classes, and for any new instructions that
might need to be added. Currently, these are the register transfer
instructions that copy the index register to the accumulator or vice
versa. X <- A A <- X
The BPF interface provides the following macros to facilitate array
initializers: BPF_STMT(opcode, operand) BPF_JUMP(opcode, operand,
true_offset, false_offset)
INCOMPATIBILITIES
The BSD Packet Filter Extensions for the Tru64 UNIX Packet Filter are
intended to provide nearly complete source-level compatibility with the
BSD Packet Filter (BPF), but in some details this is not possible. To
summarize the significant differences: In BPF, pseudo-devices are named
/dev/bpf0, /dev/bpf1, and so on. Applications open them directly. On
Tru64 UNIX systems, pseudo-devices are named /dev/pf/pfilt0,
/dev/pf/pfilt1, and so on. In BPF, the BPF header is always prepended
to packets. On Tru64 UNIX this behavior must be specifically requested
by setting the ENBPFHDR mode bit. In BPF, the number of packet bytes
returned by the kernel is specified by the return value from the BPF
filter program. This can thus vary from packet to packet (since a BPF
filter program may have more than one return statement). On Tru64 UNIX
the size returned by a BPF filter program is ignored, and the number of
returned packet bytes is set using EIOCTRUNCATE. This means that it
cannot vary from packet to packet. By default, Tru64 UNIX returns the
entire packet, which means that programs not using EIOCTRUNCATE will
probably operate correctly, but perhaps not efficiently. In BPF,
packet filter applications see packets to or from their own host. On
Tru64 UNIX packet filter applications do not see packets to or from
their own host, unless the ENCOPYALL mode bit is set. In BPF, the num‐
ber of queued packets is limited to what will fit in one page (after
truncation). On Tru64 UNIX the limit on the number of queued packets
defaults to 2. This limit may be increased using EIOCSETW. Not doing
so may result in many lost packets.
EXAMPLES
The following filter is taken from the Reverse ARP Daemon. It accepts
only Reverse ARP requests. struct bpf_insn insns[] = {
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
sizeof(struct ether_header)),
BPF_STMT(BPF_RET+BPF_K, 0), };
This filter accepts only IP packets between host 128.3.112.15 and
128.3.112.35. struct bpf_insn insns[] = {
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 26),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
BPF_STMT(BPF_RET+BPF_K, 0), };
Finally, this filter returns only TCP finger packets. We must parse
the IP header to reach the TCP header. The BPF_JSET instruction checks
that the IP fragment offset is 0 so we are sure that we have a TCP
header. struct bpf_insn insns[] = {
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
BPF_STMT(BPF_RET+BPF_K, 0), };
SEE ALSO
Commands: pfconfig(8)pfstat(1)
Files: packetfilter(7)bpf(7)