Configuration

Blocking

Supports blocking of ads, malware, adult content, dating & social media sites, video streaming platforms, and other content.

Blocking can be done network-wide or per device group:

groups:
  # not specifying devices blocks on the entire network
  all:
    block:
      - ads
      - malware
      - adult

  screens:
    devices:
      - phone
      - laptop
      - tv

Blocking can also be scheduled so that certain content is only blocked at certain times:

schedules:
  bedtime:
    apply_to:
      - screens
    when:
      - days: ["sun", "mon", "tue", "wed", "thur", "fri", "sat"]
        periods:
        - start: "22:00"
          end: "06:00"
    block:
      - social-media
      - video-streaming
      - gaming
      - dating

For now, rDNS queries for private IP ranges that reach the resolver are always blocked.

Caching

Supports caching of DNS records for up to the record's TTL. This can then be served to other devices in the network thus speeding up DNS lookups.

But, DNS records on the internet use ridicuously low TTLs. The resolver can be configured to serve stale DNS records while it refreshes/prefetches the record in the background.

Beacon DNS also "learns" your query patterns to prefetch subsequent queries before the device makes them. For instance, when github.com is queried, avatars.githubusercontent.com & github.githubassets.com usually follow. So when the resolver sees github.com, it can prefetch the next two before the device queries for them.

cache:
  capacity: 1000
  serve_stale:
    for: 5m
    with_ttl: 15s
  query_patterns:
    follow: true
    look_back: 14d

Client Lookup

Supports looking up of the client's hostname either using reverse DNS:

client_lookup:
  upstream: 100.100.100.100 # your router's IP or tailscale's MagicDNS IP
  method: rdns
  refresh_after: 1h

Or hardcoded based on the static IPs configured on your router:

client_lookup:
  clients:
    192.168.0.102: laptop
    192.168.0.103: phone

Statistics

Beacon DNS stores your queries for a configured retention period:

querylog:
  enabled: true
  log_clients: true
  retention: 90d

The querylog allows us to generate statistics and compute the query patterns.

Timezone

To change the server's timezone:

system:
  timezone: Africa/Nairobi

Sources

You can use override the default lists this way:

sources:
  update_interval: 1d
  lists:
    - name: peter-lowe:adservers
      url: https://pgl.yoyo.org/adservers/serverlist.php?hostformat=hosts
      category: ads
      action: block
      format: hosts
    - name: beacon-dns-lists:allowlists:social-media
      url: https://raw.githubusercontent.com/st3v3nmw/beacon-dns-lists/main/allowlists/social-media
      category: social-media
      action: allow
      format: domains

The format can either be domains or hosts.

Allowlists have higher precedence than blocklists to remove false positives from a category.