Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/shulhan/rescached

[mirror] Resolver (DNS) cache daemon. See https://sr.ht/~shulhan/rescached
https://github.com/shulhan/rescached

cache dns golang resolver

Last synced: 17 days ago
JSON representation

[mirror] Resolver (DNS) cache daemon. See https://sr.ht/~shulhan/rescached

Awesome Lists containing this project

README 

        
// SPDX-FileCopyrightText: 2018 M. Shulhan 

// SPDX-License-Identifier: GPL-3.0-or-later

= RESCACHED(1)

M. Shulhan 

8 February 2022

:doctype: manpage

:mansource: rescached

:manmanual: rescached

:toc:



== NAME



rescached - DNS resolver cache daemon.



== SYNOPSIS



rescached [-config '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 host names in `/etc/hosts`

* Load and serve hosts formatted files inside directory

  `/etc/rescached/hosts.d/`

* Blocking ads and/or malicious websites through host list in

  `/etc/rescached/hosts.d/`

* Support loading and serving zone file format from

  `/etc/rescached/zone.d`

* Integration with openresolv

* Support DNS over TLS (DoH) (RFC 7858)

* Support DNS over HTTPS (DoH) (RFC 8484)



=== 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 (for example to 18.136.35.199) 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 (for example, `/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 JavaScript 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



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` (let say every 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



* https://golang.org[Go compiler]

* https://git-scm.com[git, version control system]

* asciidoc, to generate manual pages

* systemd or system V init tool for service on Linux



=== COMPILING



Steps to compile from source,



----

$ go get -u git.sr.ht/~shulhan/rescached

$ cd ${GOPATH}/src/git.sr.ht/~shulhan/rescached

$ 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).

For OS using systemd, you can see an example for `systemd` service in

`scripts/rescached.service`.

For system using launchd (macOS), you can see an example in

`scripts/info.kilabit.rescached.plist`.



This step could be different between systems, consult your distribution

wiki, forum, or mailing-list on how to create system startup script.



====  AUTOMATIC INSTALLATION ON LINUX



Automatic installation on Linux require systemd.

Run the following command



	$ sudo make install



to setup and copies all required files and binaries to system directories.

You can then start the rescached service using systemd,



	$ sudo systemctl start rescached



====  AUTOMATIC INSTALLATION ON MACOS



Run the following command



	$ sudo make install-macos



to setup and copies all required files and binaries to system directories.

You can then load the rescached service using launchd,



	$ sudo launchctl load info.kilabit.rescached



==== POST INSTALLATION



* Set your parent DNS server.

+

Edit rescached configuration, `/etc/rescached/rescached.cfg`, change the value

of `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.



=== ZONE FILE



Rescached support loading zone file format.

Unlike hosts file format, where each domain name is only mapped to type A

(IPv4 address), in zone file, one can define other type that known to

rescached.

All files defined `zone.d` configuration are considered as zone file and

will be loaded by rescached only if the configuration is not empty.



Example of zone 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's value.



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 zone 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.

Rescached support serving DNS over HTTPS or as client to parent DoH

nameservers.

To enable this feature rescached provided TLS certificate and private key.



Example configuration in *rescached.cfg*,



----

[dns "server"]

parent = https://kilabit.info/dns-query

tls.certificate = /etc/rescached/localhost.cert.pem

tls.private_key = /etc/rescached/localhost.key.pem

tls.allow_insecure = false

----



If the parent nameserver is using self-signed certificate, you can set

"tls.allow_insecure" to true.



Using the above configuration, rescached will serve DoH queries on

https://localhost/dns-query on port 443 and UDP queries on port 53.

All queries to both locations will be forwarded to parent nameserver.



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 (for example. 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[808]: dns: ^ DoH https://kilabit.info/dns-query 41269:&{Name:id.wikipedia.org Type:A}                                                                         

... rescached[808]: dns: < UDP 45873:&{Name:id.wikipedia.org Type:AAAA}                                                                                                     

... rescached[808]: dns: + UDP 41269:&{Name:id.wikipedia.org Type:A}     

----



If you see number "4" in request line, "< request: 4", thats indicated that

request is from HTTPS connection and its working.



== WEB USER INTERFACE



The rescached service provide a web user interface that can be accessed at

http://127.0.0.1:5380.



.Screenshot of front page

image:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_frontpage.png[Screenshot

of rescached front page,320]



The front page allow user to monitor active caches, query the caches, and

removing the caches.



.Screenshot of Environment page

image:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_environment.png[rescached environment page,320]



The Environment page allow user to modify the rescached configuration on the

fly.



.Screenshot of Hosts Blocks page

image:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_hosts_blocks.png[rescached

Hosts Blocks page,320]



The Hosts Blocks page allow user to enable or disable the external sources of

hosts blocks list.



.Screenshot of Hosts.d page

image:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_hosts_d.png[rescached

Hosts.d page,320]



The Hosts.d page allow user to manage hosts file, creating new hosts file,

create new record, or delete a record.



.Screenshot of Zone.d page

image:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_zone_d.png[rescached

Zone.d page,320]



The Zone.d page allow user manage zone file, creating new zone file, adding or

deleting new resource record in the zone file.



== 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/COPYING`:: 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)

RFC8484:: DNS Queries over HTTPS (DoH)



== BUGS



`rescached` only know specific DNS record type,



[horizontal]

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 and macOS system.

Technically, if it can compiled, it will run in any operating system.



== AUTHOR



`rescached` is developed by Shulhan ([email protected]).



== LICENSE



Copyright 2018, M. Shulhan ([email protected]).

All rights reserved.



Use of this source code is governed by a GPL 3.0 license that can be found

in the COPYING file.



== LINKS



The project for this software is available at

https://sr.ht/~shulhan/rescached.



For request of features and/or bugs report please submitted through web at

https://todo.sr.ht/~shulhan/rescached.



== SEE ALSO



*rescached.cfg*(5)