packetfilter.4

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 4 代码 · 共 1,077 行 · 第 1/2 页

.TH packetfilter 4
.SH Name
packetfilter \- Ethernet packet filter
.SH Syntax
.B "options	PACKETFILTER"
.br
.B "pseudo-device	packetfilter"
.SH Description
.NXR "packetfilter"
The packet filter pseudo-device driver
provides a raw interface to Ethernets and similar network data link layers.
Packets received that are not used by the kernel
(for example, to support the IP and DECnet protocol families)
are available through this mechanism.
The packet filter driver is kernel-resident code provided by
the ULTRIX operating system.  The driver appears to
applications as a set of character special files, one
for each open packet filter application.
(Throughout this reference page, the word
.I file
refers to such a character special file.)
.PP
You create the minor device files
with the
.MS MAKEDEV 8
script using
these commands:
.EX
# \f(CBcd /dev\fP
# \f(CBMAKEDEV pfilt
.EE
A single call to
.PN MAKEDEV
with an argument of
.PN pfilt
creates 64 character special files in 
.PN /dev/pf ,
which are named
.PN pfilt\fInnn ,
\fRwhere \fInnn\fP is
the unit number.
Successive calls to
.PN MAKEDEV
with arguments of
.PN pfilt1 ,
.PN pfilt2 ,
and
.PN pfilt3
make additional sets of 64 sequentially numbered packet filters
to a maximum of 256.
The maximum number of packet filter special files
is limited to 256, which is the maximum number of
minor device numbers allowed for each major device number.
(See 
.MS MAKEDEV 8 
for more information on making system special files.)
.PP
For opening these special files, the ULTRIX operating system
provides the
.MS pfopen 3 
library routine.
.PP
Associated with each open instance of a
packet filter special
file is a user-settable packet filter ``program''
that is used to select which incoming 
packets are delivered by that
packet filter special file.
Whenever a packet is received from the net,
the packet filter driver successively applies the filter
programs of each of the open packet filter files to the
packet, until one filter program ``accepts'' the packet.
When a filter accepts the packet,
it is placed on the packet input queue of the
associated special file.
If no filters accept the packet, it is discarded.
The format of a packet filter is described later.
.PP
Reads from these files return the next packet
from a queue of packets that have matched the filter.
If the read operation specifies insufficient buffer space
to store the entire packet,
the packet is truncated and the trailing contents lost.
Writes to these files transmit packets on the
network, with each write operation generating exactly one packet.
.PP
The packet filter supports a variety of different Ethernet
data-link levels:
.IP "10Mb Ethernet"
.br
Packets consist of fourteen or more bytes, with the first six
bytes specifying the destination Ethernet address,
the next six bytes the source Ethernet address,
and the next two bytes specifying the packet type.
(This is the Standard Ethernet.)
.IP "3Mb Ethernet"
.br
Packets consist of four or more bytes, with the first byte
specifying the source Ethernet address, the second
byte specifying the destination Ethernet address,
and the next two bytes specifying the packet type.
(On the network, the source and destination addresses
are in the opposite order.)
.br
.ne 6
.IP "Byte-swapping 3Mb Ethernet"
.br
Packets consist of four or more bytes, with the first byte
specifying the source Ethernet address, the second
byte specifying the destination Ethernet address,
and the next two bytes specifying the packet type.
Each short word (pair of bytes) is swapped from the network
byte order.  This device type is provided only for
backwards-compatibility.
.PP
The remaining words are interpreted according to the packet type.
Note that 16-bit and 32-bit quantities may have to be byteswapped
(and possibly short-swapped) to be intelligible on an ULTRIX system.
.PP
The packet filters treat the entire packet,
including headers, as uninterpreted data.
The user must supply
the headers for transmitted packets (although the system makes sure that
the source address is correct) and the headers of received packets
are delivered to the user.
The packet filter mechanism does not know anything about the data
portion of the packets it sends and receives.
.PP
In addition to the FIONREAD
.PN ioctl
request (described in the 
.MS tty 4
reference page), the application can apply several special
.PN ioctl
requests to an open
packet filter file.  The calls are divided into five categories:
packet-filter specifying,
packet handling,
device configuration,
administrative,
and miscellaneous.
.br
.ne 1i
.SS Packet-filter Specification ioctl Request
The
.PN EIOCSETF
.PN ioctl
is central to the operation of the packet filter interface, because
it specifies which packets the application wishes to receive.
It is used to set the packet filter ``program''
for an open
packet filter file, and is of the form:
.EX
ioctl(\fIfildes\fP, EIOCSETF, \fIfilter\fP)
struct enfilter *\fIfilter\fP
.EE
The
.PN enfilter
structure is defined in 
.PN <net/pfilt.h>
as:
.EX
.ta \w'struct 'u \w'struct u_short  'u
struct enfilter
{
	u_char	enf_Priority;
	u_char	enf_FilterLen;
	u_short	enf_Filter[ENMAXFILTERS];
};
.DT
.EE
.PP
A packet filter consists of a priority,
the filter command list length (in shortwords),
and the filter command list itself.
Each filter command list specifies
a sequence of actions that
operate on an internal stack.
Each shortword of the
command list specifies an action and a binary operator.  
.SS Command List Actions
The action
can be one of the following:
.IP ENF_PUSHLIT
.br
Pushes the next shortword of the command list on the stack.
.IP ENF_PUSHWORD+N
.br
Pushes shortword N of the incoming packet on the stack.
.br
.ne 3
.IP ENF_PUSHZERO
.br
Pushes a zero.  Is slightly faster than ENF_PUSHLIT with an
explicit literal.
.IP ENF_PUSHONE
.br
Pushes a one.  Is slightly faster than ENF_PUSHLIT with an 
explicit literal.
.IP ENF_PUSHFFFF
.br
Pushes 0xFFFF.  Is slightly faster than ENF_PUSHLIT with an
explicit literal.
.IP ENF_PUSH00FF
.br
Pushes  0x00FF.  Is slightly faster than ENF_PUSHLIT with an
explicit literal.
.IP ENF_PUSHFF00
.br
Pushes 0xFF00.  Is slightly faster than ENF_PUSHLIT with an
explicit literal.
.IP ENF_NOPUSH
.br
Defined as zero.
.SS Binary Operators
When both an action and an operator are specified in the
same shortword, the action is performed, followed by the
operation.
You can combine an action with an operator 
using bitwise OR;
for example,
.EX
((ENF_PUSHWORD+3) | ENF_EQ)
.EE
.PP
The binary operator, which can be one of the following, operates on
the top two elements of the stack and replaces them with its
result:
.IP ENF_EQ 15
Returns true if the result is equal.
.IP ENF_NEQ
Returns true if the result is not equal.
.IP ENF_LT
Returns true if the result is less than.
.IP ENF_LE
Returns true if the result is less than or equal.
.IP ENF_GT
Returns true if the result is greater than.
.IP ENF_GE
Returns true if the result is greater than or equal.
.IP ENF_AND
Returns the result of the binary AND operation.
.IP ENF_OR
Returns the result of the binary OR operation.
.IP ENF_XOR
Returns the result of the binary XOR operation.
.IP ENF_NOP
Defined as zero.
.IP ENF_CAND
Returns false immediately if the result is false,
and continues execution of the filter otherwise.
(Short-circuit operator)
.IP ENF_COR
Returns true immediately if the result is true,
and continues execution of the filter otherwise.
(Short-circuit operator)
.IP ENF_CNAND
Returns true immediately if the result is false,
and continues execution of the filter otherwise.
(Short-circuit operator)
.IP ENF_CNOR
Returns false immediately if the result is true,
and continues execution of the filter otherwise.
(Short-circuit operator)
.PP
The short-circuit operators are so called because they terminate
the execution of the filter immediately if the condition they are 
checking for is found, and continue otherwise.
All the short-circuit operators pop two elements from the stack and 
compare them for equality.
Unlike the other binary operators, these four operators do not leave a result
on the stack, even if they continue.
.PP
Use the short-circuit operators whenever possible, to reduce the
amount of time spent evaluating filters.  When you use them, you should
also arrange the order of the tests so that the filter will succeed or fail
as soon as possible. For example, checking a word in
an address field of an Ethernet packet 
is more likely to indicate failure than the Ethernet type field.
.PP
The
special action
ENF_NOPUSH
and the special operator
ENF_NOP
can be used to only perform the binary operation or
to only push a value on the stack.
Because both are defined to be zero, specifying
only an action actually specifies the action followed by
ENF_NOP, and specifying only an operation actually specifies
ENF_NOPUSH
followed
by the operation.
.PP
After executing the filter command list, a nonzero value (true)
left on top of the stack
(or an empty stack) causes the incoming
packet to be accepted for the corresponding
packet filter file and a zero value (false) causes the packet to
be passed through the next packet filter.
If the filter exits as the result of a short-circuit operator,
the top-of-stack value is ignored.
Specifying an undefined operation or action in the command list
or performing an illegal operation or action (such as pushing
a shortword offset
past the end of the packet or executing a binary operator
with fewer than two shortwords on the stack) causes a filter to
reject the packet.
.PP
To resolve problems with
overlapping or conflicting packet filters,
the filters for each open
packet filter file are ordered by the driver
according to their priority
(lowest
priority is 0, highest is 255).
When processing incoming
packets, filters are applied according to their
priority (from highest to lowest) and
for identical priority values according to their
relative ``busyness'' (the filter that has previously
matched the most packets is checked first), until one or more filters
accept the packet or all filters reject it and
it is discarded.
.PP
Normally once a packet is delivered to a filter, it is not presented to any
other filters.  However, if the packet is accepted by a filter in
nonexclusive mode (ENNONEXCL set using EIOCMBIS,
described in the following section), the packet is
passed along to lower-priority filters and may be delivered more than
once.
The use of nonexclusive filters imposes an additional cost on
the system, because it increases the average number of filters applied to each
packet.
.PP
The packet filter for a packet filter file is initialized
with length 0 at priority 0 by
.MS open 2 ,
and hence, by default, accepts all
packets in which no higher-priority filter
is interested.
.PP
Priorities should be assigned so that, in general, the more packets a
filter is expected to match, the higher its priority.  This prevents
a lot of checking of packets against filters that are unlikely
to match them.
.br
.ne 3i
.PP
The filter in this example accepts incoming
RARP (Reverse Address Resolution Protocol) broadcast packets.
.PP
The filter first checks the Ethernet type of the packet.
If it is not a RARP (Reverse ARP) packet, it is discarded. 
Then, the RARP type field is checked for a reverse request (type 3),
followed by a check for a broadcast destination address.
Note that the packet type field is checked before the destination address,
because the total number of broadcast packets on the network is larger
than the number of RARP packets.  Thus, the filter is
ordered with a minimum amount of processing overhead.
.EX
.ta \w'stru'u \w'struct ENF_PUSHWORD,      'u
struct enfilter f =
{
	36, 0,	/* priority and length */
	ENF_PUSHWORD + 6,
	ENF_PUSHLIT, 0x3580,
	ENF_CAND,	/* Ethernet type == 0x8035 (RARP) */
	ENF_PUSHWORD + 10,
	ENF_PUSHLIT, 0x0300,
	ENF_CAND,	/* reverse request type = 0003 */
	ENF_PUSHWORD + 0,
	ENF_PUSHLIT, 0xFFFF,
	ENF_CAND,	/* dest addr = FF-FF */
	ENF_PUSHWORD + 1,
	ENF_PUSHLIT, 0xFFFF,
	ENF_CAND,	/* dest addr = FF-FF */
	ENF_PUSHWORD + 2,
	ENF_PUSHLIT, 0xFFFF,
	ENF_EQ	/* dest addr = FF-FF */
};
.DT
.EE
.PP
Note that shortwords, such as the packet type field, are in network
byte-order.
The literals you compare them to may have to be byte-swapped
on machines like the VAX.
.br
.ne 3i
.PP
By taking advantage of the ability to
specify both an action and operation in each word of
the command list, you could abbreviate the filter to the
following:
.EX
.ta \w'stru'u \w'struct ENF_PUSHLIT | ENF_CAND,  'u
struct enfilter f =
{
	36, 0,	/* priority and length */
	ENF_PUSHWORD + 6,
	ENF_PUSHLIT | ENF_CAND,
	0x3580,	/* Ethernet type == 0x8035 (RARP) */
	ENF_PUSHWORD + 10,
	ENF_PUSHLIT | ENF_CAND,
	0x0300,	/* reverse request type = 0003 */
	ENF_PUSHWORD + 0,
	ENF_PUSHFFFF | ENF_CAND,	/* dest addr = FF-FF */
	ENF_PUSHWORD + 1,
	ENF_PUSHFFFF | ENF_CAND,	/* dest addr = FF-FF */
	ENF_PUSHWORD + 2,
	ENF_PUSHFFFF | ENF_EQ	/* dest addr = FF-FF */
};
.DT
.EE
.ne 1i
.SS Packet-Handling ioctl Requests
These
.PN ioctl
requests control how the packet filter processes input packets
and returns them to the application process.
The most useful of these requests set and clear so-called
``mode bits'' for the file and are of this form:
.EX
ioctl(\fIfildes\fP, \fIcode\fP, \fIbits\fP)
u_short *\fIbits\fP;
.DT
.EE
.i0
.PP
In these calls,
.I bits
is a bitmask specifying which bits to set or clear.  The applicable
.I codes
are:
.IP EIOCMBIS
.br
Sets the specified mode bits.
.IP EIOCMBIC
.br
Clears the specified mode bits.
.br
.ne 1i
.PP
The bits 
are:
.IP ENTSTAMP
.br
If set, a received packet is preceded by a header structure (see the
description of
.PN enstamp
following) that includes a time stamp and other information.
.IP ENBATCH
.br
If clear, each
.MS read 2
system call returns at most one packet.  If set, a
.PN read
call might return more than one packet, each of which is preceded by an
.PN enstamp
header.
.IP ENPROMISC
.br
If set, this filter will be applied to promiscuously-received packets.
This puts the interface into ``promiscuous mode'' only if this
has been allowed by the superuser using the EIOCALLOWPROMISC
.PN ioctl
call (described later).
.IP ENCOPYALL
.br
If set, this filter will see packets sent and received by the
kernel-resident protocols of the local host.  (Normally, these packets
are not copied to the packet filter.)  This mode takes effect only if this
has been allowed by the superuser using the EIOCALLOWCOPYALL
.PN ioctl
call (described later).
.br
.ne 4
.IP ENNONEXCL
.br
If set, packets accepted by this filter will be available to
any lower-priority filters.  If clear, no lower-priority filter will see
packets accepted by this filter.
.IP ENHOLDSIG
.br
If clear,
means that the driver should
disable the effect of EIOCENBS (described later)
once it has delivered a signal.
If set (the default), the effect of EIOCENBS persists.
.PP
The
.PN enstamp
structure contains useful information about the packet that immediately
follows it; in ENBATCH mode, it also allows the reader to separate the
packets in a batch.  It is defined in
.PN <net/pfilt.h>
as:
.EX
.ta \w'struct 'u +\w'struct timeval  'u
struct enstamp {
	u_short	ens_stamplen;
	u_short	ens_flags;
	u_short	ens_count;
	u_short	ens_dropped;
	u_long	ens_ifoverflows;
	struct	timeval	ens_tstamp;
};
.EE
.i0
.DT
.PP
The fields are:
.IP ens_stamplen
.br
The length of 
.PN enstamp
structure in bytes.  The packet data follows immediately.
.br
.ne 1.25i
.IP ens_flags
.br
Indicates how the packet was received. The bits 
are:
.RS
.IP ENSF_PROMISC
.br
Received promiscuously (unicast to some other host).
.IP ENSF_BROADCAST
.br
Received as a broadcast.
.IP ENSF_MULTICAST
.br
Received as a multicast.
.IP ENSF_TRAILER
.br
Received in a trailer encapsulation.  The packet has been rearranged into
header format.
.RE