README.md

   1 # Blacklist based domain name filtering
   2
   3 The `nfblocker` utility is a blacklist based network traffic filter
   4 for `iptables` via `libnetfilter-queue`. It applies to HTTP and SSL
   5 traffic for recognizing and dropping packets that are directed to
   6 blacklisted domain names.
   7
   8 ## Dendencies
   9
  10 Operationally `nfblocker` depends on the `libnetfilter-queue-dev` and
  11 `iptables` packages, and for building, you'll also need a C build
  12 environment including `make`.
  13
  14 The blacklist format is that of squidblacklist.org, which you'll need
  15 to acquire separately.
  16
  17 ## Build and Install
  18
  19 `nfblocker` is distributed in a tar file, which should be unpacked at
  20 its future residence; e.g., as /usr/local/src/nfblocker-1.0.0. Then
  21 `cd` into that directory and type:
  22
  23 > `# make`
  24
  25 This will build the binary filter, and install the control script as
  26 `/usr/local/sbin/nfblocker.sh`. Edit the Makefile to install
  27 elsewhere.
  28
  29 ## Setup and Confguration
  30
  31 The residence has a directory `acl` that is intended to hold all
  32 available access control lists, and a directory `blocked` that should
  33 be set up with links to the access control list files to use. For
  34 example:
  35
  36 > `# ( cd blocked && ln -s ../acl/youtube-google-videos.acl )`
  37
  38 That command will set up `youtube-google-videos.acl` to be an included
  39 blacklist. Do the opposite to remove; for example:
  40
  41 > `# rm blocked/youtube-google-videos.acl`
  42
  43 ## Running
  44
  45 The `nfblocker` is started with the following command:
  46
  47 > `# nfblocker.sh start`
  48
  49 With the `start` argument, the script adds appropriate `iptables`
  50 rules to use direct certain traffic to net-filter queue 99, and it
  51 starts a background process fot that filtering.
  52
  53 > `# nfblocker.sh reload`
  54
  55 With the `reload` argument, the control script stops and restarts the
  56 filter without changing `iptables` rules.
  57
  58 > `# nfblocker.sh stop`
  59
  60 With the `stop` argument, the control script removes the `iptables`
  61 rules and terminates the filtering process.
  62
  63 ## Technical Detail
  64
  65 The filtering uses the given lists of domain names for rejecting
  66 packets. It recognizes HTTP message headers and SSL certificate
  67 requests, from where it picks out the targeted domain name. If that
  68 name is blacklised or in a blacklisted domain, then the packet is
  69 rejected.
  70
  71 The filtering also uses a fixed size decision cache, so that
  72 subsequent decisions for the same target can be made quickly.