From cbf73923434db8f38f74ee36d9e8470a7c37e63a Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Tue, 18 Feb 2025 11:54:14 +1100 Subject: [PATCH] use the term "block list" consistently --- README.adoc | 102 +++++++++++++++++++++++----------------- doc/blockdomains.8.adoc | 4 +- src/blockdomains.c | 2 +- 3 files changed, 61 insertions(+), 47 deletions(-) diff --git a/README.adoc b/README.adoc index 4b0a02e..6fe912d 100644 --- 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 diff --git a/doc/blockdomains.8.adoc b/doc/blockdomains.8.adoc index 408546a..b7bf511 100644 --- 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 0d551c5..046e592 100644 --- 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(); -- 2.39.5