Skip to content
Resolver (DNS) cache daemon.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
AUR @ 5583eb3
cmd
doc doc: update benchmark output with latest commit Mar 22, 2019
scripts
testdata
.gitignore
.gitmodules
CHANGELOG.adoc
LICENSE rescached: DNS resolver cache daemon Aug 19, 2018
Makefile make: remove lint task from build and debug Mar 2, 2019
README.adoc README: update documentation on running DNS over HTTPS Mar 2, 2019
caches.go
caches_test.go
cacheslist.go cacheslist: implement Stringer interface on cachesList Jan 23, 2019
cacheslist_test.go cachesList: add unit test for all functions Jan 20, 2019
cacheworker.go
cacheworker_test.go cacheworker: remove method update() Mar 2, 2019
go.mod
go.sum
listrequest.go
listrequest_test.go
listresponse.go
listresponse_test.go go.mod: update dependency github.com/shuLhan/share to v0.4.0 Mar 2, 2019
options.go
options_test.go
rescached.go
rescached_test.go
response.go
response_test.go

README.adoc

RESCACHED(1) Manual Page

NAME

rescached - DNS resolver cache daemon.

SYNOPSIS

rescached rescached.cfg

OPTIONS

rescached.cfg is rescached configuration, usually it reside in /etc/rescached/rescached.cfg.

DESCRIPTION

rescached is a daemon that caching internet name and address on local memory for speeding up DNS resolution.

rescached is not a reimplementation of DNS server like BIND.

rescached primary goal is only to caching DNS queries and answers, used by personal or small group of users, to minimize unneeded traffic to outside network.

FEATURES

List of current features,

  • Enable to handle request from UDP and TCP connections

  • Enable to forward request using UDP or TCP

  • Load and serve addresses and hostnames in /etc/hosts

  • Load and serve hosts formated files inside directory /etc/rescached/hosts.d/

  • Blocking ads and/or malicious websites through host list in /etc/rescached/hosts.d/hosts.block

  • Support loading and serving master (zone) file format from /etc/rescached/master.d

  • Integration with openresolv

  • Support DNS over HTTPS (DoH) (draft 14)

BEHIND THE DNS

When you open a website, let say kilabit.info, in a browser, the first thing that browser do is to translate name address kilabit.info into an internet address (e.g.: 103.200.4.162) so browser can make a connection to kilabit.info server.

How browser do that?

First, it will send query to one of DNS server listed in your system configuration (i.e. /etc/resolv.conf in Linux). Then, if your DNS server also "caching" the name that you requested, it will reply the answer (internet address) directly, if it is not then it will ask their parent DNS server.

+----+      +----------------+      +------------------+
| PC | <==> | ISP DNS Server | <==> | Other DNS Server | <==> ...
+----+      +----------------+      +------------------+

If you browsing frequently on the same site, hitting the refresh button, opening another page on the same website, etc; this procedures will always repeated every times, not including all external links like ads, social media button, or javascripts from an other server.

To make this repetitive procedures less occurred, you can run rescached in your personal computer. The first time the answer is received in your local computer, rescached will saved it in computer memory and any subsequent request of the same address will be answered directly by rescached.

+----+      +----------------+      +------------------+
| PC |      | ISP DNS Server | <==> | Other DNS Server | <==> ...
+----+      +----------------+      +------------------+
  ^^             ^^
  ||             ||
  vv             ||
+-----------+    ||
| rescached | <==//
+-----------+

The only request that will be send to your DNS server is the one that does not already exist in rescached cache.

HOW CACHE WORKS IN RESCACHED

This section explain the simplified version of how internal program works.

Each DNS record in cache have the time last accessed field, which defined how the cache will be ordered in memory. The last queried host-name will be at the bottom of cache list, and the oldest queried host-name will at the top of cache list.

The following table illustrate list of caches in memory,

