# DHCP Protect

DHCP Protect is a userspace application that filters DHCPv4 and DHCPv6 floods to protect a DHCP server. It uses the Netfilter userspace packet queuing API.

# How it works

DHCP Protect receives every packet that enters the iptables NFQUEUE. It will count the number of queries sent by a client and if `max_pkt_per_interval` is reached within `interval` time, it will blacklist the client. While a client is blacklisted, the accounting continues, this means that when the `blacklist_time` is over and if the client continued to flood the DHCP server, the client will NOT be unblacklisted. The blacklist expiration time will be pushed forward as long as the client continues to flood.

## What is a client?
### DHCPv4
In DHCPv4 DHCP Protect will primarly look for option 82, suboption 2 (remoteID). If this is not available it will use the hardware address field.

### DHCPv6
In DHCPv6 DHCP Protect will account based on the client DUID.

# Installation
```
git clone https://git.home.spale.com/dhcp_protect.git
cd dhcp_protect
sudo apt-get install build-essential uthash-dev libnetfilter-queue-dev
make all
sudo make install
```
Note: the `make install` will automatically create, enable and start the systemd service and the `make uninstall` will stop and remove the systemd service.

# Netfilter (iptables)

iptables and ip6tables must be configured to send the DHCPv4 and/or DHCPv6 packets to DHCP Protect for forwarding decision.
Both DHCPv4 and DHCPv6 can be processed by the same instance of DHCP Protect. However, they must use the same `--queue-num` as in the `dhcp_protect.conf` configuration file.

The `--queue-bypass` will tell iptables to continue to forward packets if DHCP Protect is not running or crashed. It is strongly recommended to keep this option.

## Example IPv4
`iptables -A INPUT -p udp -m udp --dport 67 -j NFQUEUE --queue-num 67 --queue-bypass`

## Example IPv6
`ip6tables -A INPUT -p udp -m udp --dport 547 -j NFQUEUE --queue-num 67 --queue-bypass`

# Configuration
The configuration file may be tuned, but the defaults should be fine.
```
# max_pkt_per_interval
# maximum number of packets authorised per time interval.
max_pkt_per_interval=30

# interval
# measurement time interval in seconds.
interval=30

# debug
# enable debugging, warning, very verbose
debug=0

# blacklist_time
# number of seconds this client will be ignored once
# it exceeded the max_pkt_per_interval per interval
blacklist_time=55

# queue number
# refers to the queue-num of iptables.
# -A FORWARD -p udp -m udp --dport 67 -j NFQUEUE --queue-num 67 --queue-bypass
queue=67

# dryrun
# if dryrun is set to 1 it will accept all packets no matter what.
# this can be used for testing, syslog will still display the blacklisting
# actions.
# Set to 0 for production.
dryrun=0
```

# Starting / Stopping
```
root@hostname:~/# systemd <start|stop|restart> dhcp_protect
```

# Logging / Accounting

The program will log every blacklisting action to syslog (also in dryrun mode).

```
Oct 23 16:50:18 router dhcp_protect[9706]: 00000000021b: blacklisting started
Oct 23 16:52:18 router dhcp_protect[9706]: 00000000021b: blacklisting ended
```
# Copyright / License
```
   Copyright 2019 Pascal Gloor

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
```