xref: /freebsd/share/man/man4/divert.4 (revision 09b4b086495174c435f490488886fb8ea8d10427)
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