From 06135e3b12818167168e0feee8d8d95e05d9d6c9 Mon Sep 17 00:00:00 2001 From: Shulhan Date: Wed, 9 Feb 2022 22:14:19 +0700 Subject: all: fix format of all asciidoc files This is to make the adoc files parsed and rendered correctly by asciidocgo and asciidoc tools. --- README.adoc | 175 ++++++++++++++++++++++++------------------------ _doc/rescached.cfg.5.gz | Bin 2795 -> 2773 bytes _doc/rescached.cfg.adoc | 117 ++++++++++++++++---------------- _doc/resolver.1.gz | Bin 1553 -> 1458 bytes _doc/resolver.adoc | 23 ++++--- rescached.1.gz | Bin 5919 -> 5887 bytes 6 files changed, 160 insertions(+), 155 deletions(-) diff --git a/README.adoc b/README.adoc index 91f503f..5572b4e 100644 --- a/README.adoc +++ b/README.adoc @@ -1,7 +1,6 @@ -RESCACHED(1) -============ += RESCACHED(1) M. Shulhan -20 January 2021 +8 February 2022 :doctype: manpage :mansource: rescached :manmanual: rescached @@ -15,23 +14,23 @@ rescached - DNS resolver cache daemon. == SYNOPSIS -+rescached+ [-config 'rescached.cfg'] +rescached [-config 'rescached.cfg'] == OPTIONS -'rescached.cfg' is rescached configuration, usually it reside in +`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 +`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` is not a reimplementation of DNS server like BIND. -+rescached+ primary goal is only to caching DNS queries and answers, used by +`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. @@ -40,18 +39,18 @@ network. 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) +* 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 @@ -64,7 +63,7 @@ address (for example to 18.136.35.199) so browser can make a connection to How browser do that? First, it will send query to one of DNS server listed in your system -configuration (in example, +/etc/resolv.conf+ in Linux). +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. @@ -80,11 +79,11 @@ 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 +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 +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+. +will be answered directly by `rescached`. ---- +----+ +----------------+ +------------------+ @@ -99,7 +98,7 @@ will be answered directly by +rescached+. ---- The only request that will be send to your DNS server is the one that does not -already exist in +rescached+ cache. +already exist in `rescached` cache. === HOW CACHE WORKS @@ -127,15 +126,15 @@ The following table illustrate list of caches in memory, +---------------------+------------------+ ---- -Every +cache.prune_delay+ (let say every 5 minutes), rescached will try to +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 +current-time + cache.threshold ---- -(remember that "+cache.threshold+" value must be negative) it will remove the +(remember that "cache.threshold" value must be negative) it will remove the record from cache. @@ -153,12 +152,12 @@ record from cache. 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 +$ 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. +The last command will build binary named `rescached` in current directory. === INSTALLATION @@ -167,25 +166,25 @@ system binary directory. ==== MANUAL INSTALLATION -* Copy rescached configuration to system directory. +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. -+ +Copy rescached program to your system path. + $ sudo cp -f rescached /usr/bin/ -* Create system startup script. -+ +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 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+. -+ +`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. @@ -217,26 +216,28 @@ You can then load the rescached service using launchd, * Set your parent DNS server. + -Edit rescached configuration, +/etc/rescached/rescached.cfg+, change the value -of +parent+ based on your preferred 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. +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, +* 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 +and if you want `rescached` service to run when system startup, enable it by invoking, + $ sudo systemctl enable rescached.service @@ -244,7 +245,7 @@ invoking, == CONFIGURATION -All rescached configuration located in file +/etc/rescached/rescached.cfg+. +All rescached configuration located in file `/etc/rescached/rescached.cfg`. See manual page of *rescached.cfg*(5) for more information. === ZONE FILE @@ -253,7 +254,7 @@ 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 +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, @@ -319,34 +320,34 @@ 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 +[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. +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 +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). +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. @@ -370,31 +371,35 @@ 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[width=75%]. +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[width=75%]. +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[width=75%]. +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[width=75%]. +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[width=75%]. +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. @@ -402,38 +407,34 @@ deleting new resource record in the zone file. == EXIT STATUS -Upon success, +rescached+ will return 0, or 1 otherwise. +Upon success, `rescached` will return 0, or 1 otherwise. == FILES -'/etc/rescached/rescached.cfg':: - -The +rescached+ main configuration. +`/etc/rescached/rescached.cfg`:: The `rescached` main configuration. This configuration will be read when program started. -'/usr/share/rescached/LICENSE':: +`/usr/share/rescached/LICENSE`:: License file for this software. -License file for this software. - -'/var/run/rescached.pid':: - -File where process ID of rescached will be saved when running. +`/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) +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, +`rescached` only know specific DNS record type, + [horizontal] A:: A host address in IPv4 NS:: An authoritative name server @@ -452,7 +453,7 @@ 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. +`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 @@ -461,7 +462,7 @@ https://github.com/shuLhan/rescached-go/issues. == AUTHOR -+rescached+ is developed by Shulhan (ms@kilabit.info). +`rescached` is developed by Shulhan (ms@kilabit.info). == LICENSE @@ -475,9 +476,9 @@ 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/ +* 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 diff --git a/_doc/rescached.cfg.5.gz b/_doc/rescached.cfg.5.gz index a5dbbea..af4e274 100644 Binary files a/_doc/rescached.cfg.5.gz and b/_doc/rescached.cfg.5.gz differ diff --git a/_doc/rescached.cfg.adoc b/_doc/rescached.cfg.adoc index 8ca017a..20b8d28 100644 --- a/_doc/rescached.cfg.adoc +++ b/_doc/rescached.cfg.adoc @@ -1,5 +1,4 @@ -RESCACHED.CONF(5) -================= += RESCACHED.CONF(5) :doctype: manpage :man source: rescached.cfg :man version: 2020.05.10 @@ -20,38 +19,40 @@ rescached.cfg - Configuration for rescached service These file configure the behaviour of *rescached*(1) service. This section will explain more about each option and how they effect -+rescached+. +`rescached`. The configuration is using INI format where each options is grouped by header in square bracket: -* +[rescached]+ -* +[dns "server"]+ +* `[rescached]` +* `[dns "server"]` == OPTIONS -=== +[rescached]+ +=== [rescached] This group of options contain the main configuration that related to rescached. -[[wui.listen]] -==== +wui.listen+ +[#wui-listen] +==== wui.listen Format:: [host]:port Default:: 127.0.0.1:5380 Description:: The address to listen for web user interface. -[[file.resolvconf]] -==== +file.resolvconf+ +[#file-resolvconf] +==== file.resolvconf Format:: /any/path/to/file Default:: /etc/rescached/resolv.conf Description:: A path to dynamically generated *resolv.conf*(5) by -*resolvconf*(8). If set, the nameserver values in referenced file will -be used as "parent" name server if no "parent" is defined in configuration -file. +*resolvconf*(8). ++ +-- +If set, the nameserver values in referenced file will be used as "parent" name +server if no "parent" is defined in configuration file. To use this config, you must set either "dnsmasq_resolv", "pdnsd_resolv", or "unbound_conf" in "/etc/resolvconf.conf" to point to @@ -65,9 +66,10 @@ dnsmasq_resolv=/etc/rescached/resolv.conf #pdnsd_resolv=/etc/rescached/resolv.conf #unbound_conf=/etc/rescached/resolv.conf ---- +-- -[[debug]] -==== +debug+ +[#debug] +==== debug Value:: 0::: log startup and errors. @@ -77,14 +79,13 @@ Default:: 0 Description:: This option only used for debugging program or if user want to monitor what kind of traffic goes in and out of rescached. -[[dns_server]] -=== DNS Server options +[#dns_server] +=== [dns "server"] -This group of options related to DNS server using `[dns "server"]` as section -header. +This group of options related to DNS server. -[[parent]] -==== +parent+ +[#parent] +==== parent Format:: @@ -98,7 +99,7 @@ Default:: * Port: 53 Description:: List of parent DNS servers. + -When +rescached+ receive a query from client (for example, your browser) and +When `rescached` receive a query from client (for example, your browser) and when it does not have a cached answer for that query, it will forward the query to one of the parent name servers. + @@ -106,14 +107,14 @@ Using UDP as parent scheme, will automatically assume that the server also capable of handling query in TCP. This is required when client (for example, your browser) re-send the query after receiving truncated UDP answer. -Any query received by +rescached+ through TCP will forwarded to the parent +Any query received by `rescached` through TCP will forwarded to the parent name server as TCP too, using the same address and port defined in one of UDP parent. + Please, do not use OpenDNS server. If certain host-name not found (i.e. typo in host-name), OpenDNS will reply with its own address, instead of replying with empty answer. -This will make +rescached+ caching a false data and it may make your +This will make `rescached` caching a false data and it may make your application open or consume unintended resources. + To check if your parent server reply the unknown host-name with no answer, use @@ -121,66 +122,67 @@ To check if your parent server reply the unknown host-name with no answer, use Example:: ---- - ## Using UDP connection to forward request to parent name server. - parent = udp://1.1.1.1 +## Using UDP connection to forward request to parent name server. +parent = udp://1.1.1.1 - ## Using DNS over TLS to forward request to parent name server. - parent = https://1.1.1.1 +## Using DNS over TLS to forward request to parent name server. +parent = https://1.1.1.1 - ## Using DNS over HTTPS to forward request to parent name server. - parent = https://kilabit.info/dns-query +## Using DNS over HTTPS to forward request to parent name server. +parent = https://kilabit.info/dns-query ---- -[[listen]] -==== +listen+ +[#listen] +==== listen Format:: : Default:: 127.0.0.1:53 -Description:: Address in local network where +rescached+ will listening for +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:53+. +network, change this value to `0.0.0.0:53`. -[[http.port]] -==== +http.port+ +[#http-port] +==== http.port Format:: Number Default:: 443 Description:: Port to serve DNS over HTTP. -[[tls.port]] -==== +tls.port+ +[#tls-port] +==== tls.port Format:: Number Default:: 853 Description:: Port to serve DNS over TLS. -[[tls.certificate]] -==== +tls.certificate+ +[#tls-certificate] +==== tls.certificate Format:: /path/to/file Default:: (empty) Description:: Path to certificate file to serve DNS over TLS and HTTPS. -[[tls.private_key]] -==== +tls.private_key+ +[#tls-private_key] +==== tls.private_key Format:: /path/to/file Default:: (empty) Description:: Path to certificate private key file to serve DNS over TLS and HTTPS. -[[tls.allow_insecure]] -==== +tls.allow_insecure+ +[#tls-allow_insecure] +==== tls.allow_insecure Format:: true | false Default:: false Description:: If its true, allow serving DoH and DoT with self-signed certificate. -[[doh.behind_proxy]] -==== +doh.behind_proxy+ +[#doh-behind_proxy] +==== doh.behind_proxy Format:: true | false Default:: false @@ -188,19 +190,20 @@ Description:: If its true, serve DNS over HTTP only, even if certificate files is defined. This allow serving DNS request forwarded by another proxy server. -[[cache.prune_delay]] -==== +cache.prune_delay+ +[#cache-prune_delay] +==== cache.prune_delay Format:: Duration with time unit. Valid time units are "s", "m", "h". Default:: 1h Description:: Delay for pruning caches. ++ Every N seconds/minutes/hours, rescached will traverse all caches and remove response that has not been accessed less than -+cache.prune_threshold+. +`cache.prune_threshold`. Its value must be equal or greater than 1 hour (3600 seconds). -[[cache.prune_threshold]] -==== +cache.prune_threshold+ +[#cache-prune_threshold] +==== cache.prune_threshold Format:: Duration with time unit. Valid time units are "s", "m", "h". Default:: -1h @@ -209,13 +212,13 @@ Its value must be negative and greater or equal than -1 hour (-3600 seconds). == FILES -[[hosts.d]] +[#hosts-d] === /etc/rescached/hosts.d Path to hosts directory where rescached will load all hosts formatted files. -[[zone.d]] +[#zone-d] === /etc/rescached/zone.d Path to zone directory where rescached will load all zone files. @@ -227,21 +230,21 @@ Simple rescached configuration using dnscrypt-proxy that listen on port 54 as parent resolver, with prune delay set to 60 seconds and threshold also to 60 seconds. -.............................................................................. +---- [dns "server"] parent=udp://127.0.0.1:54 cache.prune_delay=60s cache.prune_threshold=60s -.............................................................................. +---- -Save the above script into +rescached.cfg+ and run it, +Save the above script into `rescached.cfg` and run it, $ sudo rescached -config rescached.cfg == AUTHOR -+rescached+ is developed by M. Shulhan (m.shulhan@gmail.com). +`rescached` is developed by M. Shulhan (m.shulhan@gmail.com). == LICENSE diff --git a/_doc/resolver.1.gz b/_doc/resolver.1.gz index 3a53d5d..66c46b9 100644 Binary files a/_doc/resolver.1.gz and b/_doc/resolver.1.gz differ diff --git a/_doc/resolver.adoc b/_doc/resolver.adoc index ff5cc23..98118c7 100644 --- a/_doc/resolver.adoc +++ b/_doc/resolver.adoc @@ -1,5 +1,4 @@ -RESOLVER(1) -=========== += RESOLVER(1) :doctype: manpage :man source: resolver :man version: 2018.08.26 @@ -42,7 +41,8 @@ Value:: DNS record type Format:: String Default:: A Description:: List of supported DNS record type, - ++ +---- TYPE (ID) - Description * A (1) - a host Address @@ -61,6 +61,7 @@ TYPE (ID) - Description * TXT (16) - TeXT strings * AAAA (28) - a host address in IPv6 * SRV (33) - a SerViCe record +---- [[hostname]] === +hostname+ @@ -78,18 +79,18 @@ Upon exit and success +resolver+ will return 0, or 1 otherwise. == EXAMPLE -* Resolve the IPv4 address for kilabit.info using one of nameserver in - +/etc/resolv.conf+, -+ +Resolve the IPv4 address for kilabit.info using one of nameserver in +`/etc/resolv.conf`, + $ resolver kilabit.info -* Resolve the IPv4 address for kilabit.info using 127.0.0.1 at port 54 as - name server, -+ +Resolve the IPv4 address for kilabit.info using 127.0.0.1 at port 54 as +name server, + $ resolver -ns 127.0.0.1:54 kilabit.info -* Resolve the mail exchange (MX) for kilabit.info, -+ +Resolve the mail exchange (MX) for kilabit.info, + $ resolver -t MX kilabit.info diff --git a/rescached.1.gz b/rescached.1.gz index 986dd77..b1b334f 100644 Binary files a/rescached.1.gz and b/rescached.1.gz differ -- cgit v1.3