README.html

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