README.divert.md
1Divert Module
2=============
3
4A DAQ module for listening on BSD divert sockets. The input specification given
5to the DAQ module should be the integer value of the divert port number to
6receive and process packets on. The module is intrinsically operating in an
7inline mode as any packets that it does not return to the kernel will be
8dropped.
9
10Packets will come up to the application with a datalink type of "RAW", which
11means the packet data begins with the IP header.
12
13On FreeBSD, the IPFW firewall subsystem is used to send packets to divert
14sockets. On OpenBSD, the PF firewall subsystem is used to do so. Note that
15the PF firewall is also available on FreeBSD, but it does not support diverting
16packets like the OpenBSD implementation does.
17
18Note: If nothing is listening on the specified divert socket port, the traffic
19that was supposed to be diverted to it will be dropped.
20
21Example Setup (FreeBSD)
22-----------------------
23
24The following steps set up a FreeBSD system with two data interfaces (em1 and
25em2) and configures them as two routing interfaces with IPv4 addresses. All
26traffic that is received on either interface is sent to the divert socket on
27port 8000 and forwarded when it is received back from the userspace
28application.
29
301. Enable the firewall and configure it with the "open" template.
31
32 sysrc firewall_enable="YES"
33 sysrc firewall_type="open"
34 service ipfw restart
35
362. Give the interfaces IPv4 addresses.
37
38 ifconfig em1 172.16.1.1/24
39 ifconfig em2 172.16.2.1/24
40
413. Enable gateway (routing) functionality.
42
43 sysrc gateway_enable="yes"
44 service routing restart
45
464. Load the ipdivert kernel module if it's not compiled in (default).
47
48 kldload ipdivert
49 To make this permanent, add ipdivert_load="YES" to /boot/loader.conf.
50
515. Define an ipfw rule with an arbitrary (but low) rule ID (75) that diverts all
52traffic received on em1 and em2 to an arbitrary divert socket port (8000).
53
54 ipfw add 75 divert 8000 all from any to any in recv em1
55 ipfw add 75 divert 8000 all from any to any in recv em2
56
57Note: If you are operating in a slightly more complicated setup with NAT via a
58natd divert, you will want to add the two rules before and after the natd divert
59rule. For example, if em1 is the public interface and em2 is the internal
60interface, the snippet of the final rule set around the nat divert rule should
61look something like this:
62
63 ipfw add 45 divert 8000 all from any to any in recv em2
64 ipfw add 50 divert natd ip4 from any to any via em1
65 ipfw add 55 divert 8000 all from any to any in recv em1
66
67This will send all traffic coming in on the internal interface pre-NAT and all
68traffic coming in on the public interace post-NAT to the divert socket so that
69all traffic is using private addresses.
70
71Example Setup (OpenBSD)
72-----------------------
73
74The following steps set up a OpenBSD system with two data interfaces (em1 and
75em2) and configures them as two routing interfaces with IPv4 addresses. All
76traffic that is leaving on either interface is sent to the divert socket on
77port 8000 and forwarded when it is received back from the userspace
78application.
79
801. Configure the system to forward IPv4 packets.
81
82 sysctl net.inet.ip.forwarding=1
83
84 (You can also put that in /etc/sysctl.conf to enable on boot.)
85
862. Give the interfaces IPv4 addresses.
87
88 ifconfig em1 172.16.1.1/24
89 ifconfig em2 172.16.2.1/24
90
913. Add packet filter rules to the configuration and load them.
92
93 echo "pass out on em1 divert-packet port 8000" >> /etc/pf.conf
94 echo "pass out on em2 divert-packet port 8000" >> /etc/pf.conf
95
96 pfctl -vf /etc/pf.conf
97
98Note: With this configuration it seems like one direction of the traffic comes
99off the divert socket with bad IP checksums. I'm really not familiar enough
100with OpenBSD/PF to figure out why. This seems to be related, but it sounds
101like it should have fixed it:
102<https://lteo.net/blog/2015/01/06/dissecting-openbsds-divert-4-part-1-introduction/>
103
104Additional Resources
105--------------------
106
107* FreeBSD online handbook for IFPW: <https://www.freebsd.org/doc/handbook/firewalls-ipfw.html>
108* OpenBSD online manual for PF configuration: <https://man.openbsd.org/pf.conf.5>
109