New sentence, new line. Use more markup.
Bump date for previous.
This commit is contained in:
wiz
parent
915709d082
commit
e95cae6b93
|
|
@ -1,6 +1,6 @@
|
|||
.\" -*- nroff -*-
|
||||
.\"
|
||||
.\" $NetBSD: bpf.4,v 1.38 2006/08/04 23:22:30 martin Exp $
|
||||
.\" $NetBSD: bpf.4,v 1.39 2006/08/04 23:30:53 wiz Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1990, 1991, 1992, 1993, 1994
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
|
|
@ -24,7 +24,7 @@
|
|||
.\" This document is derived in part from the enet man page (enet.4)
|
||||
.\" distributed with 4.3BSD Unix.
|
||||
.\"
|
||||
.Dd February 4, 2006
|
||||
.Dd August 4, 2006
|
||||
.Dt BPF 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -69,7 +69,8 @@ Note that an individual packet larger than this size is necessarily
|
|||
truncated.
|
||||
.Pp
|
||||
The packet filter will support any link level protocol that has fixed length
|
||||
headers. Currently, only Ethernet, SLIP and PPP drivers have been
|
||||
headers.
|
||||
Currently, only Ethernet, SLIP and PPP drivers have been
|
||||
modified to interact with
|
||||
.Nm .
|
||||
.Pp
|
||||
|
|
@ -79,8 +80,8 @@ macros to extract multi-byte values.
|
|||
.Pp
|
||||
A packet can be sent out on the network by writing to a
|
||||
.Nm
|
||||
file descriptor. The writes are unbuffered, meaning only one
|
||||
packet can be processed per write.
|
||||
file descriptor.
|
||||
The writes are unbuffered, meaning only one packet can be processed per write.
|
||||
Currently, only writes to Ethernets and SLIP links are supported.
|
||||
.Sh IOCTLS
|
||||
The
|
||||
|
|
@ -113,12 +114,14 @@ files.
|
|||
.It Dv "BIOCSBLEN (u_int)"
|
||||
Sets the buffer length for reads on
|
||||
.Nm
|
||||
files. The buffer must be set before the file is attached to an interface
|
||||
with
|
||||
files.
|
||||
The buffer must be set before the file is attached to an interface with
|
||||
.Dv BIOCSETIF .
|
||||
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 EINVAL if it is passed a buffer that is not this size.
|
||||
A read call will result in
|
||||
.Er EINVAL
|
||||
if it is passed a buffer that is not this size.
|
||||
.It Dv BIOCGDLT (u_int)
|
||||
Returns the type of the data link layer underlying the attached interface.
|
||||
.Er EINVAL
|
||||
|
|
@ -143,7 +146,8 @@ field while its length in u_int is supplied to the
|
|||
.Va bfl_len
|
||||
field.
|
||||
.Er ENOMEM
|
||||
is returned if there is not enough buffer. The
|
||||
is returned if there is not enough buffer.
|
||||
The
|
||||
.Va bfl_len
|
||||
field is modified on return to indicate the actual length in u_int
|
||||
of the array returned.
|
||||
|
|
@ -164,8 +168,8 @@ 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,
|
||||
a listener that opened its interface non-promiscuously may receive
|
||||
packets promiscuously. This problem can be remedied with an
|
||||
appropriate filter.
|
||||
packets promiscuously.
|
||||
This problem can be remedied with an appropriate filter.
|
||||
.Pp
|
||||
The interface remains in promiscuous mode until all files listening
|
||||
promiscuously are closed.
|
||||
|
|
@ -179,8 +183,8 @@ The name is returned in the ifr_name field of
|
|||
.Fa ifr .
|
||||
All other fields are undefined.
|
||||
.It Dv BIOCSETIF (struct ifreq)
|
||||
Sets the hardware interface associate with the file. This
|
||||
command must be performed before any packets can be read.
|
||||
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
|
||||
.Dv ifr_name
|
||||
field of the
|
||||
|
|
@ -225,7 +229,8 @@ Enable or disable
|
|||
.Dq 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
|
||||
reception.
|
||||
Otherwise, a read will block until either the kernel buffer
|
||||
becomes full or a timeout occurs.
|
||||
This is useful for programs like
|
||||
.Xr rarpd 8 ,
|
||||
|
|
@ -233,8 +238,8 @@ which must respond to messages in real time.
|
|||
The default for a new file is off.
|
||||
.It Dv 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:
|
||||
packets.
|
||||
An array of instructions and its length is passed in using the following structure:
|
||||
.Bd -literal -offset indent
|
||||
struct bpf_program {
|
||||
u_int bf_len;
|
||||
|
|
@ -258,11 +263,12 @@ See section
|
|||
for an explanation of the filter language.
|
||||
.It Dv BIOCVERSION (struct bpf_version)
|
||||
Returns the major and minor version numbers of the filter language currently
|
||||
recognized by the kernel. Before installing a filter, applications must check
|
||||
that the current version is compatible with the running kernel. Version
|
||||
numbers are compatible if the major numbers match and the application minor
|
||||
is less than or equal to the kernel minor. The kernel version number is
|
||||
returned in the following structure:
|
||||
recognized by the kernel.
|
||||
Before installing a filter, applications must check
|
||||
that the current version is compatible with the running kernel.
|
||||
Version numbers are compatible if the major numbers match and the
|
||||
application minor is less than or equal to the kernel minor.
|
||||
The kernel version number is returned in the following structure:
|
||||
.Bd -literal -offset indent
|
||||
struct bpf_version {
|
||||
u_short bv_major;
|
||||
|
|
@ -307,20 +313,26 @@ Returns the number of bytes that are immediately available for reading.
|
|||
.It Dv SIOCGIFADDR (struct ifreq)
|
||||
Returns the address associated with the interface.
|
||||
.It Dv FIONBIO (int)
|
||||
Set or clear non-blocking I/O. If arg is non-zero, then doing a
|
||||
Set or clear non-blocking I/O.
|
||||
If arg is non-zero, then doing a
|
||||
.Xr read 2
|
||||
when no data is available will return -1 and
|
||||
.Va errno
|
||||
will be set to
|
||||
.Er EAGAIN .
|
||||
If arg is zero, non-blocking I/O is disabled. Note: setting this
|
||||
If arg is zero, non-blocking I/O is disabled.
|
||||
Note: setting this
|
||||
overrides the timeout set by
|
||||
.Dv BIOCSRTIMEOUT .
|
||||
.It Dv FIOASYNC (int)
|
||||
Enable or disable async I/O. When enabled (arg is non-zero), the process or
|
||||
process group specified by FIOSETOWN will start receiving SIGIO's when packets
|
||||
Enable or disable async I/O.
|
||||
When enabled (arg is non-zero), the process or process group specified by
|
||||
.Dv FIOSETOWN
|
||||
will start receiving SIGIO's when packets
|
||||
arrive.
|
||||
Note that you must do an FIOSETOWN in order for this to take affect, as
|
||||
Note that you must do an
|
||||
.Dv FIOSETOWN
|
||||
in order for this to take affect, as
|
||||
the system will not default this for you.
|
||||
The signal may be changed via
|
||||
.Dv BIOCSRSIG .
|
||||
|
|
@ -348,7 +360,8 @@ The fields, whose values are stored in host order, and are:
|
|||
.It Va bh_tstamp
|
||||
The time at which the packet was processed by the packet filter.
|
||||
.It Va bh_caplen
|
||||
The length of the captured portion of the packet. This is the minimum of
|
||||
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.
|
||||
.It Va bh_datalen
|
||||
The length of the packet off the wire.
|
||||
|
|
@ -369,14 +382,16 @@ The packet filter ensures that the
|
|||
.Va bpf_hdr
|
||||
and the
|
||||
.Em 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
|
||||
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).
|
||||
.Pp
|
||||
Additionally, individual packets are padded so that each starts
|
||||
on a word boundary. This requires that an application
|
||||
on a word boundary.
|
||||
This requires that an application
|
||||
has some knowledge of how to get from packet to packet.
|
||||
The macro
|
||||
.Dv BPF_WORDALIGN
|
||||
|
|
@ -384,7 +399,9 @@ is defined in
|
|||
.Aq Pa 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).
|
||||
to the nearest word aligned value (where a word is
|
||||
.Dv BPF_ALIGNMENT
|
||||
bytes wide).
|
||||
.Pp
|
||||
For example, if
|
||||
.Sq Va p
|
||||
|
|
@ -429,7 +446,8 @@ 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
|
||||
BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC.
|
||||
Various other mode and
|
||||
operator bits are or'd into the class to give the actual instructions.
|
||||
The classes and modes are defined in
|
||||
.Aq Pa net/bpf.h .
|
||||
|
|
@ -443,7 +461,8 @@ 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.
|
||||
addressed in word units.
|
||||
The memory store is indexed from 0 to BPF_MEMWORDS-1.
|
||||
.Va k ,
|
||||
.Va jt ,
|
||||
and
|
||||
|
|
@ -454,8 +473,8 @@ instruction definition.
|
|||
refers to the length of the packet.
|
||||
.Bl -tag -width indent -offset indent
|
||||
.It Sy BPF_LD
|
||||
These instructions copy a value into the accumulator. The type of the
|
||||
source operand is specified by an
|
||||
These instructions copy a value into the accumulator.
|
||||
The type of the source operand is specified by an
|
||||
.Dq addressing mode
|
||||
and can be a constant
|
||||
.Sy ( BBPF_IMM ) ,
|
||||
|
|
@ -490,9 +509,9 @@ The semantics of all the recognized BPF_LD instructions follow.
|
|||
.It Sy BPF_LD+BPF_MEM Ta A \*[Lt]- M[k]
|
||||
.El
|
||||
.It Sy 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
|
||||
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
|
||||
.Sy BPF_MSH ,
|
||||
a hack for efficiently loading the IP header length.
|
||||
.Bl -column "BPF_LDX_BPF_W_BPF_IMM" "X \*[Lt]- k" -offset indent
|
||||
|
|
@ -540,8 +559,8 @@ or
|
|||
.It Sy BPF_ALU+BPF_NEG Ta A \*[Lt]- -A
|
||||
.El
|
||||
.It Sy BPF_JMP
|
||||
The jump instructions alter flow of control. Conditional jumps
|
||||
compare the accumulator against a constant
|
||||
The jump instructions alter flow of control.
|
||||
Conditional jumps compare the accumulator against a constant
|
||||
.Sy ( BPF_K )
|
||||
or the index register
|
||||
.Sy ( BPF_X ) .
|
||||
|
|
@ -567,8 +586,8 @@ All conditionals use unsigned comparison conventions.
|
|||
.El
|
||||
.It Sy 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.
|
||||
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
|
||||
.Sy ( BPF_K )
|
||||
or the accumulator
|
||||
|
|
@ -580,7 +599,8 @@ or the accumulator
|
|||
.It Sy 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
|
||||
be added.
|
||||
Currently, these are the register transfer instructions
|
||||
that copy the index register to the accumulator or vice versa.
|
||||
.Bl -column "BPF_MISC+BPF_TAX" "X \*[Lt]- A" -offset indent
|
||||
.It Sy BPF_MISC+BPF_TAX Ta X \*[Lt]- A
|
||||
|
|
@ -622,8 +642,8 @@ utility.
|
|||
.Sh FILES
|
||||
.Pa /dev/bpf
|
||||
.Sh EXAMPLES
|
||||
The following filter is taken from the Reverse ARP Daemon. It accepts
|
||||
only Reverse ARP requests.
|
||||
The following filter is taken from the Reverse ARP Daemon.
|
||||
It accepts only Reverse ARP requests.
|
||||
.Bd -literal -offset indent
|
||||
struct bpf_insn insns[] = {
|
||||
BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
|
||||
|
|
@ -654,8 +674,9 @@ struct bpf_insn insns[] = {
|
|||
};
|
||||
.Ed
|
||||
.Pp
|
||||
Finally, this filter returns only TCP finger packets. We must parse
|
||||
the IP header to reach the TCP header. The
|
||||
Finally, this filter returns only TCP finger packets.
|
||||
We must parse the IP header to reach the TCP header.
|
||||
The
|
||||
.Sy BPF_JSET
|
||||
instruction checks that the IP fragment offset is 0 so we are sure
|
||||
that we have a TCP header.
|
||||
|
|
@ -691,13 +712,15 @@ struct bpf_insn insns[] = {
|
|||
.Re
|
||||
.Sh HISTORY
|
||||
The Enet packet filter was created in 1980 by Mike Accetta and
|
||||
Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at
|
||||
Stanford, ported the code to BSD and continued its development from
|
||||
1983 on. Since then, it has evolved into the ULTRIX Packet Filter
|
||||
Rick Rashid at Carnegie-Mellon University.
|
||||
Jeffrey Mogul, at Stanford, ported the code to BSD and continued
|
||||
its development from 1983 on.
|
||||
Since then, it has evolved into the ULTRIX Packet Filter
|
||||
at DEC, a STREAMS NIT module under SunOS 4.1, and BPF.
|
||||
.Sh AUTHORS
|
||||
Steven McCanne, of Lawrence Berkeley Laboratory, implemented BPF in
|
||||
Summer 1990. The design was in collaboration with Van Jacobson,
|
||||
Summer 1990.
|
||||
The design was in collaboration with Van Jacobson,
|
||||
also of Lawrence Berkeley Laboratory.
|
||||
.Sh BUGS
|
||||
The read buffer must be of a fixed size (returned by the
|
||||
|
|
@ -706,8 +729,9 @@ ioctl).
|
|||
.Pp
|
||||
A file that does not request promiscuous mode may receive promiscuously
|
||||
received packets as a side effect of another file requesting this
|
||||
mode on the same hardware interface. This could be fixed in the kernel
|
||||
with additional processing overhead. However, we favor the model where
|
||||
mode on the same hardware interface.
|
||||
This could be fixed in the kernel with additional processing overhead.
|
||||
However, we favor the model where
|
||||
all files must assume that the interface is promiscuous, and if
|
||||
so desired, must use a filter to reject foreign packets.
|
||||
.Pp
|
||||
|
|
|
|||
Loading…
Reference in New Issue