8 .Nd kernel packet diversion mechanism
14 .Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT
16 To enable support for divert sockets, place the following lines in the
17 kernel configuration file:
18 .Bd -ragged -offset indent
19 .Cd "options IPFIREWALL"
20 .Cd "options IPDIVERT"
23 Alternatively, to load
25 as a module at boot time, add the following lines into the
28 .Bd -literal -offset indent
33 Divert sockets are similar to raw IP sockets, except that they
34 can be bound to a specific
39 The IP address in the bind is ignored; only the port
40 number is significant.
41 A divert socket bound to a divert port will receive all packets diverted
42 to that port by some (here unspecified) kernel mechanism(s).
43 Packets may also be written to a divert port, in which case they
44 re-enter kernel IP packet processing.
46 Divert sockets are normally used in conjunction with
48 packet filtering implementation and the
51 By reading from and writing to a divert socket, matching packets
52 can be passed through an arbitrary ``filter'' as they travel through
53 the host machine, special routing tricks can be done, etc.
55 Packets are diverted either as they are ``incoming'' or ``outgoing.''
56 Incoming packets are diverted after reception on an IP interface,
57 whereas outgoing packets are diverted before next hop forwarding.
59 Diverted packets may be read unaltered via
64 In the latter case, the address returned will have its port set to
65 some tag supplied by the packet diverter, (usually the ipfw rule number)
66 and the IP address set to the (first) address of
67 the interface on which the packet was received (if the packet
70 (if the packet was outgoing).
71 The interface name (if defined
72 for the packet) will be placed in the 8 bytes following the address,
75 Writing to a divert socket is similar to writing to a raw IP socket;
76 the packet is injected ``as is'' into the normal kernel IP packet
79 and minimal error checking is done.
80 Packets are distinguished as either incoming or outgoing.
83 is used with a destination IP address of
85 then the packet is treated as if it were outgoing, i.e., destined
86 for a non-local address.
87 Otherwise, the packet is assumed to be
88 incoming and full packet routing is done.
90 In the latter case, the
91 IP address specified must match the address of some local interface,
93 must be found after the IP address.
94 If an interface name is found,
95 that interface will be used and the value of the IP address will be
96 ignored (other than the fact that it is not
98 This is to indicate on which interface the packet
101 Normally, packets read as incoming should be written as incoming;
102 similarly for outgoing packets.
103 When reading and then writing back
104 packets, passing the same socket address supplied by
108 simplifies things (see below).
110 The port part of the socket address passed to the
112 contains a tag that should be meaningful to the diversion module.
116 the tag is interpreted as the rule number
118 rule processing should restart.
120 Packets written into a divert socket
123 re-enter the packet filter at the rule number
124 following the tag given in the port part of the socket address, which
125 is usually already set at the rule number that caused the diversion
126 (not the next rule if there are several at the same number).
128 is altered to indicate an alternative re-entry point, care should be taken
129 to avoid loops, where the same packet is diverted more than once at the
132 If a packet is diverted but no socket is bound to the
135 is not enabled or loaded in the kernel, the packet is dropped.
137 Incoming packet fragments which get diverted are fully reassembled
138 before delivery; the diversion of any one fragment causes the entire
139 packet to get diverted.
140 If different fragments divert to different ports,
141 then which port ultimately gets chosen is unpredictable.
143 Note that packets arriving on the divert socket by the
146 action are delivered as-is and packet fragments do not get reassembled
149 Packets are received and sent unchanged, except that
150 packets read as outgoing have invalid IP header checksums, and
151 packets written as outgoing have their IP header checksums overwritten
152 with the correct value.
153 Packets written as incoming and having incorrect checksums will be dropped.
154 Otherwise, all header fields are unchanged (and therefore in network order).
156 Binding to port numbers less than 1024 requires super-user access, as does
157 creating a socket of type SOCK_RAW.
159 Writing to a divert socket can return these errors, along with
160 the usual errors possible when writing raw packets:
163 The packet had an invalid header, or the IP options in the packet
164 and the socket options set were incompatible.
165 .It Bq Er EADDRNOTAVAIL
166 The destination address contained an IP address not equal to
168 that was not associated with any interface.
178 .An Archie Cobbs Aq archie@FreeBSD.org ,
179 Whistle Communications Corp.
181 This is an attempt to provide a clean way for user mode processes
182 to implement various IP tricks like address translation, but it
183 could be cleaner, and it is too dependent on
186 It is questionable whether incoming fragments should be reassembled
187 before being diverted.
188 For example, if only some fragments of a
189 packet destined for another machine do not get routed through the
190 local machine, the packet is lost.
191 This should probably be
192 a settable socket option in any case.