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