bpf man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

bpf(7)									bpf(7)

NAME
       bpf - 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)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net