{"id":16682547,"url":"https://github.com/shulhan/rescached","last_synced_at":"2025-03-17T00:32:44.011Z","repository":{"id":53927120,"uuid":"145297729","full_name":"shuLhan/rescached","owner":"shuLhan","description":"[mirror] Resolver (DNS) cache daemon. See https://sr.ht/~shulhan/rescached","archived":false,"fork":false,"pushed_at":"2025-01-11T11:49:16.000Z","size":3991,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-27T15:28:54.446Z","etag":null,"topics":["cache","dns","golang","resolver"],"latest_commit_sha":null,"homepage":"https://sr.ht/~shulhan/rescached","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuLhan.png","metadata":{"files":{"readme":"README","changelog":"CHANGELOG.adoc","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-19T11:37:08.000Z","updated_at":"2025-01-14T23:57:46.000Z","dependencies_parsed_at":"2023-11-09T15:27:52.092Z","dependency_job_id":"c54f0d87-8337-4d38-b0c9-cead22002fa2","html_url":"https://github.com/shuLhan/rescached","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuLhan%2Frescached","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuLhan%2Frescached/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuLhan%2Frescached/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuLhan%2Frescached/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuLhan","download_url":"https://codeload.github.com/shuLhan/rescached/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243835942,"owners_count":20355611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","dns","golang","resolver"],"created_at":"2024-10-12T14:07:52.227Z","updated_at":"2025-03-17T00:32:43.165Z","avatar_url":"https://github.com/shuLhan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"// SPDX-FileCopyrightText: 2018 M. Shulhan \u003cms@kilabit.info\u003e\n// SPDX-License-Identifier: GPL-3.0-or-later\n= RESCACHED(1)\nM. Shulhan \u003cms@kilabit.info\u003e\n8 February 2022\n:doctype: manpage\n:mansource: rescached\n:manmanual: rescached\n:toc:\n\n\n== NAME\n\nrescached - DNS resolver cache daemon.\n\n\n== SYNOPSIS\n\nrescached [-config 'rescached.cfg']\n\n\n== OPTIONS\n\n`rescached.cfg` is rescached configuration, usually it reside in\n/etc/rescached/rescached.cfg.\n\n\n== DESCRIPTION\n\n`rescached` is a daemon that caching internet name and address on local memory\nfor speeding up DNS resolution.\n\n`rescached` is not a reimplementation of DNS server like BIND.\n\n`rescached` primary goal is only to caching DNS queries and answers, used by\npersonal or small group of users, to minimize unneeded traffic to outside\nnetwork.\n\n\n=== FEATURES\n\nList of current features,\n\n* Enable to handle request from UDP and TCP connections\n* Enable to forward request using UDP or TCP\n* Load and serve addresses and host names in `/etc/hosts`\n* Load and serve hosts formatted files inside directory\n  `/etc/rescached/hosts.d/`\n* Blocking ads and/or malicious websites through host list in\n  `/etc/rescached/hosts.d/`\n* Support loading and serving zone file format from\n  `/etc/rescached/zone.d`\n* Integration with openresolv\n* Support DNS over TLS (DoH) (RFC 7858)\n* Support DNS over HTTPS (DoH) (RFC 8484)\n\n\n=== BEHIND THE DNS\n\nWhen you open a website, let say 'kilabit.info', in a browser, the first thing\nthat browser do is to translate name address 'kilabit.info' into an internet\naddress (for example to 18.136.35.199) so browser can make a connection to\n'kilabit.info' server.\n\nHow browser do that?\n\nFirst, it will send query to one of DNS server listed in your system\nconfiguration (for example, `/etc/resolv.conf` in Linux).\nThen, if your DNS server also \"caching\" the name that you requested, it will\nreply the answer (internet address) directly, if it is not then it will ask\ntheir parent DNS server.\n\n----\n+----+      +----------------+      +------------------+\n| PC | \u003c==\u003e | ISP DNS Server | \u003c==\u003e | Other DNS Server | \u003c==\u003e ...\n+----+      +----------------+      +------------------+\n----\n\nIf you browsing frequently on the same site, hitting the refresh button,\nopening another page on the same website, etc; this procedures will always\nrepeated every times, not including all external links like ads, social media\nbutton, or JavaScript from an other server.\n\nTo make this repetitive procedures less occurred, you can run `rescached` in\nyour personal computer.\nThe first time the answer is received in your local computer, `rescached` will\nsaved it in computer memory and any subsequent request of the same address\nwill be answered directly by `rescached`.\n\n----\n+----+      +----------------+      +------------------+\n| PC |      | ISP DNS Server | \u003c==\u003e | Other DNS Server | \u003c==\u003e ...\n+----+      +----------------+      +------------------+\n  ^^             ^^\n  ||             ||\n  vv             ||\n+-----------+    ||\n| rescached | \u003c==//\n+-----------+\n----\n\nThe only request that will be send to your DNS server is the one that does not\nalready exist in `rescached` cache.\n\n\n=== HOW CACHE WORKS\n\nThis section explain the simplified version of how internal program works.\n\nEach DNS record in cache have the time last accessed field, which defined how\nthe cache will be ordered in memory.\nThe last queried host-name will be at the bottom of cache list, and the oldest\nqueried host-name will at the top of cache list.\n\nThe following table illustrate list of caches in memory,\n\n----\n+---------------------+------------------+\n| Accessed At         | host-name        |\n+---------------------+------------------+\n| 2018-01-01 00:00:01 | kilabit.info     |\n+---------------------+------------------+\n| 2018-01-01 00:00:02 | www.google.com   |\n+---------------------+------------------+\n|         ...         |        ...       |\n+---------------------+------------------+\n| 2018-01-01 00:01:00 | www.kilabit.info |\n+---------------------+------------------+\n----\n\nEvery `cache.prune_delay` (let say every 5 minutes), rescached will try to\npruning old records from cache.\nIf the accessed-at value of record in cache is less than,\n\n----\ncurrent-time + cache.threshold\n----\n\n(remember that \"cache.threshold\" value must be negative) it will remove the\nrecord from cache.\n\n\n== BUILDING\n\n=== PREREQUISITES\n\n* https://golang.org[Go compiler]\n* https://git-scm.com[git, version control system]\n* asciidoc, to generate manual pages\n* systemd or system V init tool for service on Linux\n\n=== COMPILING\n\nSteps to compile from source,\n\n----\n$ go get -u git.sr.ht/~shulhan/rescached\n$ cd ${GOPATH}/src/git.sr.ht/~shulhan/rescached\n$ go build ./cmd/rescached\n----\n\nThe last command will build binary named `rescached` in current directory.\n\n=== INSTALLATION\n\nAfter program successfully build, you can install it manually by copying to\nsystem binary directory.\n\n==== MANUAL INSTALLATION\n\nCopy rescached configuration to system directory.\nWe use directory \"/etc/rescached\" as configuration directory.\n\n\t$ sudo mkdir -p /etc/rescached\n\t$ sudo cp cmd/rescached/rescached.cfg /etc/rescached/\n\nCopy rescached program to your system path.\n\n\t$ sudo cp -f rescached /usr/bin/\n\nCreate system startup script.\n\nIf you want your program running each time the system is starting up you can\ncreate a system startup script (or system service).\nFor OS using systemd, you can see an example for `systemd` service in\n`scripts/rescached.service`.\nFor system using launchd (macOS), you can see an example in\n`scripts/info.kilabit.rescached.plist`.\n\nThis step could be different between systems, consult your distribution\nwiki, forum, or mailing-list on how to create system startup script.\n\n====  AUTOMATIC INSTALLATION ON LINUX\n\nAutomatic installation on Linux require systemd.\nRun the following command\n\n\t$ sudo make install\n\nto setup and copies all required files and binaries to system directories.\nYou can then start the rescached service using systemd,\n\n\t$ sudo systemctl start rescached\n\n====  AUTOMATIC INSTALLATION ON MACOS\n\nRun the following command\n\n\t$ sudo make install-macos\n\nto setup and copies all required files and binaries to system directories.\nYou can then load the rescached service using launchd,\n\n\t$ sudo launchctl load info.kilabit.rescached\n\n\n==== POST INSTALLATION\n\n* Set your parent DNS server.\n+\nEdit rescached configuration, `/etc/rescached/rescached.cfg`, change the value\nof `parent` based on your preferred DNS server.\n\n* Set the cache prune delay and threshold\n+\nEdit rescached configuration, `/etc/rescached/rescached.cfg`, change the value\nof `cache.prune_delay` and/or `cache.threshold` to match your needs.\n\n* Set your system DNS server to point to rescached.\n+\n--\nIn UNIX system,\n\n\t$ sudo mv /etc/resolv.conf /etc/resolv.conf.org\n\t$ sudo echo \"nameserver 127.0.0.1\" \u003e /etc/resolv.conf\n--\n\n* If you use `systemd`, run `rescached` service by invoking,\n+\n\t$ sudo systemctl start rescached.service\n+\nand if you want `rescached` service to run when system startup, enable it by\ninvoking,\n+\n\t$ sudo systemctl enable rescached.service\n\n\n== CONFIGURATION\n\nAll rescached configuration located in file `/etc/rescached/rescached.cfg`.\nSee manual page of *rescached.cfg*(5) for more information.\n\n=== ZONE FILE\n\nRescached support loading zone file format.\nUnlike hosts file format, where each domain name is only mapped to type A\n(IPv4 address), in zone file, one can define other type that known to\nrescached.\nAll files defined `zone.d` configuration are considered as zone file and\nwill be loaded by rescached only if the configuration is not empty.\n\nExample of zone file,\n\n----\n$ORIGIN my-site.vm.\n$TTL    3600\n\n; resource record (RR) address\n@ A 192.168.56.10\n\n; resource record alias\ndev CNAME @\n\n; resource record address for other sub-domain\nstaging A 192.168.100.1\n\n; resource record address for other absolute domain.\nmy-site.com A 10.8.0.1\n----\n\nHere we defined the variable origin for root domain \"my-site.vm.\" with minimum\ntime-to-live (TTL) to 3600 seconds.\nIf no \"$ORIGIN\" variable is defined, rescached will use the file name as\n$ORIGIN's value.\n\nThe \"@\" character will be replaced with the value of $ORIGIN.\n\nThe first resource record (RR) is defining an IPv4 address for \"my-site.vm.\"\nto \"192.168.56.10\".\n\nThe second RR add an alias for relative subdomain \"dev\".\nDomain name that does not terminated with \".\" are called relative, and\nthe origin will be appended to form the absolute domain \"dev.my-site.vm\".\nIn this case IP address for \"dev.my-site.vm.\" is equal to \"my-site.vm.\".\n\nThe third RR define a mapping for another relative subdomain\n\"staging.my-site.vm.\" to address \"192.168.100.1\".\n\nThe last RR define a mapping for absolute domain \"my-site.com.\" to IP\naddress \"10.8.0.1\".\n\nFor more information about format of zone file see RFC 1035 section 5.\n\n\n=== INTEGRATION WITH OPENRESOLV\n\nRescached can detect change on file generated by resolvconf.\nTo use this feature unset the \"file.resolvconf\" in configuration file and set\neither \"dnsmasq_resolv\", \"pdnsd_resolv\", or \"unbound_conf\" in\n\"/etc/resolvconf.conf\" to point to file referenced in \"file.resolvconf\".\n\nFor more information see  *rescached.cfg*(5).\n\n\n=== INTEGRATION WITH DNS OVER HTTPS\n\nDNS over HTTPS (DoH) is the new protocol to query DNS through HTTPS layer.\nRescached support serving DNS over HTTPS or as client to parent DoH\nnameservers.\nTo enable this feature rescached provided TLS certificate and private key.\n\nExample configuration in *rescached.cfg*,\n\n----\n[dns \"server\"]\nparent = https://kilabit.info/dns-query\ntls.certificate = /etc/rescached/localhost.cert.pem\ntls.private_key = /etc/rescached/localhost.key.pem\ntls.allow_insecure = false\n----\n\nIf the parent nameserver is using self-signed certificate, you can set\n\"tls.allow_insecure\" to true.\n\nUsing the above configuration, rescached will serve DoH queries on\nhttps://localhost/dns-query on port 443 and UDP queries on port 53.\nAll queries to both locations will be forwarded to parent nameserver.\n\nThis feature can be tested using Firefox Nightly by updating the configuration\nin \"about:config\" into,\n\n----\nnetwork.trr.bootstrapAddress;127.0.0.1\nnetwork.trr.mode;3\nnetwork.trr.uri;https://localhost/dns-query\n----\n\nSince we are using `mode=3`, the `network.trr.bootstrapAddress` is required so\nFirefox Nightly can resolve \"localhost\" to \"127.0.0.1\".\nIf you use the provided self-signed certificate, you must import and/or enable\nan exception for it manually in Firefox Nightly (for example. by opening\nhttps://localhost/dns-query in new tab and accept security risk).\n\nTo check if DoH works, first, set the `debug` option to `1`, and\nrestart the rescached.\nOpen a new terminal and run `sudo journalctl -xf`, to show current system log.\nRun Firefox Nightly and open any random website.\nAt the terminal you will see output from rescached which looks like these,\n\n----\n... rescached[808]: dns: ^ DoH https://kilabit.info/dns-query 41269:\u0026{Name:id.wikipedia.org Type:A}                                                                         \n... rescached[808]: dns: \u003c UDP 45873:\u0026{Name:id.wikipedia.org Type:AAAA}                                                                                                     \n... rescached[808]: dns: + UDP 41269:\u0026{Name:id.wikipedia.org Type:A}     \n----\n\nIf you see number \"4\" in request line, \"\u003c request: 4\", thats indicated that\nrequest is from HTTPS connection and its working.\n\n\n== WEB USER INTERFACE\n\nThe rescached service provide a web user interface that can be accessed at\nhttp://127.0.0.1:5380.\n\n.Screenshot of front page\nimage:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_frontpage.png[Screenshot\nof rescached front page,320]\n\nThe front page allow user to monitor active caches, query the caches, and\nremoving the caches.\n\n.Screenshot of Environment page\nimage:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_environment.png[rescached environment page,320]\n\nThe Environment page allow user to modify the rescached configuration on the\nfly.\n\n.Screenshot of Hosts Blocks page\nimage:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_hosts_blocks.png[rescached\nHosts Blocks page,320]\n\nThe Hosts Blocks page allow user to enable or disable the external sources of\nhosts blocks list.\n\n.Screenshot of Hosts.d page\nimage:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_hosts_d.png[rescached\nHosts.d page,320]\n\nThe Hosts.d page allow user to manage hosts file, creating new hosts file,\ncreate new record, or delete a record.\n\n.Screenshot of Zone.d page\nimage:https://raw.githubusercontent.com/shuLhan/rescached-go/master/_www/doc/images/Screenshot_wui_zone_d.png[rescached\nZone.d page,320]\n\nThe Zone.d page allow user manage zone file, creating new zone file, adding or\ndeleting new resource record in the zone file.\n\n\n== EXIT STATUS\n\nUpon success, `rescached` will return 0, or 1 otherwise.\n\n\n== FILES\n\n`/etc/rescached/rescached.cfg`:: The `rescached` main configuration.\nThis configuration will be read when program started.\n\n`/usr/share/rescached/COPYING`:: License file for this software.\n\n`/var/run/rescached.pid`:: File where process ID of rescached will be saved\nwhen running.\n\n\n== NOTES\n\nThis program developed with references to,\n\nRFC1034:: Domain Names - Concepts and Facilities.\nRFC1035:: Domain Names - Implementation and Specification.\nRFC1886:: DNS Extensions to support IP version 6.\nRFC2782:: A DNS RR for specifying the location of services (DNS SRV)\nRFC8484:: DNS Queries over HTTPS (DoH)\n\n== BUGS\n\n`rescached` only know specific DNS record type,\n\n[horizontal]\nA:: A host address in IPv4\nNS:: An authoritative name server\nCNAME:: A canonical name for an alias\nSOA::  Start of [a zone of] authority record\nMB:: Mail box\nMG:: Mail group\nNULL:: Placeholders for experimental extensions\nWKS:: Record to describe well-known services supported by a host\nPTR:: Pointer to a canonical name.\nHINFO:: Host information\nMINFO:: Mail information\nMX:: Mail exchange\nTXT:: Text record\nAAAA:: A host address in IPv6\nSRV:: Service locator\nOPT:: This is a \"pseudo DNS record type\" needed to support EDNS\n\n`rescached` only run and tested in Linux and macOS system.\nTechnically, if it can compiled, it will run in any operating system.\n\n\n== AUTHOR\n\n`rescached` is developed by Shulhan (ms@kilabit.info).\n\n\n== LICENSE\n\nCopyright 2018, M. Shulhan (ms@kilabit.info).\nAll rights reserved.\n\nUse of this source code is governed by a GPL 3.0 license that can be found\nin the COPYING file.\n\n\n== LINKS\n\nThe project for this software is available at\nhttps://sr.ht/~shulhan/rescached.\n\nFor request of features and/or bugs report please submitted through web at\nhttps://todo.sr.ht/~shulhan/rescached.\n\n\n== SEE ALSO\n\n*rescached.cfg*(5)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshulhan%2Frescached","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshulhan%2Frescached","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshulhan%2Frescached/lists"}