{"id":16842668,"url":"https://github.com/rofl0r/dnscache","last_synced_at":"2025-04-10T13:33:44.700Z","repository":{"id":138311112,"uuid":"336925776","full_name":"rofl0r/dnscache","owner":"rofl0r","description":"tiny\u0026efficient caching dns daemon and forwarder","archived":false,"fork":false,"pushed_at":"2021-02-08T02:56:06.000Z","size":20,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T12:12:51.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rofl0r.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2021-02-08T01:03:43.000Z","updated_at":"2024-03-31T13:36:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"70c71a5d-446b-4285-881d-1dba04a99895","html_url":"https://github.com/rofl0r/dnscache","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rofl0r%2Fdnscache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rofl0r%2Fdnscache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rofl0r%2Fdnscache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rofl0r%2Fdnscache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rofl0r","download_url":"https://codeload.github.com/rofl0r/dnscache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225836,"owners_count":21068078,"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":[],"created_at":"2024-10-13T12:47:49.732Z","updated_at":"2025-04-10T13:33:44.689Z","avatar_url":"https://github.com/rofl0r.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"dnscache\n========\n\na small DNS forwarder, with caching functionality.\nit's purpose is mainly to be used as a so-called `pihole`, but without requiring\nto run a docker container, a separate box, or somesuch.\nit was devised because all existing and known (by me) solutions are either\ndifficult to set up, bloated, or buggy.\n\nusecase 1: caching DNS server for your own box\n----------------------------------------------\nin case you got a slow internet connection, having DNS names cached can make\na huge performance difference, and also makes your internet usage less\ntransparent to the provider of your DNS server, as every DNS name is only\nlooked up once during the lifetime of the process.\nin this case you probably want to either run dnscache on port 53 as root,\nor redirect port 53 to whatever port you run dnscache on, and put it as your\nnameserver into `/etc/resolv.conf`.\nas dnscache has only a few hundred lines of code it should be quite easy to\nassure that it's not exploitable.\n\nusecase 2: prevent connections to undesired domains\n---------------------------------------------------\ndnscache accepts an option -l to specify an `/etc/hosts`-style ip/dns mapping\nwhich is loaded on start, and additionally an option -s to specify a script\nthat gets passed a yet unknown DNS name and can return an IP for it.\nthis makes it easy to write a small script/program that matches the hostname\nusing e.g. a regex against common naming patterns for adservers or devices\nthat \"call home\" like e.g. android devices that talk to google servers all the\ntime even when no google app is actively being used, probably telling them all\nsorts of stuff about your behaviour, interests, data, and usage patterns.\na couple lines in the list file or some custom rules in a matcher script make\na quick end to this unwanted behaviour.\nto make this work, you need to control the internet gateway used by those\ndevices e.g. when you run `hostapd` on your local box, and define some iptables\nrules to bend traffic to dnscache.\nin case of running this on a NAT router, you'd configure some rules roughly\nlike this:\n\n       iptables -t nat -A PREROUTING -i OUTIF -p udp --dport 53 \\\n         --source HOST -j DNAT --to ADDR:PORT\n\nwhere\n\n    OUTIF = network interface where you want to capture DNS requests\n    HOST  = the ipv4 of the host of which we want to hijack DNS request\n    ADDR  = ipv4 address of dnscache listen interface (e.g. 127.0.0.1)\n    PORT  = port where dnscache listens\n\nthis example would redirect all DNS packets of HOST to our dnscache.\n\nto catch traffic of e.g. a virtual machine running on your box, you'd need\nto use the `OUTPUT` chain instead of `PREROUTING`. in that case it's a little\ntrickier to not make looping DNS requests. what i did is to specify a DNS\nserver ip for use with dnscache that's not used anywhere else on the system\n(and is not google's DNS server either), then make the rule like so:\n\n    iptables -t nat -A OUTPUT -p udp --dport 53 \\\n     ! --destination A.B.C.D -j DNAT --to 127.0.0.1:2053\n\nwhere A.B.C.D is the address of that DNS servers. this tells iptables to let\nonly DNS requests to that specific server go out.\n\nyou can check your rules like so:\n\n    iptables -t nat -L --line-numbers\n\nthis will show you the rules for chains `OUTPUT` and `PREROUTING` with\nlinenumbers, which can be deleted with the command\n\n    iptables -t nat -D CHAINNAME N\n\nwhere N is that linenumber, in case the rule doesn't work as expected.\n\n\nimplementation details\n----------------------\n\ndnscache works currently only with ipv4. if an AAAA (ipv6) request is received,\nthe request will be turned into an A (ipv4) request and forwarded to the\nchosen upstream DNS server. the returned ipv4 is then converted into an\nipv4-in-ipv6 address and returned to the client.\ncurrently the implementation is quite lame in that only one thread is used,\nso while an upstream DNS lookup is in progress, the server blocks.\nalso MX lookups aren't currently processed.\notoh the implementation is quite resource efficient, only a couple bytes are\nrequired for every cached DNS name. while no DNS packets are received, there\nis no CPU usage at all. it's estimated that this daemon can run for weeks and\nnever consume more than like 256KB heap memory.\nthe best of all is that no config file is necessary, everything can be done\nwith a handful of command line options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frofl0r%2Fdnscache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frofl0r%2Fdnscache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frofl0r%2Fdnscache/lists"}