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

FreeBSD Manual Pages


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>


     To	enable support for divert sockets, place the following lines in	the
     kernel configuration file:

	   options IPFIREWALL
	   options IPDIVERT

     Alternatively, to load the	driver as a module at boot time, add the fol-
     lowing lines into the loader.conf(5) file:


     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 ad-
     dress in the bind is ignored; only	the port number	is significant.	 A di-
     vert 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 ar-
     bitrary ``filter''	as they	travel through the host	machine, special rout-
     ing 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 some tag supplied by the packet diverter, (usually the ipfw	rule
     number) and the IP	address	set to the (first) address of the interface on
     which the packet was received (if the packet was incoming)	or INADDR_ANY
     (if the packet was	outgoing).  The	interface name (if defined for the
     packet) will be placed in the 8 bytes following the address, if it	fits.

     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
     using sendto(2) and minimal error checking	is done.  Packets are distin-
     guished as	either incoming	or outgoing.  If sendto(2) is used with	a des-
     tination 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, or an interface name	must be	found after the	IP ad-
     dress.  If	an interface name is found, that interface will	be used	and
     the value of the IP address will be ignored (other	than the fact that it
     is	not INADDR_ANY).  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 (see below).

     The port part of the socket address passed	to the sendto(2) contains a
     tag that should be	meaningful to the diversion module.  In	the case of
     ipfw(8) the tag is	interpreted as the rule	number after which rule	pro-
     cessing should restart.

     Packets written into a divert socket (using sendto(2)) re-enter the
     packet filter at the rule number following	the tag	given in the port part
     of	the socket address, which is usually already set at the	rule number
     that caused the diversion (not the	next rule if there are several at the
     same number).  If the 'tag' is altered to indicate	an alternative re-en-
     try point,	care should be taken to	avoid loops, where the same packet is
     diverted more than	once at	the same rule.

     If	a packet is diverted but no socket is bound to the port, or if
     IPDIVERT is not enabled or	loaded 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.

     Note that packets arriving	on the divert socket by	the ipfw(8) tee	action
     are delivered as-is and packet fragments do not get reassembled in	this

     Packets are received and sent unchanged, except that packets read as out-
     going have	invalid	IP header checksums, and packets written as outgoing
     have their	IP header checksums overwritten	with the correct value.	 Pack-
     ets written as incoming and having	incorrect checksums will be dropped.
     Otherwise,	all header fields are unchanged	(and therefore in network or-

     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(4), ipfw(8)

     Archie Cobbs <>,	Whistle	Communications Corp.

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

     It	is questionable	whether	incoming fragments should be reassembled be-
     fore being	diverted.  For example,	if only	some fragments of a packet
     destined for another machine do not get routed through the	local machine,
     the packet	is lost.  This should probably be a settable socket option in
     any case.

FreeBSD	13.0		       December	17, 2004		  FreeBSD 13.0


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

home | help