= Block list based domain name filtering

The `blockdomains` utility is a block list 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
listed domain names.

== Dendencies

Operationally `blockdomains` depends on the `libnetfilter-queue-dev` and
`iptables` packages, and for building, you'll also need a C build
environment including `make`.

== Build and Install

=== Custom build and install

The `Makefile` offers an `install` target that makes use of a
`DESTDIR` variable to nominate a root directory for installation. The
prerequies for this are a gcc build environment, and that the
`libnetfilter_queue` library is duly installed.

.Illustration of custom build and install
----
$ mkdir here
$ make install DESTDIR=here
----

NOTE: The control and init scripts assume it installed at system root.
They need to be edited for other installation choices.

=== Build debian package

This project has a `debian` branch that is set up for building a
debian package in a debian build environment. The prerequesites are
obtained by installing the debian package `git-buildpackage`.

.Illustration of debian package build
----
$ git checkout debian
$ gbp buildpackage --git-export-dir=build
----

When the illustration build succeeds, it results in a `.deb` file in
the newly created `build` directory, and there are also
some  other useful files

== Setup and Confguration

The blockdomains utility uses block list files that nominate the
domains to block. Control scripting supports the notion of a
configuration root directory `/etc/blockdomains/` with two sub
direcotries `acl/` and `blocked/`. The idea is that `acl/` contains
all the block list files and that `blocked/` is set up with links into
`acl/` files for the __enabled__ block list files.

Thus, you enable a block list `acl/foo.acl` by setting a link
----
/etc/blockdomains/blocked -> ../acl/foo.acl
----

== Running

The `blockdomains` utility has control scripting to either operate it
manually via the `blockdomainsctl` script, or as a system service via
the `init/blockdomains` service control script.

== Technical Detail

The filtering uses the given lists of domain names for rejecting
packets. It inspects all packets so as to recognize HTTP message
headers and SSL certificate requests and then pick out the targeted
domain name. If that name is listed or a sub domain of a listed
domain, then the packet is rejected. Doing so "disturbs" the
communication with the domain to effectively block it.

The filtering has decision cache so that subsequent decisions for the
same target can be made quickly.

NOTE: It is technically possible but highly unlikely to run into
'false positives' in the filtering. The result would then be an
unexpected interruption and break of a TCP communication.

== AUTHOR

Ralph Ronnquist <rrq@rrq.au>
