Tiny replacement for piHole DNS filter
Go to file
bloved e2a625a92e if the DNS response Rcode contains an error the cache expires after just 10 seconds.
this should limit the cache in case of temporary upstream DNS errors.
2021-09-16 09:40:03 +02:00
vendor first commit 2020-10-08 22:14:07 +02:00
.gitignore first commit 2020-10-08 22:14:07 +02:00
00.database.go - added simple stats python script 2021-05-11 10:32:48 +02:00
00.memory.go first commit 2020-10-08 22:14:07 +02:00
01.conf.go - added simple stats python script 2021-05-11 10:32:48 +02:00
01.dnscheck.go first commit 2020-10-08 22:14:07 +02:00
01.killfile.go - added simple stats python script 2021-05-11 10:32:48 +02:00
01.stats.go - stats: if "SET" to zero, stat is removed 2021-01-14 00:20:23 +01:00
02.cache.go if the DNS response Rcode contains an error the cache expires after just 10 seconds. 2021-09-16 09:40:03 +02:00
Dockerfile.amd64 - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
Dockerfile.arm32v7 - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
Dockerfile.arm64v8 - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
LICENSE - added simple stats python script 2021-05-11 10:32:48 +02:00
README.md - added whitelist documentation 2021-05-11 10:36:00 +02:00
adlist_hosts.go - single/double and local lists: ignore blank/comment lines 2021-01-15 13:28:15 +01:00
adlist_single.go - single/double and local lists: ignore blank/comment lines 2021-01-15 13:28:15 +01:00
config.json - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
config.sample.json - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
dns-upstream.txt first commit 2020-10-08 22:14:07 +02:00
dns_client.go - BUG FIX: preserving DNS RCode in Zabov responses (SetReply(query) resets it to RcodeSuccess) 2021-01-29 19:47:01 +01:00
dns_handler.go - added simple stats python script 2021-05-11 10:32:48 +02:00
go.mod first commit 2020-10-08 22:14:07 +02:00
go.sum first commit 2020-10-08 22:14:07 +02:00
hostfile.go - added simple stats python script 2021-05-11 10:32:48 +02:00
main.go - added simple stats python script 2021-05-11 10:32:48 +02:00
stats.py - added simple stats python script 2021-05-11 10:32:48 +02:00
urls-domains.txt - FIX: optional settings were not optional 2021-01-17 15:28:20 +01:00
urls-hosts.txt first commit 2020-10-08 22:14:07 +02:00
urls-local.txt first commit 2020-10-08 22:14:07 +02:00

README.md

zabov

Tiny replacement for piHole DNS filter

Still Work in progress, usable.

Idea is to produce a very simple, no-web-interface , IP DNS blocker.

INSTALL

Zabov requires golang 1.13 or later.

git clone https://git.keinpfusch.net/Loweel/zabov.git
cd zabov
go get
go build -mod=vendor

Then, edit config.json: please notice config.json must be in the same folder of the executable you run.

Just a few words about "singlefilters" and "doublefilters":

Data must be downloaded from URLs of blacklist mantainers.They may come in different formats.

There are two kinds of blacklists:

One is the format zabov calls "singlefilter", where we find a single column , full of domains:

domain1.com
domain2.com
domain3.com

The second is the format zabov calls "doublefilter" (a file in "/etc/hosts" format, to be precise), where there is an IP, usually localhost or 0.0.0.0 and then the domain:

127.0.0.1 domain1.com
127.0.0.1 domain2.com
127.0.0.1 domain3.com

This is why configuration file has two separated items.

Minimal config file should look like:

{
    "zabov":{
        "port":"53", 
        "proto":"udp", 
        "ipaddr":"0.0.0.0",
        "cachettl": 1,
        "killfilettl": 12,
        "debug:"false"
    },
    "configs":{
        "default":{
            "upstream":"./dns-upstream.txt",
            "singlefilters":"./urls-domains.txt",
            "doublefilters":"./urls-hosts.txt", 
            "blackholeip":"127.0.0.1",
            "hostsfile":"./urls-local.txt",
            "whitelist":"./whitelist.txt",
            "cache":true
        },
    }
}

Global zabov settings:

  • port is the port number. Usually is 53, you can change for docker, if you like
  • proto is the protocol. Choices are "udp", "tcp", "tcp/udp"
  • ipaddr is the port to listen to. Maybe empty, (which will result in listening to 0.0.0.0) to avoid issues with docker.
  • cachettl: amount of time the cache is kept (in hours)
  • killfilettl: refresh time for killfiles
  • debug: if set to "true" Zabov prints verbose logs, such as config selection and single DNS requests

configs:

  • contains multiple zabov configuration dictionaries. "default" configuration name is mandatory
  • upstream: file containing all DNS we want to query : each line in format IP:PORT
  • singlefilters: name of the file for blacklists following the "singlefilter" schema.(one URL per line)
  • doublefilters: name of the file, for blacklists following the "doublefilter" schema.(one URL per line)
  • blackholeip: IP address to return when the IP is banned. This is because you may want to avoid MX issues, mail loops on localhost, or you have a web server running on localhost
  • hostsfile: path where you keep your local blacklist file : this is in the format "singlefilter", meaning one domain per line, unlike hosts file.
  • whitelist: path where you keep your local whitelist file : this is in the format "singlefilter", meaning one domain per line, unlike hosts file.
  • cache: if set to false disable the cache for this configuration. Boolean, defaults true