+---------------------+------------------+
| Accessed At         | host-name        |
+---------------------+------------------+
| 2018-01-01 00:00:01 | kilabit.info     |
+---------------------+------------------+
| 2018-01-01 00:00:02 | www.google.com   |
+---------------------+------------------+
|         ...         |        ...       |
+---------------------+------------------+
| 2018-01-01 00:01:00 | www.kilabit.info |
+---------------------+------------------+

Every cache.prune_delay (e.g. 5 minutes), rescached will try to pruning old records from cache. If the accessed-at value of record in cache is less than,

	current-time + cache.threshold

(remember that "cache.threshold" value must be negative) it will remove the record from cache.

BUILDING

PREREQUISITES

COMPILING

Steps to compile from source,

	$ go get -u github.com/shuLhan/rescached-go
	$ cd ${GOPATH}/src/github.com/shuLhan/rescached-go
	$ go build ./cmd/rescached

The last command will build binary named rescached in current directory.

INSTALLATION

After program successfully build, you can install it manually by copying to system binary directory.

MANUAL INSTALLATION

  • Copy rescached configuration to system directory. We use directory "/etc/rescached" as configuration directory.

    $ sudo mkdir -p /etc/rescached
    $ sudo cp cmd/rescached/rescached.cfg /etc/rescached/
  • Copy rescached program to your system path.

    $ sudo cp -f rescached /usr/bin/
  • Create system startup script.

    If you want your program running each time the system is starting up you can create a system startup script (or system service). You can see an example for systemd service in scripts/rescached.service.

    This step is really different between each system, consult your distribution wiki, forum, or mailing-list on how to create system startup script.

POST INSTALLATION

  • Set your parent DNS server.

    Edit rescached configuration, /etc/rescached/rescached.cfg, change the value of server.parent based on your preferred DNS server.

  • Set the cache prune delay and threshold

    Edit rescached configuration, /etc/rescached/rescached.cfg, change the value of cache.prune_delay and/or cache.threshold to match your needs.

  • Set your system DNS server to point to rescached.

    In UNIX system,

    $ sudo mv /etc/resolv.conf /etc/resolv.conf.org
    $ sudo echo "nameserver 127.0.0.1" > /etc/resolv.conf
  • If you use systemd, run rescached service by invoking,

    $ sudo systemctl start rescached.service

    and if you want rescached service to run when system startup, enable it by invoking,

    $ sudo systemctl enable rescached.service

CONFIGURATION

All rescached configuration located in file /etc/rescached/rescached.cfg. See manual page of rescached.cfg(5) for more information.

MASTER FILE

Rescached support loading master file format. Unlike hosts file format, where each domain name is only mapped to type A (IPv4 address), in master file, one can define other type that known to rescached. All files defined dir.master configuration are considered as master file and will be loaded by rescached only if the config is not empty.

Example of master file,

$ORIGIN my-site.vm.
$TTL    3600

; resource record (RR) address
@ A 192.168.56.10

; resource record alias
dev CNAME @

; resource record address for other sub-domain
staging A 192.168.100.1

; resource record address for other absolute domain.
my-site.com A 10.8.0.1

Here we defined the variable origin for root domain "my-site.vm." with minimum time-to-live (TTL) to 3600 seconds. If no "$origin" variable is defined, rescached will use the file name as origin.

The "@" character will be replaced with the value of origin.

The first resource record (RR) is defining an IPv4 address for "my-site.vm." to "192.168.56.10".

The second RR add an alias for relative subdomain "dev". Domain name that does not terminated with "." are called relative, and the origin will be appended to form the absolute domain "dev.my-site.vm". In this case IP address for "dev.my-site.vm." is equal to "my-site.vm.".

The third RR define a mapping for another relative subdomain "staging.my-site.vm." to address "192.168.100.1".

The last RR define a mapping for absolute domain "my-site.com." to IP address "10.8.0.1".

For more information about format of master file see RFC 1035 section 5.

INTEGRATION WITH OPENRESOLV

