converted from markdown

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
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.