_www/doc: update the index and resolver documentation

While at it, rename the README.adoc to README and made symlink
to it as README.adoc.

1 files changed, 1 insertions, 488 deletions

diff --git a/README.adoc b/README.adoc
index 18ac4a6..100b938 100644..120000
--- a/README.adoc
+++ b/README.adoc
@@ -1,488 +1 @@
-// SPDX-FileCopyrightText: 2018 M. Shulhan <ms@kilabit.info>
-// SPDX-License-Identifier: GPL-3.0-or-later
-= RESCACHED(1)
-M. Shulhan <ms@kilabit.info>
-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 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).
-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/_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/_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/_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/_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/_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.
-
-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 GPL 3.0 license that can be found
-in the COPYING 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)
+README
\ No newline at end of file