1.\" 2.Dd December 17, 2004 3.Dt DIVERT 4 4.Os 5.Sh NAME 6.Nm divert 7.Nd kernel packet diversion mechanism 8.Sh SYNOPSIS 9.In sys/types.h 10.In sys/socket.h 11.In netinet/in.h 12.Ft int 13.Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT 14.Pp 15To enable support for divert sockets, place the following lines in the 16kernel configuration file: 17.Bd -ragged -offset indent 18.Cd "options IPFIREWALL" 19.Cd "options IPDIVERT" 20.Ed 21.Pp 22Alternatively, to load 23the driver 24as a module at boot time, add the following lines into the 25.Xr loader.conf 5 26file: 27.Bd -literal -offset indent 28ipfw_load="YES" 29ipdivert_load="YES" 30.Ed 31.Sh DESCRIPTION 32Divert sockets are similar to raw IP sockets, except that they 33can be bound to a specific 34.Nm 35port via the 36.Xr bind 2 37system call. 38The IP address in the bind is ignored; only the port 39number is significant. 40A divert socket bound to a divert port will receive all packets diverted 41to that port by some (here unspecified) kernel mechanism(s). 42Packets may also be written to a divert port, in which case they 43re-enter kernel IP packet processing. 44.Pp 45Divert sockets are normally used in conjunction with 46.Fx Ns 's 47packet filtering implementation and the 48.Xr ipfw 8 49program. 50By reading from and writing to a divert socket, matching packets 51can be passed through an arbitrary ``filter'' as they travel through 52the host machine, special routing tricks can be done, etc. 53.Sh READING PACKETS 54Packets are diverted either as they are ``incoming'' or ``outgoing.'' 55Incoming packets are diverted after reception on an IP interface, 56whereas outgoing packets are diverted before next hop forwarding. 57.Pp 58Diverted packets may be read unaltered via 59.Xr read 2 , 60.Xr recv 2 , 61or 62.Xr recvfrom 2 . 63In the latter case, the address returned will have its port set to 64some tag supplied by the packet diverter, (usually the ipfw rule number) 65and the IP address set to the (first) address of 66the interface on which the packet was received (if the packet 67was incoming) or 68.Dv INADDR_ANY 69(if the packet was outgoing). 70The interface name (if defined 71for the packet) will be placed in the 8 bytes following the address, 72if it fits. 73.Sh WRITING PACKETS 74Writing to a divert socket is similar to writing to a raw IP socket; 75the packet is injected ``as is'' into the normal kernel IP packet 76processing using 77.Xr sendto 2 78and minimal error checking is done. 79Packets are distinguished as either incoming or outgoing. 80If 81.Xr sendto 2 82is used with a destination IP address of 83.Dv INADDR_ANY , 84then the packet is treated as if it were outgoing, i.e., destined 85for a non-local address. 86Otherwise, the packet is assumed to be 87incoming and full packet routing is done. 88.Pp 89In the latter case, the 90IP address specified must match the address of some local interface, 91or an interface name 92must be found after the IP address. 93If an interface name is found, 94that interface will be used and the value of the IP address will be 95ignored (other than the fact that it is not 96.Dv INADDR_ANY ) . 97This is to indicate on which interface the packet 98.Dq arrived . 99.Pp 100Normally, packets read as incoming should be written as incoming; 101similarly for outgoing packets. 102When reading and then writing back 103packets, passing the same socket address supplied by 104.Xr recvfrom 2 105unmodified to 106.Xr sendto 2 107simplifies things (see below). 108.Pp 109The port part of the socket address passed to the 110.Xr sendto 2 111contains a tag that should be meaningful to the diversion module. 112In the 113case of 114.Xr ipfw 8 115the tag is interpreted as the rule number 116.Em after which 117rule processing should restart. 118.Sh LOOP AVOIDANCE 119Packets written into a divert socket 120(using 121.Xr sendto 2 ) 122re-enter the packet filter at the rule number 123following the tag given in the port part of the socket address, which 124is usually already set at the rule number that caused the diversion 125(not the next rule if there are several at the same number). 126If the 'tag' 127is altered to indicate an alternative re-entry point, care should be taken 128to avoid loops, where the same packet is diverted more than once at the 129same rule. 130.Sh DETAILS 131If a packet is diverted but no socket is bound to the 132port, or if 133.Dv IPDIVERT 134is not enabled or loaded in the kernel, the packet is dropped. 135.Pp 136Incoming packet fragments which get diverted are fully reassembled 137before delivery; the diversion of any one fragment causes the entire 138packet to get diverted. 139If different fragments divert to different ports, 140then which port ultimately gets chosen is unpredictable. 141.Pp 142Note that packets arriving on the divert socket by the 143.Xr ipfw 8 144.Cm tee 145action are delivered as-is and packet fragments do not get reassembled 146in this case. 147.Pp 148Packets are received and sent unchanged, except that 149packets read as outgoing have invalid IP header checksums, and 150packets written as outgoing have their IP header checksums overwritten 151with the correct value. 152Packets written as incoming and having incorrect checksums will be dropped. 153Otherwise, all header fields are unchanged (and therefore in network order). 154.Pp 155Binding to port numbers less than 1024 requires super-user access, as does 156creating a socket of type SOCK_RAW. 157.Sh ERRORS 158Writing to a divert socket can return these errors, along with 159the usual errors possible when writing raw packets: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162The packet had an invalid header, or the IP options in the packet 163and the socket options set were incompatible. 164.It Bq Er EADDRNOTAVAIL 165The destination address contained an IP address not equal to 166.Dv INADDR_ANY 167that was not associated with any interface. 168.El 169.Sh SEE ALSO 170.Xr bind 2 , 171.Xr recvfrom 2 , 172.Xr sendto 2 , 173.Xr socket 2 , 174.Xr ipfw 4 , 175.Xr ipfw 8 176.Sh AUTHORS 177.An Archie Cobbs Aq Mt archie@FreeBSD.org , 178Whistle Communications Corp. 179.Sh BUGS 180This is an attempt to provide a clean way for user mode processes 181to implement various IP tricks like address translation, but it 182could be cleaner, and it is too dependent on 183.Xr ipfw 8 . 184.Pp 185It is questionable whether incoming fragments should be reassembled 186before being diverted. 187For example, if only some fragments of a 188packet destined for another machine do not get routed through the 189local machine, the packet is lost. 190This should probably be 191a settable socket option in any case. 192