rescached can detect change on file generated by resolvconf. To use this feature unset the "file.resolvconf" in configuration file and set either "dnsmasq_resolv", "pdnsd_resolv", or "unbound_conf" in "/etc/resolvconf.conf" to point to file referenced in "file.resolvconf".

For more information see rescached.cfg(5).

INTEGRATION WITH DNS OVER HTTPS

DNS over HTTPS (DoH) is the new protocol to query DNS through HTTPS layer. To enable this feature rescached must run as DoH server using the provided self-signed certificate or your own certificate.

Example configuration in rescached.cfg,

	server.doh.parent = https://cloudflare-dns.com/dns-query
	server.doh.certificate = /etc/rescached/localhost.cert.pem
	server.doh.certificate.key = /etc/rescached/localhost.key.pem

If the "server.doh.parent" is using self-signed certificate, you can set "server.doh.allow_insecure" to true.

Using the above configuration, rescached will serve DoH queries on https://localhost/dns-query. Only query to port 443 will be forwarded to "server.doh.parent". Queries to port 53, either with UDP or TCP, will be forwarded to "server.parent" name servers as usual.

This feature can be tested using Firefox Nightly by updating the configuration in "about:config" into,

	network.trr.bootstrapAddress;127.0.0.1
	network.trr.mode;3
	network.trr.uri;https://localhost/dns-query

Since we are using mode=3, the network.trr.bootstrapAddress is required so Firefox Nightly can resolve "localhost" to "127.0.0.1". If you use the provided self-signed certificate, you must import and/or enable an exception for it manually in Firefox Nightly (e.g. by opening https://localhost/dns-query in new tab and accept security risk).

To check if DoH works, first, set the debug option to 1, and restart the rescached. Open a new terminal and run sudo journalctl -xf, to show current system log. Run Firefox Nightly and open any random website. At the terminal you will see output from rescached which looks like these,

... rescached[10742]: < request:    4          - &{Name:cs2...
... rescached[10742]: - expired:  413 1548503139 &{Name:cs2...
... rescached[10742]: + update :    - 1548503139 &{Name:cs2...

If you see number "4" in request line, "< request: 4", thats indicated that request is from HTTPS connection and its working.

EXIT STATUS

Upon success, rescached will return 0, or 1 otherwise.

FILES

/etc/rescached/rescached.cfg

The rescached main configuration. This configuration will be read when program started.

/usr/share/rescached/LICENSE

License file for this software.

/var/run/rescached.pid

File where process ID of rescached will be saved when running.

NOTES

This program developed with references to,

RFC1034

Domain Names - Concepts and Facilities.

RFC1035

Domain Names - Implementation and Specification.

RFC1886

DNS Extensions to support IP version 6.

RFC2782

A DNS RR for specifying the location of services (DNS SRV)

draft-ietf-doh-dns-over-https-14

DNS Queries over HTTPS (DoH)

BUGS

rescached only know specific DNS record type,

A

A host address in IPv4

NS

An authoritative name server

CNAME

A canonical name for an alias

SOA

Start of [a zone of] authority record

MB

Mail box

MG

Mail group

NULL

Placeholders for experimental extensions

WKS

Record to describe well-known services supported by a host

PTR

Pointer to a canonical name.

HINFO

Host information

MINFO

Mail information

MX

Mail exchange

TXT

Text record

AAAA

A host address in IPv6

SRV

Service locator

OPT

This is a "pseudo DNS record type" needed to support EDNS

rescached only run and tested in Linux system. Technically, if it can compiled, it will run in any operating system.

For request of features and/or bugs report please submitted through web at https://github.com/shuLhan/rescached-go/issues.

AUTHOR

rescached is developed by Shulhan (ms@kilabit.info).

LICENSE

Copyright 2018, M. Shulhan (ms@kilabit.info). All rights reserved.

Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

SEE ALSO

rescached.cfg(5)

You can’t perform that action at this time.