From: Ralph Ronnquist Date: Sat, 15 Feb 2025 23:56:53 +0000 (+1100) Subject: converted from markdown X-Git-Tag: 0.1~20 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=053bc349a2e7ec39a8988ba627d43834d336053a;p=rrq%2Fnfblocker.git converted from markdown --- diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..c875365 --- /dev/null +++ b/README.adoc @@ -0,0 +1,72 @@ += Blacklist based domain name filtering + +The `nfblocker` utility is a blacklist based network traffic filter +for `iptables` via `libnetfilter-queue`. It applies to HTTP and SSL +traffic for recognizing and dropping packets that are directed to +blacklisted domain names. + +== Dendencies + +Operationally `nfblocker` depends on the `libnetfilter-queue-dev` and +`iptables` packages, and for building, you'll also need a C build +environment including `make`. + +The blacklist format is that of squidblacklist.org, which you'll need +to acquire separately. + +== Build and Install + +`nfblocker` is distributed in a tar file, which should be unpacked at +its future residence; e.g., as /usr/local/src/nfblocker-1.0.0. Then +`cd` into that directory and type: + +> `# make` + +This will build the binary filter, and install the control script as +`/usr/local/sbin/nfblocker.sh`. Edit the Makefile to install +elsewhere. + +== Setup and Confguration + +The residence has a directory `acl` that is intended to hold all +available access control lists, and a directory `blocked` that should +be set up with links to the access control list files to use. For +example: + +> `# ( cd blocked && ln -s ../acl/youtube-google-videos.acl )` + +That command will set up `youtube-google-videos.acl` to be an included +blacklist. Do the opposite to remove; for example: + +> `# rm blocked/youtube-google-videos.acl` + +== Running + +The `nfblocker` is started with the following command: + +> `# nfblocker.sh start` + +With the `start` argument, the script adds appropriate `iptables` +rules to use direct certain traffic to net-filter queue 99, and it +starts a background process fot that filtering. + +> `# nfblocker.sh reload` + +With the `reload` argument, the control script stops and restarts the +filter without changing `iptables` rules. + +> `# nfblocker.sh stop` + +With the `stop` argument, the control script removes the `iptables` +rules and terminates the filtering process. + +== Technical Detail + +The filtering uses the given lists of domain names for rejecting +packets. It recognizes HTTP message headers and SSL certificate +requests, from where it picks out the targeted domain name. If that +name is blacklised or in a blacklisted domain, then the packet is +rejected. + +The filtering also uses a fixed size decision cache, so that +subsequent decisions for the same target can be made quickly.