Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DIVERT(4)	       FreeBSD Kernel Interfaces Manual		     DIVERT(4)

     divert -- kernel packet diversion mechanism

     #include <sys/types.h>
     #include <sys/socket.h>
     #include <netinet/in.h>


     Divert sockets are	similar	to raw IP sockets, except that they can	be
     bound to a	specific divert	port via the bind(2) system call. The IP
     address in	the bind is ignored; only the port number is significant.  A
     divert socket bound to a divert port will receive all packets diverted to
     that port by some (here unspecified) kernel mechanism(s).	Packets	may
     also be written to	a divert port, in which	case they re-enter kernel IP
     packet processing.

     Divert sockets are	normally used in conjunction with FreeBSD's packet
     filtering implementation and the ipfw(8) program. By reading from and
     writing to	a divert socket, matching packets can be passed	through	an
     arbitrary ``filter'' as they travel through the host machine, special
     routing tricks can	be done, etc.

     Packets are diverted either as they are ``incoming'' or ``outgoing.''
     Incoming packets are diverted after reception on an IP interface, whereas
     outgoing packets are diverted before next hop forwarding.

     Diverted packets may be read unaltered via	read(2), recv(2), or
     recvfrom(2).  In the latter case, the address returned will have its port
     set to the	divert port and	the IP address set to the (first) address of
     the interface on which the	packet was received (if	the packet was incom-
     ing) or INADDR_ANY	(if the	packet was outgoing).

     Writing to	a divert socket	is similar to writing to a raw IP socket; the
     packet is injected	``as is'' into the normal kernel IP packet processing
     and minimal error checking	is done.  Packets are written as either	incom-
     ing or outgoing: if write(2) or send(2) is	used to	deliver	the packet, or
     if	sendto(2) is used with a destination IP	address	of INADDR_ANY, then
     the packet	is treated as if it were outgoing, i.e., destined for a	non-
     local address.  Otherwise,	the packet is assumed to be incoming and full
     packet routing is done.

     In	the latter case, the IP	address	specified must match the address of
     some local	interface.  This is to indicate	on which interface the packet

     Normally, packets read as incoming	should be written as incoming; simi-
     larly for outgoing	packets.  When reading and then	writing	back packets,
     passing the same socket address supplied by recvfrom(2) unmodified	to
     sendto(2) simplifies things.

     Packets written into a divert socket (using sendto(2)) are	never redi-
     verted back to the	same socket.  This means that a	given packet (either
     incoming or outgoing) will	be diverted to a given socket once and once

     Ipfw(8) rules are executed	in order, each time the	packet passes through
     the kernel, but only up until a matching divert rule applies.  On the
     second pass, after	the packet has been diverted, the divert rule is
     ignored and any subsequent	ipfw(8)	rules are applied.  For	this reason,
     it	is normally best to specify your divert	rules prior to any others.

     To	enable divert sockets, your kernel must	be compiled with the option

     If	a packet is diverted but no socket is bound to the port, or if
     IPDIVERT is not enabled in	the kernel, the	packet is dropped.

     Incoming packet fragments which get diverted are fully reassembled	before
     delivery; the diversion of	any one	fragment causes	the entire packet to
     get diverted.  If different fragments divert to different ports, then
     which port	ultimately gets	chosen is unpredictable.

     Packets are received and sent unchanged, except that packets written as
     outgoing have their IP header checksums overwritten with the correct
     value.  Packets written as	incoming and having incorrect checksums	will
     be	dropped.  Otherwise, all header	fields are unchanged (and therefore in
     network order).

     Binding to	port numbers less than 1024 requires super-user	access,	as
     does creating a socket of type SOCK_RAW.

     Writing to	a divert socket	can return these errors, along with the	usual
     errors possible when writing raw packets:

     [EINVAL]		The packet had an invalid header, or the IP options in
			the packet and the socket options set were incompati-

     [EADDRNOTAVAIL]	The destination	address	contained an IP	address	not
			equal to INADDR_ANY that was not associated with any

     bind(2), recvfrom(2), sendto(2), socket(2), ipfw(8)

     This is an	attempt	to provide a clean way for user	mode processes to
     implement various IP tricks like address translation, but it could	be
     cleaner, and it's too dependent on	ipfw(8).

     It's questionable whether incoming	fragments should be reassembled	before
     being diverted. For example, if only some fragments of a packet destined
     for another machine don't get routed through the local machine, the
     packet is lost. This should probably be a settable	socket option in any

     Archie Cobbs <>,	Whistle	Communications Corp.

FreeBSD				 June 18, 1996			       FreeBSD


Want to link to this manual page? Use this URL:

home | help