Advanced configuration includes support for multiple configurations based on IP Source and timetables:

{
    "zabov":{
        "port":"53", 
        "proto":"udp", 
        "ipaddr":"0.0.0.0",
        "cachettl": 1,
        "killfilettl": 12,
        "debug":"false",
        "timetable":"tt_default"
    },
    "localresponder":{
        "responder":"192.168.178.1:53",
        "localdomain":"fritz.box"
    },
    "ipaliases":{
        "pc8":"192.168.178.29",
        "lg-tv":"192.168.178.10",
        "localhost":"127.0.0.1"
    },
    "ipgroups":[
        {
            "ips":["localhost", "::1", "192.168.178.30", "192.168.178.31", "pc8"],
            "cfg":"",
            "timetable":"tt_children"
        },
        {
            "ips":["lg-tv"],
            "cfg":"tv",
            "timetable":""
        }
    ],
    "timetables":{
        "tt_children":{
            "tables":[{"times":"00:00-05:00;8:30-12:30;18:30-22:59", "days":"Mo;Tu;We;Th;Fr;Sa;Su"}],
            "cfgin":"children_restricted",
            "cfgout":"default"
        }
        "tt_default":{
            "tables":[{"times":"8:30-22:30", "days":"Su"}],
            "cfgin":"children",
            "cfgout":"default"
        }
    },
    "configs":{
        "default":{
            "upstream":"./dns-upstream.txt",
            "singlefilters":"./urls-domains.txt",
            "doublefilters":"./urls-hosts.txt", 
            "blackholeip":"127.0.0.1",
            "hostsfile":"./urls-local.txt",
            "whitelist":"./whitelist.txt",
        },
        "children":{
            "upstream":"./dns-upstream-safe.txt",
            "singlefilters":"./urls-domains.txt",
            "doublefilters":"./urls-hosts.txt", 
            "blackholeip":"127.0.0.1",
            "hostsfile":"./urls-local.txt",
            "whitelist":"./whitelist.txt",
        },
        "children_restricted":{
            "upstream":"./dns-upstream-safe.txt",
            "singlefilters":"./urls-domains-restricted.txt",
            "doublefilters":"./urls-hosts-restricted.txt", 
            "blackholeip":"127.0.0.1",
            "hostsfile":"./urls-local.txt",
            "whitelist":"./whitelist.txt",
        },
        "tv":{
            "upstream":"./dns-upstream.txt",
            "singlefilters":"",
            "doublefilters":"", 
            "blackholeip":"127.0.0.1",
            "hostsfile":"",
            "whitelist":"",
            "cache":false
        }
    }
}

Global zabov settings:

  • timetable: sets the global/default timetable. This table will be used for any client that is not already included in an IP group

localresponder:

  • allows to set a local DNS to respond for "local" domains. A domain name is handled as "local" if dosen't contains "." (dots) or if it ends with a well known prefix, such as ".local". Note: the cache is not used for local responder.
  • responder: is the local DNS server address in the IP:PORT format.
  • localdomain: is the suffix for local domain names. All domains ending with this prefix are resolved by local responder

ipaliases: a dictionary of IPs

  • each entry in this dictionary define a domain-alias name and his IP address. It works as replacement of /etc/hosts file.
  • each entry is used by Zabov to resolve that names and to replace any value in the ipgroups.ips array.

timetables: a dictionary of timetable dictionaries

  • allow to define timetables in the format "time-ranges" and "days-of-week"
  • tables: contain an array of dictionaries, each defining a time rule.
    • each table is a dictinary containing "time" and "days" values
    • time: is a string in the form "start:time1-stop:time1;start:time2-stop:time2..."
    • days: is a string containing semicolon separated day names to apply the rule such as "Mo;Tu;We;Th;Fr"
      • days names are: "Mo", "Tu" "We", "Th", "Fr", "Sa", "Su"
      • empty value means all week-days You can define complex time rules using more than one entry in this dictionay
  • cfgin: is the name of the configuration to apply if current time is "inside" the timetable
  • cfgout: is the name of the configuration to apply if current time is "outside" the timetable

ipgroups: an array of ipgroup dictionaries

  • let you define a set of IP addresses that shall use a configuration other than "default"
  • ips: is an array of strings, each containing an ip address or a name defined in the "ipaliases" config branch
  • cfg: is a string containing the name of the configuration to be used for this group; ignored if timetable is also defined
  • timetable: is a string containing the name of the tiemtable to be aplied to this group

DOCKER

Multistage Dockerfiles are provided for AMD64, ARMv7, ARM64V8

NOTE: you shall use TZ env var to change docker image timezone. TZ defaults to CET.

TODO:

  • caching
  • monitoring port