dnsp

README

dnsp: A DNS Proxy

dnsp is a lightweight but powerful DNS server. Queries are blocked or resolved based on a blacklist or a whitelist. Wildcard host patterns are supported (e.g. *.com) as well as hosted, community-managed hosts files. Ideal for running on mobile devices or embedded systems, given its low memory footprint and simple web interface.

Installation

$ go get -u github.com/gophergala/dnsp/...

Example Usage

• Forward all queries to Google's public nameservers:

$ sudo dnsp --resolve 8.8.4.4,8.8.8.8

• Use a community-managed blacklist from hosts-file.net and check it hourly for changes:

$ sudo dnsp --blacklist=http://hosts-file.net/download/hosts.txt --poll 1h

• Block everything except Wikipedia:

$ cat > /etc/dnsp.whitelist << EOF
*.wikipedia.org
*.wikimedia.org
wikipedia.org
wikimedia.org
EOF

$ sudo dnsp -r 8.8.8.8 --whitelist=/etc/dnsp.whitelist

Advanced Usage

$ dnsp -h
NAME:
   dnsp - DNS proxy with whitelist/blacklist support

USAGE:
   dnsp [global options] command [command options] [arguments...]

VERSION:
   0.9.2

COMMANDS:
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --net, -n "udp"          listen protocol (‘tcp’ or ‘udp’) [$DNSP_NET]
   --listen, -l ":dns"      listen address (host:port, host or :port) [$DNSP_BIND]
   --resolve, -r "8.8.4.4"  comma-separated list of name servers (host:port or host) [$DNSP_SERVER]
   --whitelist, -w          URL or path to file containing whitelisted hosts [$DNSP_WHITELIST]
   --blacklist, -b          URL or path to file containing blacklisted hosts [$DNSP_BLACKLIST]
   --poll, -p "0"           poll the whitelist or blacklist for updates [$DNSP_POLL]
   --http, -t               start a web-based UI on the given address (host:port, host or port) [$DNSP_HTTP]
   --help, -h               show help
   --version, -v            print the version

Notes:

• --listen defaults to :dns, which is equivalent to 0.0.0.0:53, meaning: listen on all interfaces, on port 53 (default DNS port).
• --resolve defaults to the list of nameservers found in /etc/resolv.conf. If no nameservers were found, or the file does not exist (e.g. on Windows), the default value will be `8.8.4.4,8.8.8.8" (Google's public DNS service).
  • However, explicitly setting --resolve to false or an empty string disables resolving completely. What that means is all queries will still be checked against the active whitelist or blacklist, but ones that would not be blocked will return a failure response (as opposed to no response).
• --whitelist and --blacklist are mutually exclusive. Setting both is an error.
• --whitelist and --blacklist files are parsed according to a simple syntax:
  • Empty lines are ignored, and # begins a single-line comment.
  • Each line can contain a single hostname to be whitelisted or blacklisted.
  • Alternatively, a line can contain a pattern like *.wikipedia.org or *.xxx.
  • Additionally, the /etc/hosts-like syntax is supported.
    • However, only lines starting with 127.0.0.1 or ::1 are taken into parsed, everything else is ignored.
    • This is for compatibility with popular, regularly updated blocklists like the ones on hosts-file.net.
• --whitelist and --blacklist support both file paths and URLs.
• --poll instructs dnsp to periodically check the whitelist or blacklist file for changes.
  • The file is only re-parsed if the file size or modification time has changed since the last read.
  • Same is true for URLs: the Content-Length and Last-Modified headers are compared to previous values before re-downloading the file.

Running with a non-root user

Because dnsp binds to port 53 by default, it requires to be run with a privileged user on most systems. To avoid having to run dnsp with sudo, you can set the setuid and setgid access right flags on the compiled executable:

sudo mkdir -p /usr/local/bin
sudo cp $GOPATH/bin/dnsp
sudo chmod ug+s /usr/local/bin/dnsp

While dnsp will still run with root privileges, at least now we can run it with a non-admin user (someone who is not in the sudoers group).

But… Why‽

Why, you ask, is a DNS proxy useful?

• It is a simple solution for blocking websites (like AdBlock).
• Does not require an HTTP proxy or a SOCKS proxy. Some apps don't like that.
• Easy to set up for mobile devices. Run dnsmasq on your router or in any embedded Linux system, and configure your home router to use it as the DNS server in DHCP responses. The blocklist will now apply to everyone on the network.
• Safer than dnsmasq for community managed hosts files. Because dnsp doesn't do any rewriting (it either blocks or proxies), you don't have to trust everyone having access to online hosts files not to redirect your bank's website to their own servers.

Documentation

Overview

Package dnsp implements a simple DNS proxy.

Queries are blocked or resolved based on a blacklist or a whitelist. Wildcard host patterns are supported (e.g. "*.com") as well as hosted, community-managed hosts files.

Example

package main

import (
	"log"

	"github.com/gophergala/dnsp"
)

func main() {
	// Create a server that listens on :1053, on all interfaces.
	// DNS queries will be proxied to Google's public nameservers.
	s, err := dnsp.NewServer(dnsp.Options{
		Bind:    ":1053",
		Resolve: []string{"8.8.4.4", "8.8.8.8"},
		// Block hosts listed in a community-managed file:
		Blacklist: "http://hosts-file.net/download/hosts.txt",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Remember to close it:
	defer s.Shutdown()

	// Start accepting DNS queries:
	if err := s.ListenAndServe(); err != nil {
		log.Fatal(err)
	}
}

Index

• func Asset(name string) ([]byte, error)
• func AssetDir(name string) ([]string, error)
• func AssetInfo(name string) (os.FileInfo, error)
• func AssetNames() []string
• func RestoreAsset(dir, name string) error
• func RestoreAssets(dir, name string) error
• func RunHTTPServer(host string, s *Server)
• type Options
• type Server
  • func NewServer(o Options) (*Server, error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Shutdown() error

Examples

• Package

Functions

func Asset

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy:

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames

func AssetNames() []string

AssetNames returns the names of the assets.

func RestoreAsset

func RestoreAsset(dir, name string) error

Restore an asset under the given directory

func RestoreAssets

func RestoreAssets(dir, name string) error

Restore assets under the given directory recursively

func RunHTTPServer

func RunHTTPServer(host string, s *Server)

Types

type Options

type Options struct {
	Net     string
	Bind    string
	Resolve []string
	Poll    time.Duration

	Whitelist string
	Blacklist string
}

Options can be passed to NewServer().

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server implements a DNS server.

func NewServer

func NewServer(o Options) (*Server, error)

NewServer creates a new Server with the given options.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe runs the server

func (*Server) Shutdown

func (s *Server) Shutdown() error

Shutdown stops the server, closing its connection.