 |
Click this button to go to the index for this section. |
bpf(7)
NAME
bpf - BSD Packet Filter Extensions
DESCRIPTION
The BSD Packet Filter (BPF) is similar to the DIGITAL UNIX Packet Filter
facility (see packetfilter(7)), but provides a slightly different
programming interface. The BPF Extensions to the DIGITAL 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 efficient
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 support 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 supports indirection.
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.
BIOCGBLEN (u_int)
Returns the required buffer length for reads on bpf files. [Provided
for compatibility only; on DIGITAL UNIX this may be ignored.]
BIOCSBLEN (u_int)
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 DIGITAL UNIX this command has no effect, and reads may specify
any buffer size large enough to hold at least one packet.]
BIOCGDLT (u_int)
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>.
BIOCPROMISC
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 listening on a given interface, on some operating systems a
listener that opened its interface non-promiscuously may receive
packets promiscuously. This problem can be remedied with an
appropriate filter. [This problem does not occur on DIGITAL 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 listening
promiscuously are closed.
BIOCFLUSH
Flushes the buffer of incoming packets, and resets the statistics that
are returned by BIOCGSTATS.
BIOCGETIF (struct ifreq)
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.
BIOCSETIF (struct ifreq)
Sets the hardware interface associate with the file. This command must
be performed 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.
BIOCSRTIMEOUT, BIOCGRTIMEOUT (struct timeval)
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 initialized to zero by open(2), indicating no timeout.
[See the description of EIOCSRTIMEOUT in packetfilter(7) for more
details on timeout values.]
BIOCGSTATS (struct bpf_stat)
Returns the following structure of packet statistics:
struct bpf_stat {
u_int bs_recv;
u_int bs_drop;
};
The fields are:
bs_recv
The number of packets received by the descriptor since opened or
reset (including any buffered since the last read call).
bs_drop
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).
BIOCIMMEDIATE (u_int)
Enable or disable ``immediate mode'', based on the truth value of the
argument. When immediate mode is enabled, reads return immediately
upon packet reception. Otherwise, a read will block until either the
kernel buffer becomes full or a timeout occurs. The default for a new
file is off. [On DIGITAL 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.]
BIOCSETF (struct bpf_program)
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 language.
In addition, the SIOCGIFADDR ioctl may be applied to packet filter file
descriptors.
BPF HEADER
By default, the DIGITAL 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 EIOCMBIS
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 packetfilter(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:
bh_tstamp
The time at which the packet was processed by the packet filter.
bh_caplen
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 DIGITAL UNIX systems, the truncation amount specified by
the filter is ignored, and the one specified by EIOCTRUNCATE (see
packetfilter(7)) is used.]
bh_datalen
The length of the packet off the wire. This value is independent of
the truncation amount specified by the filter.
bh_hdrlen
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 alignment-sensitive
architectures and improves performance on many other architectures. The
packet filter insures that the bpf_hdr and the network 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_ALIGNMENT 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 forwardly
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 operator 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 memory 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.
BPF_LD
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:
BPF_LD+BPF_W+BPF_ABS
A <- P[k:4]
BPF_LD+BPF_H+BPF_ABS
A <- P[k:2]
BPF_LD+BPF_B+BPF_ABS
A <- P[k:1]
BPF_LD+BPF_W+BPF_IND
A <- P[X+k:4]
BPF_LD+BPF_H+BPF_IND
A <- P[X+k:2]
BPF_LD+BPF_B+BPF_IND
A <- P[X+k:1]
BPF_LD+BPF_W+BPF_LEN
A <- len
BPF_LD+BPF_IMM
A <- k
BPF_LD+BPF_MEM
A <- M[k]
BPF_LDX
These instructions load a value into the index register. Note that the
addressing modes are more restricted than those of the accumulator
loads, but they include BPF_MSH, a hack for efficiently loading the IP
header length.
BPF_LDX+BPF_W+BPF_IMM
X <- k
BPF_LDX+BPF_W+BPF_MEM
X <- M[k]
BPF_LDX+BPF_W+BPF_LEN
X <- len
BPF_LDX+BPF_B+BPF_MSH
X <- 4*(P[k:1]&0xf)
BPF_ST
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.
BPF_ST
M[k] <- A
BPF_STX
This instruction stores the index register in the scratch memory store.
BPF_STX
M[k] <- X
BPF_ALU
The alu instructions perform operations 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).
BPF_ALU+BPF_ADD+BPF_K
A <- A + k
BPF_ALU+BPF_SUB+BPF_K
A <- A - k
BPF_ALU+BPF_MUL+BPF_K
A <- A * k
BPF_ALU+BPF_DIV+BPF_K
A <- A / k
BPF_ALU+BPF_AND+BPF_K
A <- A & k
BPF_ALU+BPF_OR+BPF_K
A <- A | k
BPF_ALU+BPF_LSH+BPF_K
A <- A << k
BPF_ALU+BPF_RSH+BPF_K
A <- A >> k
BPF_ALU+BPF_ADD+BPF_X
A <- A + X
BPF_ALU+BPF_SUB+BPF_X
A <- A - X
BPF_ALU+BPF_MUL+BPF_X
A <- A * X
BPF_ALU+BPF_DIV+BPF_X
A <- A / X
BPF_ALU+BPF_AND+BPF_X
A <- A & X
BPF_ALU+BPF_OR+BPF_X
A <- A | X
BPF_ALU+BPF_LSH+BPF_X
A <- A << X
BPF_ALU+BPF_RSH+BPF_X
A <- A >> X
BPF_ALU+BPF_NEG
A <- -A
BPF_JMP
The jump instructions alter flow of control. Conditional 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.
BPF_JMP+BPF_JA
pc += k
BPF_JMP+BPF_JGT+BPF_K
pc += (A > k) ? jt : jf
BPF_JMP+BPF_JGE+BPF_K
pc += (A >= k) ? jt : jf
BPF_JMP+BPF_JEQ+BPF_K
pc += (A == k) ? jt : jf
BPF_JMP+BPF_JSET+BPF_K
pc += (A & k) ? jt : jf
BPF_JMP+BPF_JGT+BPF_X
pc += (A > X) ? jt : jf
BPF_JMP+BPF_JGE+BPF_X
pc += (A >= X) ? jt : jf
BPF_JMP+BPF_JEQ+BPF_X
pc += (A == X) ? jt : jf
BPF_JMP+BPF_JSET+BPF_X
pc += (A & X) ? jt : jf
BPF_RET
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).
BPF_RET+BPF_A
accept A bytes
BPF_RET+BPF_K
accept k bytes
[On DIGITAL UNIX systems, the entire packet is accepted if and only if the
return value is non-zero; the truncation amount is controlled using
EIOCTRUNCATE.]
BPF_MISC
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.
BPF_MISC+BPF_TAX
X <- A
BPF_MISC+BPF_TXA
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)
RESTRICTIONS
If BPF headers are used, data link protocols with variable length headers
are not properly supported.
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),
};
INCOMPATIBILITIES
The BSD Packet Filter Extensions for the DIGITAL 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:
Opening packet filter file descriptors
In BPF, pseudo-devices are named /dev/bpf0, /dev/bpf1, and so on.
Applications open them directly. On DIGITAL UNIX systems, pseudo-
devices are named /dev/pf/pfilt0, /dev/pf/pfilt1, and so on.
Obtaining BPF headers
In BPF, the BPF header is always prepended to packets. On DIGITAL UNIX
this behavior must be specifically requested by setting the ENBPFHDR
mode bit.
Specifying packet truncation
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 DIGITAL 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, DIGITAL UNIX returns the entire packet, which
means that programs not using EIOCTRUNCATE will probably operate
correctly, but perhaps not efficiently.
COPYALL mode
In BPF, packet filter applications see packets to or from their own
host. On DIGITAL UNIX packet filter applications do not see packets to
or from their own host, unless the ENCOPYALL mode bit is set.
Buffering control
In BPF, the number of queued packets is limited to what will fit in one
page (after truncation). On DIGITAL 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.
RELATED INFORMATION
Commands: pfconfig(8) pfstat(1)
Files: packetfilter(7)