From a15415b1a283ad2a00fd261d7ff74ba7ab014d56 Mon Sep 17 00:00:00 2001
From: Daenney <daenney@users.noreply.github.com>
Date: Wed, 3 Jan 2024 11:14:38 +0100
Subject: [PATCH] [docs] Describe how to block IPs using a firewall (#2459)

* [docs] Describe how to block IPs using a firewall

This adds some documentation on how to block one, multiple or whole IP
ranges using the firewall. This can be helpful to protect from DDoS
attacks or block certain parties from being able to communicate with
your instance at all.

* [docs] Fix indenting of nft rule

* [docs] Split iptables and nftables into sections
---
 docs/advanced/security/firewall.md | 83 ++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/docs/advanced/security/firewall.md b/docs/advanced/security/firewall.md
index d2bb72e58..29f07d41c 100644
--- a/docs/advanced/security/firewall.md
+++ b/docs/advanced/security/firewall.md
@@ -88,3 +88,86 @@ For fail2ban, you can use the following regex, which triggers fail2ban on failed
 ```regex
 statusCode=401 path=/auth/sign_in clientIP=<HOST> .* msg=\"Unauthorized:
 ```
+
+## IP blocking
+
+GoToSocial implements rate-limiting in order to try and protect your instance from one party taking up all your processing capacity. However, if you know this traffic isn't legitimate or coming from an instance you don't wish to federate with anyway, you can block the IP(s) the traffic is originating from instead and spare GoToSocial from having to do any work.
+
+### Linux
+
+Blocking IPs is done with iptables or nftables. If you're using a firewall frontend like UFW or firewalld, use their facilities to block an IP.
+
+In iptables, people tend to add a `DROP` rule for an IP in the `filter` table on the `INPUT` chain. On nftables, it's often done on a table with a chain with the `ip` or `ip6` address family. In both those cases the kernel has already done a lot of unnecessary processing of the incoming traffic, just for it to then be blocked by an IP match.
+
+When using iptables, this can be done more effectively using the `mangle` table and the `PREROUTING` chain. You can check this blog post on [how that works in iptables][iptblock]. For nftables, you want to block using [the `netdev` family][nftnetdev] instead.
+
+[iptblock]: https://javapipe.com/blog/iptables-ddos-protection/
+[nftnetdev]: https://wiki.nftables.org/wiki-nftables/index.php/Nftables_families#netdev
+
+#### iptables
+
+An example of blocking an IP using `iptables`:
+
+```
+iptables -t mangle -A PREROUTING -s 1.0.0.0/8 -j DROP
+ip6tables -t mangle -A PREROUTING -s fc00::/7 -j DROP
+```
+
+When using iptables, adding many rules slows things down significantly, including reloading the firewall when adding/removing rules. Since you may wish to block many IP addresses, use [the `ipset` module][ipset] and add a single block rule for the set instead.
+
+[ipset]: https://ipset.netfilter.org/ipset.man.html
+
+Start by creating your sets and adding some IPs to them:
+
+```
+ipset create baddiesv4 hash:ip family inet
+ipset create baddiesv6 hash:ip family inet6
+
+ipset add baddiesv4 1.0.0.0/8
+ipset add baddiesv6 fc00::/7
+```
+
+Then, update your iptables rules to target the set instead:
+```
+iptables -t mangle -A PREROUTING -m set --match-set baddiesv4 src -j DROP
+ip6tables -t mangle -A PREROUTING -m set --match-set baddiesv6 src -j DROP
+```
+
+#### nftables
+
+For nftables, you can use something like:
+
+```
+table netdev filter {
+    chain ingress {
+        set baddiesv4 {
+            type ipv4_addr
+            flags interval
+            elements = { \
+                1.0.0.0/8, \
+                2.2.2.2/32 \
+            }
+        }
+        set baddiesv6 {
+            type ipv6_addr
+            flags interval
+            elements = { \
+                2620:4f:8000::/48, \
+                fc00::/7 \
+            }
+        }
+
+        type filter hook ingress device <interface name> priority -500;
+        ip saddr @baddiesv4 drop
+        ip6 saddr @baddiesv6 drop
+    }
+}
+```
+
+### BSDs
+
+When using pf, you can create a persistent table, typically named `<badhosts>`, to which you add the IP addresses you want to block. Tables can also read from other files, so it's possible to keep the list of IPs outside of your main `pf.conf`.
+
+An example of how to do this can be found [in the pf manual][manpf].
+
+[manpf]: https://man.openbsd.org/pf.conf#TABLES