Wireshark · Ethereal-dev: Re: [ethereal-dev] GxSNMP

[guy@xxxxxxxxxx (Guy Harris)]

> > If you have a SunOS 4.x machine handy, the "NIT(4P)" man page, and the
> > man pages it refers you to, give details.
> 
> I no longer do. Can someone send that manpage to the list, please?

I've attached a shell archive containing the man pages in question,
which should be formattable on any system using the UNIX man page macros
(which appears to include Linux, but *doesn't* include the AT&T-free
BSDs; yeah, one could argue that their man page macros are "better", but
it's a royal pain formatting BSD man pages on non-BSD systems, although
maybe BSD systems can figure out that something's a UNIX man page and
format it).

> What would be nice, then, is to make wiretap produce BPF, NIT, and DLPI
> "code" from the same filter string. That was the promise of libpcap, but it
> hasn't been officially patched/improved in a while now. (June 1997?)

July 1998, it appears from an "ls -l" of the top-level directory on
"ftp.ee.lbl.gov":

-r--r--r--  1 leres     wheel     209551 Jul 25 19:43 libpcap-0.4.tar.Z

No sign of anything to use the CMU/Stanford filter facility in STREAMS
NIT and DLPI, though.

> And RMON too, huh?

Yup, although the CMU/Stanford packet filter used by STREAMS NIT and
DLPI isn't as powerful as BPF (dunno whether anything expressible with,
say, the language compiled by "libpcap" is inexpressible as a
CMU/Stanford filter), and the RMON one is also not as powerful as BPF.

However, I suspect many common filter expressions can be handled by any
of them, and I also suspect there's a way to turn expressions that can't
into a combination of an expression that can, and that discards many
uninteresting packets, and one that can't, which you run through BPF in
userland to filter out the remaining uninteresting ones).

