/rescached

Resolver cache daemon (deprecated). See https://github.com/shuLhan/rescached-go for new implementation.
dns cache c-plus-plus cpp rescached
  1. C++ 82.6%
  2. Makefile 13.0%
  3. Shell 4.4%
Switch branches/tags
Nothing to show
Find file
Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Open in Desktop Download ZIP

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching Xcode...

If nothing happens, download Xcode and try again.

Launching Visual Studio...

If nothing happens, download the GitHub extension for Visual Studio and try again.

Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
AUR @ 557c4d6
doc
src
.gitignore
.gitmodules
CHANGELOG
LICENSE
README.adoc

README.adoc

RESCACHED(1) Manual Page

NAME

rescached - resolver (domain name service) 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 when running and in local disk when not running.

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

  • Enable to handle request from UDP and TCP connections.

  • Saving/loading cache to/from disk.

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

  • Load and serve addresses and hostnames from all files inside directory /etc/rescached/hosts.d/, recursively.

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

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 in rescached Works

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

Each query and answer data in cache have a number of accessed field, which defined how the cache will be ordered in memory. The frequently queried host-name will be at the top of cache list, and less queried host-name will at the bottom of cache list. The following table show an example of list of cache with number of frequently accessed in the first column, and name of host in the second column.

+-----+------------------+
| #   | host-name        |
+-----+------------------+
| 529 | kilabit.info     |
+-----+------------------+
| 233 | www.google.com   |
+-----+------------------+
| ... |        ...       |
+-----+------------------+
| 1   | www.kilabit.info |
+-----+------------------+

The number of cache that rescached can hold in memory is depend on the value of cache.max in configuration file. When the number of cache in memory reached it cache.max value, it will remove all cache data that has the number of frequently accessed less than or equal to cache.threshold.

Installation

Prerequisites

  • GNU C++ compiler.

  • GNU make.

  • git SCM.

  • asciidoc, for generate manual page.

  • systemd or system V init tool for service.

Compiling From Source

To build rescached from the source, follow the procedures bellow,

$ git clone http://www.github.com/shuLhan/rescached.git rescached.git
$ cd rescached.git/src
$ git submodule init
$ git submodule update
$ make

Installation

After program successfully build, you can install it manually or using GNU make program.

Installing Using GNU make Program

In Linux system with init.d use,

$ sudo make install-init

In Linux system with systemd use,

$ sudo make install

Manual Installation

  • Copy rescached configuration to system directory. Assume that we use directory "/etc/rescached" as configuration directory, then

    $ sudo mkdir -p /etc/rescached
$ sudo cp rescached.cfg /etc/rescached

  • Create directory for cache file. In this example we use "/var/cache/rescached" as cache directory,

    $ sudo mkdir -p /var/cache/rescached

    If you use different cache directory, do not forget to change the configuration option.

  • Copy rescached program to your system path.

    $ sudo cp build/rescached /usr/sbin

  • 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 init.d startup script in file scripts/rescached.run or scripts/rescached.arch.

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

Post Installation Configuration

  • 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 maximum caches and cache threshold

    Edit rescached configuration, /etc/rescached/rescached.cfg, change the value of cache.max 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 startup option located in file /etc/rescached/rescached.cfg. See manual page of rescached.cfg(5) for more information.

EXIT STATUS

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

ENVIRONMENT

LIBVOS_DEBUG

If the value is set to non zero before running, rescached will print debug output from libvos (the library that is used to build the program) to screen and log file. The output of debug is different from debug option.

FILES

/etc/rescached/rescached.cfg

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

/etc/rescached/hosts.d/

Directory that will be scanned by rescached for custom host files, recursively. Its means if its contain sub directory, all files in those sub directory will be loaded too.

/etc/rescached/hosts.d/hosts.block

List of ads server hostname that will blocked by the rescached. This file will be loaded when program started.

/etc/hosts

System hostname to address mapping. This file will be loaded when program started.

/usr/bin/rescached-update-hosts-block.sh

Script to update list of ads/malware hosts in /etc/rescached/hosts.d/hosts.block. After executing this script, you must restart rescached.

/var/cache/rescached.vos

The cache file. This file will be read when program started and written when program exit.

/var/run/rescached.pid

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

NOTES

This program has been debugged extensively with Valgrind and has no memory leak.

This program developed with reference 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)

BUGS

rescached only know specific DNS record type,

A

a host address
NS

an authoritative name server
CNAME

a canonical name for an alias
SOA

zone authority
PTR

a domain name pointer
HINFO

host information
MX

mail exchange
TXT

text string
SRV

location of services
AAAA

a host address for IPv6

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

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

AUTHOR

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

CREDITS

LICENSE

Copyright 2009-2017, 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

SEE ALSO

rescached.cfg(5), resolver(1)