use the term "block list" consistently

diff --git a/README.adoc b/README.adoc
index 4b0a02ef3d673317d10349de512d86afc4c09f0a..6fe912d81e6477a91a5b1963a83c6be83133677c 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,9 +1,9 @@
-= Blocklist based domain name filtering
+= Block list based domain name filtering
 
-The `blockdomains` 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.
+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
 
@@ -11,62 +11,76 @@ Operationally `blockdomains` 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
 
-`blockdomains` is distributed in a tar file, which should be unpacked at
-its future residence; e.g., as /usr/local/src/blockdomains-1.0.0. Then
-`cd` into that directory and type:
+=== Custom build and install
 
-> `# make`
+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.
 
-This will build the binary filter, and install the control script as
-`/usr/local/sbin/blockdomains.sh`. Edit the Makefile to install
-elsewhere.
+.Illustration of custom build and install
+----
+$ mkdir here
+$ make install DESTDIR=here
+----
 
-== Setup and Confguration
+NOTE: The control and init scripts assume it installed at system root.
+They need to be edited for other installation choices.
 
-The utility has a configuration 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:
+=== Build debian package
 
-> `# ( cd blocked && ln -s ../acl/youtube-google-videos.acl )`
+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`.
 
-That command will set up `youtube-google-videos.acl` to be an included
-blacklist. Do the opposite to remove; for example:
+.Illustration of debian package build
+----
+$ git checkout debian
+$ gbp buildpackage --git-export-dir=build
+----
 
-> `# rm blocked/youtube-google-videos.acl`
+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
 
-== Running
+== Setup and Confguration
 
-The `blockdomains` is started with the following command:
+The blockdomains utility uses blocklist files that nominates 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.
 
-> `# blockdomains.sh start`
+Thus, you enable a block list `acl/foo.acl` by setting a link
+----
+/etc/blockdomains/blocked -> ../acl/foo.acl
+----
 
-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.
+== Running
 
-> `# blockdomains.sh reload`
+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.
 
-With the `reload` argument, the control script stops and restarts the
-filter without changing `iptables` rules.
+== Technical Detail
 
-> `# blockdomains.sh stop`
+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.
 
-With the `stop` argument, the control script removes the `iptables`
-rules and terminates the filtering process.
+The filtering has decision cache so that subsequent decisions for the
+same target can be made quickly.
 
-== Technical Detail
+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.
 
-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.
+== AUTHOR
 
-The filtering also uses a fixed size decision cache, so that
-subsequent decisions for the same target can be made quickly.
+Ralph Ronnquist <rrq@rrq.au>

diff --git a/doc/blockdomains.8.adoc b/doc/blockdomains.8.adoc
index 408546aae64ede1cb5a4ab5760ab1c86878284fe..b7bf511ebb1d5179f1f85f904a86a3284bdd9116 100644 (file)
--- a/doc/blockdomains.8.adoc
+++ b/doc/blockdomains.8.adoc
@@ -11,10 +11,10 @@ blockdomains __blocklistfile__+
 
 == DESCRIPTION
 
-The **blockdomains** utility is a blacklist based network traffic
+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
-blacklisted domain names.
+listed domain names.
 
 == SEE ALSO
 

diff --git a/src/blockdomains.c b/src/blockdomains.c
index 0d551c5daa07c28cdd757f7ea0806eb761550e01..046e5923f9a9f8a659ade6ebb31f10d1b58d15e9 100644 (file)
--- a/src/blockdomains.c
+++ b/src/blockdomains.c
@@ -271,7 +271,7 @@ int main(int argc, char **argv) {
     start_domain_database_loading();
     int n = 1;
     for ( ; n < argc; n++ ) {
-       fprintf( stderr, "Loading blacklist %s\n", argv[ n ] );
+       fprintf( stderr, "Loading block list %s\n", argv[ n ] );
        load_domains( argv[ n ] );
     }
     end_domain_database_loading();