rescached Documentation

Introduction

What Is rescached ?

rescached is domain name service cache, it caching internet name and address on local memory when running and in local disk when not running.

Features and Limitations.

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.

• Enable to handle UDP and TCP connections.
• Saving/loading cache to/from disk

• Only know specific DNS record type,
• • A : a host address
  • NS : an authoritative name server
  • CNAME : a canonical name for an alias
  • MX : mail exchange
• Only run and tested in Unix system

Behind The DNS

A short story on how DNS work in your system.

When you opened some website, let say www.reddit.com, in a browser, the first thing that browser do is to translate name address www.reddit.com into an internet address (i.e.: 219.83.126.10) so browser can make a connection to www.reddit.com server.

How browser do that ? First, it will send query to one of DNS server listed in your system configuration (/etc/resolv.conf in Unix). 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 to their parent DNS server.

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

If you browsing frequently on the same site, hitting the refresh button, opening a page on the same website, etc.; this procedures will always repeated every times.

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

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

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

How Cache In rescached Work

rescached in technical side of view.

Each of 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. This, obviously, will make a cache list based on user habit (frequently accessed host-name), which effect on the search time on cache list: fast reply.

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

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 cache.threshold.

Installation

Prerequisite

• c++ compiler
• make tools
• git SCM
• system V init tool for service.

Compiling From Source

$ git clone http://www.github.com/shuLhan/rescached.git rescached.git
$ git clone http://www.github.com/shuLhan/libvos.git libvos.git
$ cd rescached.git/src
$ ln -s ../../libvos.git lib
$ make

Installation

$ sudo make install

$ sudo make install-arch

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.

• 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,

  $ sudo mv /etc/resolv.conf /etc/resolv.conf.org
  $ sudo echo "nameserver 127.0.0.1" > /etc/resolv.conf
      

Configuration

Controlling rescached Service

After rescached has been installed you can start, stop, and view status of rescached service using /sbin/rcrescached.

• Starting rescached service.

• $ sudo /sbin/rcrescached start
  

  
  
• Stopping rescached service.

• $ sudo /sbin/rcrescached stop
  

  
  
• View status of service.

• $ sudo /sbin/rcrescached status
  

  
  NOTE: status option is not available in Arch Linux system.

rescached Startup Option

All rescached startup option located in file /etc/rescached/rescached.cfg. In this file you can see some comment for any option and some possible value. This section will explain more about each option and how they effect rescached.

• file.data

• Value	A path to a cache file.
  Format	/any/path/to/file
  Default	rescached.vos
  Description	This file contain all DNS answers that rescached collected while running. When rescached stopped it will saved all DNS answer in this file, so when rescached is started again it will load all data in this file to memory again. If not set, then rescached will load/save the cache to the file named rescached.vos in current directory where user running rescached.

  
  
• file.data.backup

• Value	A name of of backup file, with or without path.
  Format	/any/path/to/file
  Default	file.data + ".bak"
  Description	This file is a backup of file.data, it will be created only if rescached program exit successfully without error. If not set then it will have the same name with the value in file.data but with additional suffix, .bak.

  
  
• file.pid

• Value	A path to process id file.
  Format	/any/path/to/file
  Default	rescached.pid
  Description	When rescached program started, it will create this file as a mediator to any system service. Content of this file is process ID (PID) of rescached program in system. If not set then the default name will be used, and it will be saved in current directory where user running rescached.

  
  
• file.log

• Value	A name of rescached log file.
  Format	/any/path/to/file
  Default	rescached.log
  Description	This file contain log of program when running. Verbosity of log output is depend on value of debug option.

  
  
• server.parent

• Value	List of parent DNS servers, separated by commas.
  Format	IP-ADDRESS:PORT, IP-ADDRESS:PORT, ...
  Default	Address : 8.8.8.8, 8.8.4.4 Port : 53
  Description	When rescached receive a query from client and when it does not have a cached address of query, it will pass the query to those parent server. rescached use a Google DNS public server as a default parent address if not set. The reason for this is that Google DNS public server use a simple and small size of response/answer. Please, do not use OpenDNS server, because OpenDNS will reply with it own address, instead of replying with no answer, if certain host-name not found (i.e. typo in host-name), this will make rescached caching a false data. To check if your parent server reply the unknown host-name with no answer, use dig tool.

  
  
• server.listen

• Value	Local IP address that rescached will listening for client request.
  Format	<IP-ADDRESS>
  Default	127.0.0.1
  Description	Address in local network where rescached will listening for query from client. If you want rescached to serve a query from another host in your local network, change this value to 0.0.0.0

  
  
• server.listen.port

• Value	Port for listening for client request
  Format	Any number between 1 to 65535
  Default	53
  Description	Beside the server.listen address, rescached also need to known which port it will opening for receiving client queries. You should not change this value, because technically every client (browser, email client, etc.) will always send the query to port 53.

  
  
• server.timeout

• Value	Timeout value, in second, before cleaning queue.
  Format	Any number between 300 to 2147483647.
  Default	300
  Description	This option set the server timeout value. If time out is reached, all the old queries (that is older than server.timeout) in queue that does not receipt a reply from parent server will be removed.

  
  
• cache.max

• Value	Maximum number of host-name and address that will keep in memory.
  Format	Any number between 1 and 2147483647.
  Default	100000
  Description	When rescached running it will keep all queries and answers in memory as much as cache.max. The bigger the cache.max value, then the more rescached will use memory.

  
  
• cache.threshold

• Value	Minimum value for cache status.
  Format	Any number between 1 and 2147483647.
  Default	1
  Description	When rescached cache all the queries and answers, until long enough it will reached it own maximum value (cache.max), when it happen rescached will remove all cache that their number-of-queried value is less than cache.threshold.

  
  
• cache.mode

• Value	cache mode, affect how the cache will be saved in disk/memory.
  Format	Number between 1 and 2.
  Default	2
  Description	If cache.mode is set to 1, all DNS record will be keep forever, no possible query or renewed DNS record happen until the specific DNS record removed from cache. If cache.mode is set to 2 (default), all DNS record will be keep only after the specific time, based on maximum TTL value in DNS record. If TTL is reached, hostname will be queried again to the DNS parent server, and old cache and TTL value will be replaced with a new one.

  
  
• debug

• Value	0 : log nothing. 1 : log startup, request, response, and exit status. 2 : log startup, request, response, caches, and exit status.
  Format	Any number between 0 and 2.
  Default	0
  Description	This option only used by developer for debugging program.