rescached

package module
Version: v0.0.0-...-d095dbd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 22, 2019 License: BSD-3-Clause Imports: 20 Imported by: 0

README

RESCACHED(1)
============
M. Shulhan
2018.09.29
:doctype: manpage
:mansource: rescached
:manmanual: rescached


== 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

* https://golang.org[Go compiler]
* https://git-scm.com[git, version control system]
* asciidoc, to generate manual page
* systemd or system V init tool for service

=== 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,
[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 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.


== LINKS

- Source code repository: https://github.com/shuLhan/rescached-go
- RFC 1035: https://tools.ietf.org/html/rfc1035
- Improving DNS Privacy in Firefox: https://blog.nightly.mozilla.org/2018/06/01/improving-dns-privacy-in-firefox/


== SEE ALSO

*rescached.cfg*(5)

Documentation

Overview

Package rescached implement DNS forwarder with cache.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNetworkType = errors.New("invalid network type")
)

List of error messages.

Functions

This section is empty.

Types

type Options

type Options struct {
	ListenAddress   string
	NSParents       []*net.UDPAddr
	Timeout         time.Duration
	CachePruneDelay time.Duration
	CacheThreshold  time.Duration

	FilePID        string
	FileResolvConf string
	DirHosts       string
	DirMaster      string

	DoHParents []string
	DoHCert    string
	DoHCertKey string

	ListenPort uint16
	DoHPort    uint16

	ConnType         dns.ConnType
	DoHAllowInsecure bool
}

Options for running rescached.

func NewOptions

func NewOptions() *Options

NewOptions create and initialize options with default values.

type Server

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

Server implement caching DNS server.

func New

func New(opts *Options) *Server

New create and initialize new rescached server.

func (*Server) CachesStats

func (srv *Server) CachesStats() string

func (*Server) LoadHostsDir

func (srv *Server) LoadHostsDir(dir string)

LoadHostsDir load all host formatted files in directory.

func (*Server) LoadHostsFile

func (srv *Server) LoadHostsFile(path string)

LoadHostsFile parse hosts formatted file and put it into caches.

func (*Server) LoadMasterDir

func (srv *Server) LoadMasterDir(dir string)

LoadMasterDir load all master formatted files in directory.

func (*Server) LoadMasterFile

func (srv *Server) LoadMasterFile(path string)

LostMasterFile parse master file and put the result into caches.

func (*Server) RemovePID

func (srv *Server) RemovePID()

RemovePID remove server PID file.

func (*Server) ServeDNS

func (srv *Server) ServeDNS(req *dns.Request)

ServeDNS handle DNS request from server.

func (*Server) Start

func (srv *Server) Start() error

Start the server, waiting for DNS query from clients, read it and response it.

func (*Server) Stop

func (srv *Server) Stop()

Stop the server.

func (*Server) WritePID

func (srv *Server) WritePID() error

WritePID will write current process PID to file `FilePID` only if the file is not exist, otherwise it will return an error.

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL