193e0e116SJulian Elischer.Dd June 18, 1996 293e0e116SJulian Elischer.Dt DIVERT 4 393e0e116SJulian Elischer.Os FreeBSD 493e0e116SJulian Elischer.Sh NAME 593e0e116SJulian Elischer.Nm divert 693e0e116SJulian Elischer.Nd kernel packet diversion mechanism 793e0e116SJulian Elischer.Sh SYNOPSIS 893e0e116SJulian Elischer.Fd #include <sys/socket.h> 993e0e116SJulian Elischer.Fd #include <netinet/in.h> 1093e0e116SJulian Elischer.Ft int 1193e0e116SJulian Elischer.Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT 1293e0e116SJulian Elischer.Sh DESCRIPTION 1393e0e116SJulian Elischer.Pp 1493e0e116SJulian ElischerDivert sockets are similar to raw IP sockets, except that they 1593e0e116SJulian Elischercan be bound to a specific 1693e0e116SJulian Elischer.Nm 1793e0e116SJulian Elischerport via the 1893e0e116SJulian Elischer.Xr bind 2 1993e0e116SJulian Elischersystem call. The IP address in the bind is ignored; only the port 2093e0e116SJulian Elischernumber is significant. 2193e0e116SJulian ElischerA divert socket bound to a divert port will receive all packets diverted 2293e0e116SJulian Elischerto that port by some (here unspecified) kernel mechanism(s). 2393e0e116SJulian ElischerPackets may also be written to a divert port, in which case they 2493e0e116SJulian Elischerre-enter kernel IP packet processing. 2593e0e116SJulian Elischer.Pp 2693e0e116SJulian ElischerDivert sockets are normally used in conjunction with 2793e0e116SJulian ElischerFreeBSD's packet filtering implementation and the 2893e0e116SJulian Elischer.Xr ipfw 8 2993e0e116SJulian Elischerprogram. By reading from and writing to a divert socket, matching packets 3093e0e116SJulian Elischercan be passed through an arbitrary ``filter'' as they travel through 3193e0e116SJulian Elischerthe host machine, special routing tricks can be done, etc. 3293e0e116SJulian Elischer.Sh READING PACKETS 3393e0e116SJulian ElischerPackets are diverted either as they are ``incoming'' or ``outgoing.'' 3493e0e116SJulian ElischerIncoming packets are diverted after reception on an IP interface, 3593e0e116SJulian Elischerwhereas outgoing packets are diverted before next hop forwarding. 3693e0e116SJulian Elischer.Pp 3793e0e116SJulian ElischerDiverted packets may be read unaltered via 3893e0e116SJulian Elischer.Xr read 2 , 3993e0e116SJulian Elischer.Xr recv 2 , 4093e0e116SJulian Elischeror 4193e0e116SJulian Elischer.Xr recvfrom 2 . 4293e0e116SJulian ElischerIn the latter case, the address returned will have its port set to 4393e0e116SJulian Elischerthe divert port and the IP address set to the (first) address of 4409b4b086SMike Pritchardthe interface on which the packet was received (if the packet 4593e0e116SJulian Elischerwas incoming) or 4693e0e116SJulian Elischer.Dv INADDR_ANY 4793e0e116SJulian Elischer(if the packet was outgoing). 4893e0e116SJulian Elischer.Sh WRITING PACKETS 4993e0e116SJulian ElischerWriting to a divert socket is similar to writing to a raw IP socket; 5093e0e116SJulian Elischerthe packet is injected ``as is'' into the normal kernel IP packet 5193e0e116SJulian Elischerprocessing and minimal error checking is done. 5293e0e116SJulian ElischerPackets are written as either incoming or outgoing: 5393e0e116SJulian Elischerif 5493e0e116SJulian Elischer.Xr write 2 5593e0e116SJulian Elischeror 5693e0e116SJulian Elischer.Xr send 2 5793e0e116SJulian Elischeris used to deliver the packet, or if 5893e0e116SJulian Elischer.Xr sendto 2 5993e0e116SJulian Elischeris used with a destination IP address of 6093e0e116SJulian Elischer.Dv INADDR_ANY , 6193e0e116SJulian Elischerthen the packet is treated as if it were outgoing, i.e., destined 6293e0e116SJulian Elischerfor a non-local address. Otherwise, the packet is assumed to be 6393e0e116SJulian Elischerincoming and full packet routing is done. 6493e0e116SJulian Elischer.Pp 6593e0e116SJulian ElischerIn the latter case, the 6693e0e116SJulian ElischerIP address specified must match the address of some local interface. 6793e0e116SJulian ElischerThis is to indicate on which interface the packet ``arrived.'' 6893e0e116SJulian Elischer.Pp 6993e0e116SJulian ElischerNormally, packets read as incoming should be written as incoming; 7093e0e116SJulian Elischersimilarly for outgoing packets. When reading and then writing back 7193e0e116SJulian Elischerpackets, passing the same socket address supplied by 7293e0e116SJulian Elischer.Xr recvfrom 2 7393e0e116SJulian Elischerunmodified to 7493e0e116SJulian Elischer.Xr sendto 2 7593e0e116SJulian Elischersimplifies things. 7693e0e116SJulian Elischer.Sh LOOP AVOIDANCE 7793e0e116SJulian ElischerTo avoid having a packet sent from a divert socket rediverted back 7893e0e116SJulian Elischerto the same socket, use the 7993e0e116SJulian Elischer.Xr sendto 2 8093e0e116SJulian Elischersystem call supplying any non-zero destination port number. 8193e0e116SJulian ElischerThis indicates to 8293e0e116SJulian Elischer.Xr ipfw 8 8393e0e116SJulian Elischerand other diverting mechanisms to not divert the packet back 8493e0e116SJulian Elischerto the same socket it was written from. 8593e0e116SJulian Elischer.Pp 8693e0e116SJulian ElischerSince 8793e0e116SJulian Elischer.Xr ipfw 8893e0e116SJulian Elischerchecks incoming as well as outgoing packets, 8993e0e116SJulian Elischera packet written as incoming may get checked twice. 9093e0e116SJulian ElischerLoop avoidance will be enabled for both checks. 9193e0e116SJulian Elischer.Sh DETAILS 9293e0e116SJulian ElischerTo enable divert sockets, your kernel must be compiled with the option 9393e0e116SJulian Elischer.Dv IPDIVERT . 9493e0e116SJulian Elischer.Pp 9593e0e116SJulian ElischerIf a packet is diverted but no socket is bound to the 9693e0e116SJulian Elischerport, or if 9793e0e116SJulian Elischer.Dv IPDIVERT 9893e0e116SJulian Elischeris not enabled in the kernel, the packet is dropped. 9993e0e116SJulian Elischer.Pp 10093e0e116SJulian ElischerIncoming packet fragments which get diverted are fully reassembled 10193e0e116SJulian Elischerbefore delivery; the diversion of any one fragment causes the entire 10293e0e116SJulian Elischerpacket to get diverted. 10393e0e116SJulian ElischerIf different fragments divert to different ports, 10493e0e116SJulian Elischerthen which port ultimately gets chosen is unpredictable. 10593e0e116SJulian Elischer.Pp 10609b4b086SMike PritchardPackets are received and sent unchanged, with two exceptions: 10793e0e116SJulian Elischerread as incoming will have their IP header checksum zeroed, 10893e0e116SJulian Elischerand packets written as outgoing have their IP header checksums overwritten 10993e0e116SJulian Elischerwith the correct value. 11093e0e116SJulian ElischerPackets written as incoming and having incorrect checksums will be dropped. 11193e0e116SJulian ElischerOtherwise, all header fields are unchanged (and therefore in network order). 11293e0e116SJulian Elischer.Pp 11393e0e116SJulian ElischerBinding to port numbers less than 1024 requires super-user access. 11493e0e116SJulian Elischer.Sh ERRORS 11593e0e116SJulian ElischerWriting to a divert socket can return these errors, along with 11693e0e116SJulian Elischerthe usual errors possible when writing raw packets: 11793e0e116SJulian Elischer.Bl -tag -width Er 11893e0e116SJulian Elischer.It Bq Er EINVAL 11993e0e116SJulian ElischerThe packet had an invalid header, or the IP options in the packet 12093e0e116SJulian Elischerand the socket options set were incompatible. 12193e0e116SJulian Elischer.It Bq Er EADDRNOTAVAIL 12293e0e116SJulian ElischerThe destination address contained an IP address not equal to 12393e0e116SJulian Elischer.Dv INADDR_ANY 12493e0e116SJulian Elischerthat was not associated with any interface. 12593e0e116SJulian Elischer.El 12693e0e116SJulian Elischer.Sh SEE ALSO 12793e0e116SJulian Elischer.Xr ipfw 8 , 12893e0e116SJulian Elischer.Xr socket 2 , 12993e0e116SJulian Elischer.Xr bind 2 , 13093e0e116SJulian Elischer.Xr sendto 2 . 13193e0e116SJulian Elischer.Xr recvfrom 2 , 13293e0e116SJulian Elischer.Sh BUGS 13393e0e116SJulian ElischerThis is an attempt to provide a clean way for user mode processes 13493e0e116SJulian Elischerto implement various IP tricks like address translation, but it 13593e0e116SJulian Elischercould be cleaner, and it's too dependent on 13693e0e116SJulian Elischer.Xr ipfw 8 . 13793e0e116SJulian Elischer.Pp 13893e0e116SJulian ElischerIt's questionable whether incoming fragments should be reassembled 13993e0e116SJulian Elischerbefore being diverted. For example, if only some fragments of a 14093e0e116SJulian Elischerpacket destined for another machine don't get routed through the 14193e0e116SJulian Elischerlocal machine, the packet is lost. This should probably be 14293e0e116SJulian Elischera settable socket option in any case. 14393e0e116SJulian Elischer.Sh AUTHOR 14493e0e116SJulian ElischerArchie Cobbs <archie@whistle.com>, Whistle Communications Corp. 145