Sharfile with the Sun man pages in question:

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of shell archive."
# Contents:  nit.4p nit_buf.4m nit_if.4m nit_pf.4m
# Wrapped by guy@xxxxxxxxxxxxxxx on Wed Dec 30 23:28:55 1998
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'nit.4p' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'nit.4p'\"
else
echo shar: Extracting \"'nit.4p'\" \(6646 characters\)
sed "s/^X//" >'nit.4p' <<'END_OF_FILE'
X.\" @(#)nit.4p 1.22 90/02/15 SMI;
X.TH NIT 4P "29 December 1987"
X.SH NAME
Xnit \- Network Interface Tap
X.SH CONFIG
X.nf
X.B pseudo-device	clone
X.B pseudo-device	snit
X.B pseudo-device	pf
X.B pseudo-device	nbuf
X.fi
X.SH SYNOPSIS
X.nf
X.B #include <sys/file.h>
X.B #include <sys/ioctl.h>
X.B #include <net/nit_pf.h>
X.B #include <net/nit_buf.h>
X.sp 0.25v
X	\fIfd\fP\fB = open("/dev/nit", \|\fP\fImode\fP\fB);\fP
X	\fBioctl(\fP\fIfd\fP\fB, \|I_PUSH, \|"pf");\fP
X	\fBioctl(\fP\fIfd\fP\fB, \|I_PUSH, \|"nbuf");\fP
X.fi
X.SH DESCRIPTION
X.IX "NIT facility" "" "NIT, Network Interface Tap"
X.IX STREAMS NIT "" "NIT, Network Interface Tap"
X.LP
X.SM NIT
X(the Network Interface Tap)
Xis a facility composed of several
X.SM STREAMS
Xmodules and drivers.
XThese components collectively provide facilities
Xfor constructing applications
Xthat require link-level network access.
XExamples of such applications include
X.BR rarpd (8C),
Xwhich is a user-level implementation of the Reverse
X.SM ARP
Xprotocol, and
X.BR etherfind (8C),
Xwhich is a network monitoring and trouble-shooting program.
X.LP
X.SM NIT
Xconsists of several components that are summarized below.
XSee their Reference Manual entries for detailed information
Xabout their specification and operation.
X.TP 12
X.BR nit_if (4M)
XThis component is a
X.SM STREAMS
Xdevice driver that interacts directly with the system's Ethernet drivers.
XAfter opening an instance of this device it must be bound
Xto a specific Ethernet interface before becoming usable.
XSubsequently,
X.B nit_if
Xtranscribes packets arriving on the interface
Xto the read side of its associated stream
Xand delivers messages reaching it on the write side of its stream
Xto the raw packet output code for transmission over the interface.
X.TP
X.BR nit_pf (4M)
XThis module provides packet-filtering services,
Xallowing uninteresting incoming packets
Xto be discarded with minimal loss of efficiency.
XIt passes through unaltered all outgoing messages
X(those on the stream's write side).
X.TP
X.BR nit_buf (4M)
XThis module buffers incoming messages into larger aggregates,
Xthereby reducing the overhead incurred by repeated
X.BR read (2V)
Xsystem calls.
X.LP
X.SM NIT
Xclients mix and match these components,
Xbased on their particular requirements.
XFor example, the reverse
X.SM ARP
Xdaemon concerns itself only with packets of a specific type
Xand deals with low traffic volumes.
XThus,
Xit uses
X.B nit_if
Xfor access to the network and
X.B nit_pf
Xto filter out all incoming packets except reverse
X.SM ARP
Xpackets, but omits the
X.B nit_buf
Xbuffering module since traffic is not high enough
Xto justify the additional complexity of unpacking buffered packets.
XOn the other hand, the
X.BR etherd (8C)
Xprogram, which collects Ethernet statistics for
X.BR traffic (1C)
Xto display, must examine every packet on the network.
XTherefore, it omits the
X.B nit_pf
Xmodule, since there is nothing it wishes to screen out,
Xand includes the
X.B nit_buf
Xmodule, since most networks have very heavy aggregate packet traffic.
X.SH EXAMPLES
X.LP
XThe following code fragments outline how to program
Xagainst parts of the
X.SM NIT
Xinterface.
XFor the sake of brevity, all error-handling code has been elided.
X.LP
X.B initdevice
Xcomes from
X.B etherfind
Xand sets up its input stream configuration.
X.LP
X.nf
X.ft B
X.if t .ps -1
X.if t .vs -1
Xinitdevice(if_flags, snaplen, chunksize)
X	u_long	if_flags,
X		snaplen,
X		chunksize;
X.br
X.ne 3
X{
X	struct strioctl	si;
X	struct ifreq	ifr;
X	struct timeval	timeout;
X
X	if_fd = open(NIT_DEV, O_RDONLY);
X
X	/* Arrange to get discrete messages from the stream. */
X	ioctl(if_fd, I_SRDOPT, (char *)RMSGD);
X
X	si.ic_timout = INFTIM;
X
X	/* Push and configure the buffering module. */
X	ioctl(if_fd, I_PUSH, "nbuf");
X
X	timeout.tv_sec = 1;
X	timeout.tv_usec = 0;
X	si.ic_cmd = NIOCSTIME;
X	si.ic_len = sizeof timeout;
X	si.ic_dp = (char *)&timeout;
X	ioctl(if_fd, I_STR, (char *)&si);
X
X	si.ic_cmd = NIOCSCHUNK;
X	si.ic_len = sizeof chunksize;
X	si.ic_dp = (char *)&chunksize;
X	ioctl(if_fd, I_STR, (char *)&si);
X
X	/* Configure the nit device, binding it to the proper
X	   underlying interface, setting the snapshot length,
X	   and setting nit_if-level flags. */
X	strncpy(ifr.ifr_name, device, sizeof ifr.ifr_name);
X	ifr.ifr_name[sizeof ifr.ifr_name - 1] = '\e0';
X	si.ic_cmd = NIOCBIND;
X	si.ic_len = sizeof ifr;
X	si.ic_dp = (char *)&ifr;
X	ioctl(if_fd, I_STR, (char *)&si);
X
X	if (snaplen > 0) {
X		si.ic_cmd = NIOCSSNAP;
X		si.ic_len = sizeof snaplen;
X		si.ic_dp = (char *)&snaplen;
X		ioctl(if_fd, I_STR, (char *)&si);
X	}
X
X	if (if_flags != 0) {
X		si.ic_cmd = NIOCSFLAGS;
X		si.ic_len = sizeof if_flags;
X		si.ic_dp = (char *)&if_flags;
X		ioctl(if_fd, I_STR, (char *)&si);
X	}
X
X	/* Flush the read queue, to get rid of anything that accumulated
X	   before the device reached its final configuration. */
X	ioctl(if_fd, I_FLUSH, (char *)FLUSHR);
X}
X.if t .vs
X.if t .ps
X.ft R
X.fi
X.br
X.ne 5
X.LP
XHere is the skeleton of the packet reading loop from
X.BR etherfind .
XIt illustrates how to cope with dismantling the headers the various
X.SM NIT
Xcomponents glue on.
X.LP
X.nf
X.ft B
X.if t .ps -1
X.if t .vs -1
X	while ((cc = read(if_fd, buf, chunksize)) >= 0) {
X		register u_char	*bp = buf,
X				*bufstop = buf + cc;
X
X		/* Loop through each message in the chunk. */
X		while (bp < bufstop) {
X			register u_char		*cp = bp;
X			struct nit_bufhdr	*hdrp;
X			struct timeval		*tvp = NULL;
X			u_long			drops = 0;
X			u_long			pktlen;
X
X			/* Extract information from the successive objects
X			   embedded in the current message.  Which ones we
X			   have depends on how we set up the stream (and
X			   therefore on what command line flags were set).
X			  
X			   If snaplen is positive then the packet was truncated
X			   before the buffering module saw it, so we must
X			   obtain its length from the nit_if-level nit_iflen
X			   header.  Otherwise the value in *hdrp suffices. */
X			hdrp = (struct nit_bufhdr *)cp;
X			cp += sizeof *hdrp;
X			if (tflag) {
X				struct nit_iftime	*ntp;
X
X				ntp = (struct nit_iftime *)cp;
X				cp += sizeof *ntp;
X
X				tvp = &ntp->nh_timestamp;
X			}
X			if (dflag) {
X				struct nit_ifdrops	*ndp;
X
X				ndp = (struct nit_ifdrops *)cp;
X				cp += sizeof *ndp;
X
X				drops = ndp->nh_drops;
X			}
X			if (snaplen > 0) {
X				struct nit_iflen	*nlp;
X
X				nlp = (struct nit_iflen *)cp;
X				cp += sizeof *nlp;
X
X				pktlen = nlp->nh_pktlen;
X			}
X			else
X				pktlen = hdrp->nhb_msglen;
X
X			sp = (struct sample *)cp;
X			bp += hdrp->nhb_totlen;
X
X			/* Process the packet. */
X		}
X	}
X.if t .vs
X.if t .ps
X.ft R
X.fi
X.SH FILES
X.PD 0
X.TP 20
X.B /dev/nit
Xclone device instance referring to
X.B nit_if
X.PD
X.SH "SEE ALSO"
X.BR traffic (1C),
X.BR read (2V),
X.BR nit_if (4M),
X.BR nit_pf (4M),
X.BR nit_buf (4M),
X.BR etherd (8C),
X.BR etherfind (8C),
X.BR rarpd (8C)
END_OF_FILE
if test 6646 -ne `wc -c <'nit.4p'`; then
    echo shar: \"'nit.4p'\" unpacked with wrong size!
fi
# end of 'nit.4p'
fi
if test -f 'nit_buf.4m' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'nit_buf.4m'\"
else
echo shar: Extracting \"'nit_buf.4m'\" \(5053 characters\)
sed "s/^X//" >'nit_buf.4m' <<'END_OF_FILE'
X.\" @(#)nit_buf.4m 1.8 90/02/15 SMI;
X.TH NIT_BUF 4M "29 December 1987"
X.SH NAME
Xnit_buf \- STREAMS NIT buffering module
X.SH CONFIG
X.B
Xpseudo-device	nbuf
X.SH SYNOPSIS
X.nf
X.B
X#include <sys/ioctl.h>
X.B
X#include <net/nit_buf.h>
X.B
Xioctl(fd, \|\s-1I_PUSH\s0, \|"nbuf");
X.fi
X.SH DESCRIPTION
X.IX "nit_buf module" "" "\fLnit_buf\fP, \s-1NIT\s0 buffering module"
X.IX STREAMS nit_buf "" "\fLnit_buf\fP, \s-1NIT\s0 buffering module"
X.LP
X.B nit_buf
Xis a
X.SM STREAMS
Xmodule that buffers incoming messages,
Xthereby reducing the number of system calls and associated overhead
Xrequired to read and process them.
XAlthough designed to be used in conjunction
Xwith the other components of
X.SM NIT
X(see
X.BR nit (4P)),
X.B nit_buf
Xis a general-purpose module and can be used
Xanywhere
X.SM STREAMS
Xinput buffering is required.
X.SS "Read-side Behavior"
X.B nit_buf
Xcollects incoming
X.SB M_DATA
Xand
X.SB M_PROTO
Xmessages into
X.IR chunks ,
Xpassing each chunk upward when either the chunk becomes full
Xor the current read timeout expires.
XWhen a message arrives,
Xit is processed in two steps.
XFirst,
Xthe message is prepared for inclusion in a chunk,
Xand then it is added to the current chunk.
XThe following paragraphs discuss each step in turn.
X.LP
XUpon receiving a message from below,
X.B nit_buf
Ximmediately converts all leading
X.SB M_PROTO
Xblocks in the message to
X.SB M_DATA
Xblocks,
Xaltering only the message type field and leaving the contents alone.
XIt then prepends a header to the converted message.
XThis header is defined as follows.
X.RS
X.ft B
X.nf
Xstruct nit_bufhdr {
X	u_int	nhb_msglen;
X	u_int	nhb_totlen;
X};
X.fi
X.ft R
X.RE
XThe first field of this header gives the length in bytes
Xof the converted message.
XThe second field gives the distance in bytes
Xfrom the start of the message in the current chunk
X(described below)
Xto the start of the next message in the chunk;
Xthe value reflects any padding necessary to insure
Xcorrect data alignment for the host machine
Xand includes the length of the header itself.
X.LP
XAfter preparing a message,
X.B nit_buf
Xattempts to add it to the end of the current chunk,
Xusing the chunk size and timeout values to govern the addition.
X(The chunk size and timeout values are set and inspected
Xusing the
X.B ioctl
Xcalls described below.)
XIf adding the new message would make the current chunk grow
Xlarger than the chunk size,
X.B nit_buf
Xcloses off the current chunk,
Xpassing it up to the next module in line,
Xand starts a new chunk,
Xseeding it with a zero-length message.
XIf adding the message would still make
Xthe current chunk overflow,
Xthe module passes it upward in an over-size chunk of its own.
XOtherwise,
Xthe module concatenates the message to the end of the current chunk.
X.LP
XTo ensure that messages do not languish forever
Xin an accumulating chunk,
X.B nit_buf
Xmaintains a read timeout.
XWhenever this timeout expires,
Xthe module closes off the current chunk,
Xregardless of its length,
Xand passes it upward;
Xif no incoming messages have arrived,
Xthe chunk passed upward will have zero length.
XWhenever the module passes a chunk upward,
Xit restarts the timeout period.
XThese two rules insure that
X.B nit_buf
Xminimizes the number of chunks it produces
Xduring periods of intense message activity
Xand that it periodically disposes of all messages
Xduring slack intervals.
X.LP
X.B nit_buf
Xhandles other message types as follows.
XUpon receiving an
X.SB M_FLUSH
Xmessage specifying that the read queue be flushed,
Xthe module does so,
Xclearing the currently accumulating chunk as well,
Xand passes the message on to the module or driver above.
XIt passes all other messages through unaltered to its upper neighbor.
X.SS "Write-side Behavior"
X.B nit_buf
Xintercepts
X.SB M_IOCTL
Xmessages for the
X.IR ioctl s
Xdescribed below.
XUpon receiving an
X.SB M_FLUSH
Xmessage specifying that the write queue be flushed,
Xthe module does so and
Xpasses the message on to the module or driver below.
XThe module passes all other messages through unaltered
Xto its lower neighbor.
X.SH IOCTLS
X.B nit_buf
Xresponds to the following
X.IR ioctl s.
X.nr Xx \w'\s-1NIOCSCHUK\s0'u+3nu
X.TP \n(Xxu
X.SB NIOCSTIME
XSet the read timeout value to the value referred to by the
X.I "struct timeval"
Xpointer given as argument.
XSetting the timeout value to zero
Xhas the side-effect of forcing the chunk size to zero as well,
Xso that the module will pass all incoming messages upward
Ximmediately upon arrival.
X.TP
X.SB NIOCGTIME
XReturn the read timeout in the
X.I "struct timeval"
Xpointed to by the argument.
XIf the timeout has been cleared with the
X.SB NIOCCTIME
X.IR ioctl ,
Xreturn with an
X.SM ERANGE
Xerror.
X.TP
X.SB NIOCCTIME
XClear the read timeout,
Xeffectively setting its value to infinity.
X.TP
X.SB NIOCSCHUNK
XSet the chunk size to the value referred to by the
X.I u_int
Xpointer given as argument.
X.TP
X.SB NIOCGCHUNK
XReturn the chunk size in the
X.I u_int
Xpointed to by the argument.
X.SH WARNING
XThe module name ``nbuf''
Xused in the system configuration file and as argument to the
X.SB I_PUSH
X.B ioctl
Xis provisional and subject to change.
X.SH "SEE ALSO"
X.BR nit (4P),
X.BR nit_if (4M),
X.BR nit_pf (4M)
END_OF_FILE
if test 5053 -ne `wc -c <'nit_buf.4m'`; then
    echo shar: \"'nit_buf.4m'\" unpacked with wrong size!
fi
# end of 'nit_buf.4m'
fi
if test -f 'nit_if.4m' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'nit_if.4m'\"
else
echo shar: Extracting \"'nit_if.4m'\" \(6117 characters\)
sed "s/^X//" >'nit_if.4m' <<'END_OF_FILE'
X.\" @(#)nit_if.4m 1.13 90/02/15 SMI;
X.TH NIT_IF 4M "29 December 1987"
X.SH NAME
Xnit_if \- STREAMS NIT device interface module
X.SH CONFIG
X.B
Xpseudo-device	snit
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/file.h>
Xopen("/dev/nit", mode);
X.ft R
X.fi
X.SH DESCRIPTION
X.IX "nit_if module" "" "\fLnit_if\fP, \s-1NIT\s0 device interface"
X.IX STREAMS nit_if "" "\fLnit_if\fP, \s-1NIT\s0 device interface"
X.LP
X.B nit_if
Xis a
X.SM STREAMS
Xpseudo-device driver that provides
X.SM STREAMS
Xaccess to network interfaces.
XIt is designed to be used in conjunction
Xwith the other components of
X.SM NIT
X(see
X.BR nit (4P)),
Xbut can be used by itself as a raw
X.SM STREAMS
Xnetwork interface.
X.LP
X.B nit_if
Xis an exclusive-open device
Xthat is intended to be opened indirectly through the clone device;
X.B /dev/nit
Xis a suitable instance of the clone device.
XBefore the stream resulting from opening an instance of
X.B nit_if
Xmay be used to read or write packets,
Xit must first be bound to a specific network interface,
Xusing the
X.SB NIOCSBIND
Xioctl described below.
X.SS "Read-side Behavior"
X.B nit_if
Xcopies leading prefixes of selected packets
Xfrom its associated network interface
Xand passes them up the stream.
XIf the
X.SB NI_PROMISC
Xflag is set,
Xit passes along all packets;
Xotherwise it passes along only packets addressed
Xto the underlying interface.
X.LP
XThe amount of data copied from a given packet depends on the current
X.IR "snapshot length" ,
Xwhich is set with the
X.SB NIOCSSNAP
Xioctl
Xdescribed below.
X.LP
XBefore passing each packet prefix upward,
X.B nit_if
Xoptionally prepends one or more headers,
Xas controlled by the state of the flag bits set with the
X.SB NIOCSFLAGS
X.IR ioctl .
XThe driver collects headers into
X.SB M_PROTO
Xmessage blocks,
Xwith the headers guaranteed to be completely contained
Xin a single message block,
Xwhereas the packet itself goes into
Xone or more
X.SB M_DATA
Xmessage blocks.
X.SS "Write-side Behavior"
X.B nit_if
Xaccepts packets from the module above it in the stream
Xand relays them to the associated network interface for transmission.
XPackets must be formatted with the destination address in a leading
X.SB M_PROTO
Xmessage block,
Xfollowed by the packet itself,
Xcomplete with link-level header,
Xin a sequence of
X.SB M_DATA
Xmessage blocks.
XThe destination address must be expressed as a
X.RB ` "struct sockaddr" '
Xwhose
X.I sa_family
Xfield is
X.BR \s-1AF_UNSPEC\s0
Xand whose
X.I sa_data
Xfield is a copy of the link-level header.
X(See
X.B sys/socket.h
Xfor the definition of this structure.)
XIf the packet does not conform to this format,
Xan
X.SB M_ERROR
Xmessage with
X.SM EINVAL
Xwill be sent upstream.
X.LP
X.B nit_if
Xprocesses
X.SB M_IOCTL
Xmessages as described below.
XUpon receiving an
X.SB M_FLUSH
Xmessage specifying that the write queue be flushed,
X.B nit_if
Xdoes so and transfers the message to the read side of the stream.
XIt discards all other messages.
X.SH IOCTLS
X.B nit_if
Xresponds to the following
X.IR ioctl s,
Xas defined in
X.BR net/nit_if.h .
XIt generates an
X.SB M_IOCNAK
Xmessage for all others,
Xreturning this message to the invoker along the
Xread side of the stream.
X.TP 20
X.SB SIOCGIFADDR
X.TP 20
X.SB SIOCADDMULTI
X.TP 20
X.SB SIOCDELMULTI
X.B nit_if
Xpasses these
Xioctls on to the underlying interface's driver
Xand returns its response in a
X.RB `  "struct ifreq" '
Xinstance,
Xas defined in
X.BR net/if.h .
X(See the description of this
Xioctl in
X.BR if (4N)
Xfor more details.)
X.TP
X.SB NIOCBIND
XThis ioctl
Xattaches the stream represented by its first argument
Xto the network interface designated by its third argument,
Xwhich should be a pointer to an
X.I ifreq
Xstructure whose
X.I ifr_name
Xfield names the desired interface.
XSee
X.B net/if.h
Xfor the definition of this structure.
X.TP
X.SB NIOCSSNAP
XSet the current snapshot length to the value
Xgiven in the
X.I u_long
Xpointed to by the
X.IR ioctl 's
Xfinal argument.
X.B nit_if
Xinterprets a snapshot length value of zero as meaning infinity,
Xso that it will copy all selected packets in their entirety.
XIt constrains positive snapshot lengths to be at least
Xthe length of an Ethernet header,
Xso that it will pass at least the link-level header
Xof all selected packets to its upstream neighbor.
X.TP
X.SB NIOCGSNAP
XReturns the current snapshot length
Xfor this device instance in the
X.I u_long
Xpointed to by the
X.IR ioctl 's
Xfinal argument.
X.TP
X.SB NIOCSFLAGS
X.B nit_if
Xrecognizes the following flag bits,
Xwhich must be given in the
X.I u_long
Xpointed to by the
X.IR ioctl 's
Xfinal argument.
XThis set may be augmented in future releases.
XAll but the
X.SB NI_PROMISC
Xbit control the addition of headers that precede the packet body.
XThese headers appear in the order given below,
Xwith the last-mentioned enabled header adjacent to the packet body.
X.RS
X.TP 20
X.SB NI_PROMISC
XRequests that the underlying interface
Xbe set into promiscuous mode and that all packets
Xthat the interface receives be passed up through the stream.
X.B nit_if
Xonly honors this bit for the super-user.
X.TP
X.SB NI_TIMESTAMP
XPrepend to each selected packet a header
Xcontaining the packet arrival time expressed
Xas a
X.RB `  "struct timeval" '.
X.TP
X.SB NI_DROPS
XPrepend to each selected packet a header containing
Xthe cumulative number of packets that this instance of
X.B nit_if
Xhas dropped because of flow control requirements or resource exhaustion.
XThe header value is expressed as a
X.IR u_long .
XNote: it accounts only for events occurring within
X.BR nit_if ,
Xand does not count packets dropped at the network interface level
Xor by upstream modules.
X.TP
X.SB NI_LEN
XPrepend to each selected packet a header containing the packet's
Xoriginal length
X(including link-level header),
Xas it was before being trimmed to the snapshot length.
XThe header value is expressed as a
X.IR u_long .
X.RE
X.TP 20
X.SB NIOCGFLAGS
XReturns the current state of the flag bits
Xfor this device instance in the
X.I u_long
Xpointed to by the
X.IR ioctl 's
Xfinal argument.
X.SH FILES
X.PD 0
X.TP 20
X.B /dev/nit
Xclone device instance referring to
X.B nit_if
Xdevice
X.TP
X.B net/nit_if.h
Xheader file containing definitions for the
X.IR ioctl s
Xand packet headers described above.
X.PD
X.SH "SEE ALSO"
X.BR clone (4),
X.BR nit (4P),
X.BR nit_buf (4M),
X.BR nit_pf (4M)
END_OF_FILE
if test 6117 -ne `wc -c <'nit_if.4m'`; then
    echo shar: \"'nit_if.4m'\" unpacked with wrong size!
fi
# end of 'nit_if.4m'
fi
if test -f 'nit_pf.4m' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'nit_pf.4m'\"
else
echo shar: Extracting \"'nit_pf.4m'\" \(12773 characters\)
sed "s/^X//" >'nit_pf.4m' <<'END_OF_FILE'
X.\" @(#)nit_pf.4m 1.11 90/02/15 SMI;
X.TH NIT_PF 4M "24 January 1990"
X.SH NAME
Xnit_pf \- STREAMS NIT packet filtering module
X.SH CONFIG
X.B
Xpseudo-device	pf
X.SH SYNOPSIS
X.nf
X.B
X#include <sys/ioctl.h>
X.B
X#include <net/nit_pf.h>
X.sp 0.25v
X	\fBioctl(\fP\fIfd\fP\fB, \|\s-1I_PUSH\s0, \|"pf");\fP
X.fi
X.SH DESCRIPTION
X.IX "nit_pf module" "" "\fLnit_pf\fP, \s-1NIT\s0 packet filtering module"
X.IX STREAMS nit_pf "" "\fLnit_pf\fP, \s-1NIT\s0 packet filtering module"
X.LP
X.B nit_pf
Xis a
X.SM STREAMS
Xmodule that subjects messages arriving on its read queue
Xto a packet filter
Xand passes only those messages that the filter accepts on
Xto its upstream neighbor.
XSuch filtering can be very useful for user-level protocol implementations
Xand for networking monitoring programs
Xthat wish to view only specific types of events.
X.SS "Read-side Behavior"
X.B nit_pf
Xapplies the current packet filter to all
X.SB M_DATA
Xand
X.SB M_PROTO
Xmessages arriving on its read queue.
XThe module prepares these messages for examination
Xby first skipping over all leading
X.SB M_PROTO
Xmessage blocks to arrive at the beginning of the message's data portion.
XIf there is no data portion,
X.B nit_pf
Xaccepts the message and passes it along to its upstream neighbor.
XOtherwise,
Xthe module ensures that the part of the message's data
Xthat the packet filter might examine
Xlies in contiguous memory,
Xcalling the
X.I pullupmsg
Xutility routine if necessary to force contiguity.
X(Note:
Xthis action destroys any sharing relationships
Xthat the subject message might have had with other messages.)
XFinally,
Xit applies the packet filter to the message's data,
Xpassing the entire message upstream to the next module
Xif the filter accepts,
Xand discarding the message otherwise.
XSee
X.SM "PACKET FILTERS"
Xbelow for details on how the filter works.
X.LP
XIf there is no packet filter yet in effect,
Xthe module acts as if the filter exists but does nothing,
Ximplying that all incoming messages are accepted.
X.SM IOCTLS
Xbelow describes how to associate a packet filter
Xwith an instance of
X.BR nit_pf .
X.LP
X.B nit_pf
Xhandles other message types as follows.
XUpon receiving an
X.SB M_FLUSH
Xmessage specifying that the read queue be flushed,
Xthe module does so,
Xand passes the message on to its upstream neighbor.
XIt passes all other messages through unaltered to its upper neighbor.
X.SS "Write-side Behavior"
X.B nit_pf
Xintercepts
X.SB M_IOCTL
Xmessages for the
X.IR ioctl
Xdescribed below.
XUpon receiving an
X.SB M_FLUSH
Xmessage specifying that the write queue be flushed,
Xthe module does so and
Xpasses the message on to the module or driver below.
XThe module passes all other messages through unaltered
Xto its lower neighbor.
X.SH IOCTLS
X.LP
X.B nit_pf
Xresponds to the following
X.IR ioctl .
X.nr Xx \w'\fB\s-1NIOCSETF\s0\fP'u+(3n)u
X.TP \n(Xxu
X.SB NIOCSETF
XThis
X.I ioctl
Xdirects the module to replace its current packet filter,
Xif any,
Xwith the filter specified by the
X.RB ` "struct packetfilt" '
Xpointer named by its final argument.
XThis structure is defined in
X.B <net/packetfilt.h>
Xas
X.\"	Ugh! Nesting shouldn't be required here!
X.\"
X.\"	The formatting here is ugly and should be fixed
X.\"	(and would be if I had any good ideas...).
X.RS
X.RS
X.nf
X.ft B
X.if t .ta \w'stru'u  +\w'u_short   'u  +\w'Pf_FilterLen;   'u
X.if n .ta \w'stru'u  +\w'u_short  'u  +\w'Pf_FilterLen;  'u
Xstruct packetfilt {
X	u_char	Pf_Priority;	/* priority of filter */
X	u_char	Pf_FilterLen;	/* # of cmds in list */
X	u_short	Pf_Filter[\s-1ENMAXFILTERS\s0];
X					/* filter command list */
X};
X.DT
X.ft R
X.fi
X.RE
X.RE
X.br
X.ne 8
X.IP
XThe
X.I Pf_Priority
Xfield is included only for compatibility
Xwith other packet filter implementations
Xand is otherwise ignored.
XThe packet filter itself is specified in the
X.I Pf_Filter
Xarray as a sequence of two-byte commands,
Xwith the
X.I Pf_FilterLen
Xfield giving the number of commands in the sequence.
XThis implementation restricts
Xthe maximum number of commands in a filter
X.RB ( \s-1ENMAXFILTERS\s0 )
Xto 40.
XThe next section describes the available commands and their semantics.
X.\"
X.SH "PACKET FILTERS"
X.LP
XA packet filter consists of the filter command list length
X(in units of
X.IR u_short s),
Xand the filter command list itself.
X(The priority field mentioned above
Xis ignored in this implementation.)
XEach filter command list specifies a sequence of actions
Xthat operate on an internal stack of
X.IR u_short s
X(\*(lqshortwords\*(rq).
XEach shortword of the command list specifies one of the actions
X.SM ENF_PUSHLIT\s0,
X.SM ENF_PUSHZERO\s0,
Xor
X.SM ENF_PUSHWORD\s0\c
X.RI + n ,
Xwhich respectively push the next shortword of the command list,
Xzero,
Xor shortword
X.I n
Xof the subject message on the stack,
Xand a binary operator
Xfrom the set {
X.SM ENF_EQ\s0,
X.SM ENF_NEQ\s0,
X.SM ENF_LT\s0,
X.SM ENF_LE\s0,
X.SM ENF_GT\s0,
X.SM ENF_GE\s0,
X.SM ENF_AND\s0,
X.SM ENF_OR\s0,
X.SM ENF_XOR
X}
Xwhich then operates on the top two elements of the stack
Xand replaces them with its result.
XWhen both an action and operator are specified in the same shortword,
Xthe action is performed followed by the operation.
X.LP
XThe binary operator can also be from the set {
X.SM ENF_COR\s0,
X.SM ENF_CAND\s0,
X.SM ENF_CNOR\s0,
X.SM ENF_CNAND\s0
X}.
XThese are \*(lqshort-circuit\*(rq operators,
Xin that they terminate the execution of the filter immediately
Xif the condition they are checking for is found,
Xand continue otherwise.
XAll pop two elements from the stack and compare them for equality;
X.SM ENF_CAND
Xreturns false if the result is false;
X.SM ENF_COR
Xreturns true if the result is true;
X.SM ENF_CNAND
Xreturns true if the result is false;
X.SM ENF_CNOR
Xreturns false if the result is true.
XUnlike the other binary operators,
Xthese four do not leave a result on the stack,
Xeven if they continue.
X.LP
XThe short-circuit operators should be used when possible,
Xto reduce the amount of time spent evaluating filters.
XWhen they are used,
Xyou should also arrange the order of the tests
Xso that the filter will succeed or fail as soon as possible;
Xfor example,
Xchecking the
X.SM IP
Xdestination field of a
X.SM UDP
Xpacket is more likely to indicate failure than the packet type field.
X.LP
XThe
Xspecial action
X.SM ENF_NOPUSH
Xand the special operator
X.SM ENF_NOP
Xcan be used to only
Xperform the binary operation or to only push a value on the stack.
XSince both are (conveniently) defined to be zero,
Xindicating only an action actually specifies the action followed by
X.SM ENF_NOP\s0,
Xand indicating only an operation actually specifies
X.SM ENF_NOPUSH
Xfollowed by the operation.
X.LP
XAfter executing the filter command list,
Xa non-zero value (true) left on top of the stack
X(or an empty stack) causes the incoming
Xpacket to be accepted
Xand a zero value (false) causes the packet to be rejected.
X(If the filter exits as the result of a short-circuit operator,
Xthe top-of-stack value is ignored.)
XSpecifying an undefined operation or action in the command list
Xor performing an illegal operation or action
X(such as pushing a shortword offset past the end of the packet
Xor executing a binary operator with fewer than two shortwords on the stack)
Xcauses a filter to reject the packet.
X.\"
X.\" The notion of priority is currently unimplemented. **********
X.\".LP
X.\"In an attempt to deal with the problem of
X.\"overlapping and/or conflicting packet filters,
X.\"the filters for each open
X.\".I enet
X.\"file are ordered by the driver
X.\"according to their priority
X.\"(lowest priority is 0, highest is 255).
X.\"When processing incoming Ethernet packets,
X.\"filters are applied according to their priority
X.\"(from highest to lowest)
X.\"and for identical priority values
X.\"according to their relative \*(lqbusyness\*(rq
X.\"(the filter that has previously matched the most packets is checked first)
X.\"until one or more filters accept the packet
X.\"or all filters reject it and it is discarded.
X.\".LP
X.\"Filters at a priority of 2 or higher are called \*(lqhigh priority\*(rq
X.\"filters.
X.\"Once a packet is delivered to one of these \*(lqhigh priority\*(rq
X.\".I enet
X.\"files,
X.\"no further filters are examined,
X.\"that is,
X.\"the packet is delivered only
X.\"to the first
X.\".I enet
X.\"file with a \*(lqhigh priority\*(rq filter that accepts the packet.
X.\"A packet may be delivered to more than one filter
X.\"with a priority below 2;
X.\"this might be useful,
X.\"for example, in building replicated programs.
X.\"However,
X.\"the use of low-priority filters imposes an additional cost on the system,
X.\"as these filters each must be checked against all packets
X.\"not accepted by a high-priority filter.
X.\".LP
X.\"The packet filter for an
X.\".I enet
X.\"file is initialized
X.\"with length 0 at priority 0 by
X.\".BR open (2V),
X.\"and hence by default accepts all packets
X.\"that no \*(lqhigh priority\*(rq filter is interested in.
X.\".LP
X.\"Priorities should be assigned so that,
X.\"in general,
X.\"the more packets a filter is expected to match,
X.\"the higher its priority.
X.\"This will prevent a lot of needless checking
X.\"of packets against filters that aren't likely to match them.
X.\" End of commented out section **********
X.\"
X.SH EXAMPLES
X.LP
XThe reverse
X.SM ARP
Xdaemon program
X.RB ( rarpd (8C))
Xuses code similar to the following fragment to construct a filter
Xthat rejects all but
X.SM RARP
Xpackets.
XThat is,
Xis accepts only packets whose Ethernet type field
Xhas the value
X.SM ETHERTYPE_REVARP\s0.
X.LP
X.ft B
X.nf
X	struct ether_header eh;		/* used only for offset values */
X	struct packetfilt pf;
X	register u_short *fwp = pf.Pf_Filter;
X	u_short offset;
X
X	/*
X	 * Set up filter.  Offset is the displacement of the Ethernet
X	 * type field from the beginning of the packet in units of
X	 * u_shorts.
X	 */
X.br
X.ne 10
X	offset = ((u_int) &eh.ether_type - (u_int) &eh.ether_dhost) / sizeof (u_short);
X	*fwp++ = \s-1ENF_PUSHWORD\s0 + offset;
X	*fwp++ = \s-1ENF_PUSHLIT\s0;
X	*fwp++ = htons(\s-1ETHERTYPE_REVARP\s0);
X	*fwp++ = \s-1ENF_EQ\s0;
X	pf.Pf_FilterLen = fwp - &pf.Pf_Filter[0];
X.ft R
X.fi
X.LP
XThis filter can be abbreviated by taking advantage
Xof the ability to combine actions and operations:
X.LP
X.nf
X	.\|.\|.
X.ft B
X	*fwp++ = \s-1ENF_PUSHWORD\s0 + offset;
X	*fwp++ = \s-1ENF_PUSHLIT\s0 | \s-1ENF_EQ\s0;
X	*fwp++ = htons(\s-1ETHERTYPE_REVARP\s0);
X.ft R
X	.\|.\|.
X.fi
X.\"
X.\" XXX: These examples should be revised to better fit the Sun environment.
X.\"      If no alternatives come to hand, it'd probably be best simply to
X.\"      drop the remaining examples.
X.\"
X.\"      Done!                                       ****************
X.\".LP
X.\"The following filter would accept all incoming
X.\".I pup
X.\"packets on a 3mb Ethernet
X.\"with Pup types in the range 1-0200:
X.\".LP
X.\".nf
X.\".ft B
X.\".ta \w'struct 'u \w'struct ENF_PUSHWORD+8, ENF_PUSHLIT, 0xFF00, ENF_AND,      'u
X.\"struct packetfilt f = {
X.\"	10, 19,	/* priority and length */
X.\"	\s-1ENF_PUSHWORD\s0+1, \s-1ENF_PUSHLIT\s0, 2, \s-1ENF_EQ\s0,	/* packet type \s-1PUP\s0 */
X.\"	\s-1ENF_PUSHWORD\s0+3, \s-1ENF_PUSHLIT\s0, 0x\s-1FF\s000, \s-1ENF_AND\s0,	/* mask hi byte */
X.\"	\s-1ENF_PUSHZERO\s0, \s-1ENF_GT\s0,	/* PupType > 0 */
X.\"	\s-1ENF_PUSHWORD\s0+3, \s-1ENF_PUSHLIT\s0, 0x\s-1FF\s000, \s-1ENF_AND\s0,	/* mask hi byte */
X.\"	\s-1ENF_PUSHLIT\s0, 0100, \s-1ENF_LE\s0,	/* PupType <= 0100 */
X.\"	\s-1ENF_AND\s0,	/* 0 < PupType <= 0100 */
X.\"	\s-1ENF_AND\s0	/* && packet type == \s-1PUP\s0 */
X.\"};
X.\".DT
X.\".ft R
X.\".fi
X.\".LP
X.\"Note:
X.\"shortwords,
X.\"such as the packet type field,
X.\"are byte-swapped and so the literals you compare them to
X.\"must be byte-swapped.
X.\"Also,
X.\"although for this example the word offsets are constants,
X.\"code that must run with either 3mb or 10mb Ethernets must use
X.\"offsets that depend on the device type.
X.\".LP
X.\"A different example shows the use of \*(lqshort-circuit\*(rq operators
X.\"to create a more efficient filter.
X.\"This one accepts Pup packets
X.\"(on a 3Mbit Ethernet)
X.\"with a Socket field of 12345.
X.\"Note:
X.\"we check the Socket field before the packet type field,
X.\"since in most packets the Socket is not likely to match.
X.\".sp
X.\".nf
X.\".ta \w'struct 'u \w'struct ENF_PUSHWORD+3, ENF_PUSHLIT | ENF_CAND, 12345,      'u
X.\".ft B
X.\"struct packetfilt f = {
X.\"	10, 9,	/* priority and length */
X.\"	\s-1ENF_PUSHWORD\s0+7, \s-1ENF_PUSHLIT\s0 | \s-1ENF_CAND\s0, 0,	/* Hi word of socket */
X.\"	\s-1ENF_PUSHWORD\s0+8, \s-1ENF_PUSHLIT\s0 | \s-1ENF_CAND\s0, 12345,	/* Lo word of socket */
X.\"	\s-1ENF_PUSHWORD\s0+1, \s-1ENF_PUSHLIT\s0 | \s-1ENF_CAN\s0D, 2	/* packet type == Pup */
X.\"};
X.\".ft R
X.\".DT
X.\".fi
X.\" End of commented out section **********
X.\"
X.SH WARNINGS
X.LP
XThe module name
X.RB ` pf '
Xused in the system configuration file and as argument to the
X.SB I_PUSH
X.I ioctl
Xis provisional and subject to change.
X.LP
XThe
X.I Pf_Priority
Xfield of the
X.I packetfilt
Xstructure is likely to be removed.
X.SH "SEE ALSO"
X.BR inet (4F),
X.BR nit (4P),
X.BR nit_buf (4M),
X.BR nit_if (4M)
END_OF_FILE
if test 12773 -ne `wc -c <'nit_pf.4m'`; then
    echo shar: \"'nit_pf.4m'\" unpacked with wrong size!
fi
# end of 'nit_pf.4m'
fi
echo shar: End of shell archive.
exit 0