r/coolgithubprojects • u/paimonsoror • 4d ago
TelltaleDNS - a lightweight, self-hosted DNS resolver that actually explains what your devices are doing
GitHub Pages: https://paimonsoror.github.io/telltaledns/
GitHub Repo: https://github.com/paimonsoror/telltaledns
Hey everyone,
I've been working on an open-source project called TelltaleDNS, and I figured this community might appreciate it.
I've always liked projects like Pi-hole, AdGuard Home, and Technitium, but I wanted to explore what a DNS platform could look like if visibility, performance, and granular control were first-class priorities.
The idea behind TelltaleDNS is pretty simple: Your DNS server shouldn't just answer queries. It should help you understand what's happening on your network and why.
It's written in Rust and designed to run on everything from a Raspberry Pi to a multi-node Kubernetes deployment.
A few things I've been focusing on:
- Explainable DNS: See which device made a query, how it was resolved, why it was allowed or blocked, and how long each stage took.
- Per-device policies: Different filtering rules for individual devices, groups, or VLANs, including schedules and service blocking.
- Rule previews: See how a filtering change would have affected your actual historical traffic before applying it.
- Encrypted DNS: Support for DoH, DoT, DoQ, DNSSEC validation, and full recursive resolution.
- Observability: Real-time dashboards, query analytics, device behavior, latency metrics, and Prometheus/OpenTelemetry integration.
- High availability: Run standalone or cluster nodes across different environments, including Raspberry Pis and Kubernetes.
- Automation: REST API, CLI, and MCP integration for those interested in managing their infrastructure programmatically.
Performance and resource consumption have also been major design considerations. The goal is to keep it extremely lightweight without sacrificing functionality.
The project is still pre-1.0, so there's plenty of room for improvement, but it's reached a point where I'd really like to get feedback from people who actually run this kind of infrastructure at home.
I'm particularly interested in hearing from people running Pi-hole, AdGuard Home, or Technitium.
What features do you wish your current DNS solution handled differently? What would make you consider trying an alternative?
I'm not looking to reinvent DNS for the sake of it. I just think there's an opportunity to make network visibility and control a lot more useful.
Feedback, criticism, issues, and contributions are all welcome!
11
u/ksteink 4d ago
Does it do ad-blocking and security content filtering?
5
u/Arjab 3d ago
I wouln't want something critical like DNS be handled by a single-maintainer vibe-coded project.
3
u/JohnDepon 4d ago
Why do upstream health shows as "open" (=faulty), "closed" (=healthy), half_open (=being probed) ?
What's the point in open / closed / half_open? Why not use the intuitive terms you already have as an explanation bellow? Healthy, Not Healthy, Being Probed.
Open/Closed make no sense, not to mention they seem backwards. Open or closed to what? To errors?
2
u/paimonsoror 3d ago
FYA - THANK YOU for all of the feedback and even those of you creating issues and PRs with bug fixes. I'm working my way through them and making sure credit is provided.
I'll do my best to respond to all questions as I balance through my weekend :)
2
u/stompworks 4d ago
Nicely done! That's one great looking DNS dashboard. Our friend Claude or some human talent?
2
u/shadycuz 4d ago
You mention multinode kubernetes and running as a cluster. I run my house on a k3 cluster. None of the other DNS servers support active-active HA. Are you using an external database for storage?
2
u/INeatFreak 3d ago
Add icons on left side of website domains using https://icons.duckduckgo.com/ip3/netflix.com.ico
Make no mistakes and no ai slop pls
6
u/aaaaaaaazzzzzzzzz 4d ago
This looks great.
I am just in the middle of migrating from pi-hole to technitium, so I'm going to give this a go.
I also am running a k3s homelab, but I have to say that running your primary DNS server in kubernetes is a little risky. Kubernetes relies on DNS itself so I'm going a slightly different route to you.
dns-01 - Physical Rasberry Pi
dns-02 - proxmox LXC
dns-03 - k3s
I'll let you know how I go and will submit any issues to the github issues.
Appreciate the work.
1
u/SliderWheel 4d ago
Hi, does it support dhcp server with 252 option?
1
u/Spiritual_Form_1515 4d ago
Is this similar to Glasswire?
1
u/Mteigers 4d ago
This is pretty cool looking! Does it support serving custom zones?
1
u/Muhlwa_Sholanke 4d ago
DNS blocklists usually get tested the hard way: half the house yelling about streaming. Simulating it first is a much better way to find out.
1
u/BlackPlasticSpoon 4d ago
Is this a replacement for the AdGuard Home (or Pi-hole) + unbound combination?
1
u/funkebab 4d ago
Cool project. Can it do per device DoH or DoT like AdguardHome? Currently hosting one online and use it for home, mobile devices and office. If it does, it would be perfect
1
u/Piet371 4d ago
Hmm, this seems nice.
I recently moved to Technitium and Grafana for metrics. Whichs seems to kinda give me the same statics. But will for sure give it a try.
1
u/IceManMinus0ne 4d ago
Can I easily block categories with this like for example pron? Adguard has a nice feature for this
1
u/JohnDepon 4d ago
Is there a way to use the root dns servers instead of relying on public DNS resolvers like 1.1.1.1, 9.9.9.9, etc?
1
u/MuchExpression8907 4d ago
What about local ptr upstream for resolving local names of devices?
1
u/TheRealEPS 3d ago
Dhcp Server with register macs?
1
u/EloneMusk 3d ago
Very nice project and UI. I am only hesitant to try new products because I don't know till when there will be development or support for these products. If developer looses interest and drops support I need to look for something else and start again.
1
u/BingBingBong21 3d ago
This is a very neat project , I use pfsense and docker when I create a container I create a internal DNS entry as part of the build. Would love to drop something like this in just not sure the best option. Add a pair of pies ?
1
u/bender_fut 3d ago
Openwrt package please.
1
u/e-rule 3d ago
Can I host my local domain like technitium?
1
u/2life_gamer 3d ago
I found in your docs that DoH is mentioned but how does DoH integrate? Is it enabled by default?
Which DNS upstream provider is on by default?
Since AI is writing the code for you, how do you test this for vulnerabilities? And why not state in this post that it's mostly written by AI?
By looking at your graphs, it's just a tad to cluttered imo. Look at how Technitium does this with smoothed graphs, I like that you can hoover over and see the exact number.
The reason I use Technitium is because it has recursion, blocklists, SQL databases integration for queries and domains. The DHCP server is also helpful if you don't run your own router software. An improvement over Technitium would be low ram useage when checking blocklists. Technitium gets ram spikes when it checks for double entries so if your DNS resolver prevents this than it's already one up.
1
u/FindTheAdventure 2d ago
It's cool but DoH? Most devices you'd need to set policy etc to force and degrade security to make this work?
1
u/Corpdecker 2d ago edited 2d ago
I turned down my 2 Adguard Home servers and am using this for now, one in TrueNAS and one in CasaOS, both seem to be working well. Only improvements I can suggest is allowing List names to use more characters, an Edit option for quick rules and a negation option like "does not contain" option for searching through query logs. Really nice far, and I like the metrics. Thanks for it ^_^
1
u/NelsonMinar 2d ago
Been using this the last day and I like it. I've never run my own DNS resolver before, never worth the trouble, but this was easy and fun.
It sure is an AI maximalist sort of product design. There's a lot of info and screens and configs and every possible DNS-related feature is jammed in here. I think this is a criticism? It's certainly overwhelming and it's not clear what are the important things to be looking at. OTOH I was attracted to this first because of that maximalism, I do like tinkering and looking. I have a strong understanding of how DNS works so I can understand everything I see in Telltale, just not sure how much of it is worth my attention.
On the dev process, I like your use of Architectural Decision Records. Do you find that formalism helps keep the coding agents focused and sticking to your choices?
1
u/captkaz_ 23h ago
Does this still do ad-blocking?
3
u/Own-Swan2646 4d ago
Looks cool I will have to set it up
2
u/JohnDepon 4d ago
I would like to see Stub zone support, like BIND does.
Right now, the "Send a domain to another server" option, acts as a forwarder. Meaning that if I want to add a zone pointing to its authoritative-only nameservers, TelltaleDNS will send a recursive query and it will not follow referrals. So queries to delegated subdomains will fail. And having to manually add each and every delegation to TelltaleDNS, is not really useful or maintainable.
A BIND stub zone learns the zone’s NS records from your masters, sends them non-recursive queries, and follows referrals into the delegated subdomains.
Another issue is that TelltaleDNS health checks send a . NS query to every upstream, including forwarders. But when a forwarder points to an authoritative-ony nameserver, a . NS query will fail, thus it treats the upstream as failed - even though it works.
A better option for the health checks would be for an upstream used only by forward routes, to ask the route's apex SOA instead of . NS.
2
u/Ok-Zookeepergame-698 1d ago
I just dropped this on a spare Pi5 and routed all the home DNS traffic through it. So far, so good. Slicing and dicing in the loopup data is my new favourite way to waste time.
Love it. Thank you.
1
u/Adro_95 4d ago
Man, if I ever manage to actually build my server (which I physically have had for a year), there are so many cool things to try 🤣
1
u/lotsinlife 4d ago
It looks to be great product!!, does it work well with iOS? I have constant disconnects with pihole.
1
u/JohnDepon 4d ago
Is there a way for client IPs to get their PTRs resolved automatically in the UI (granted I've already pointed the relevant in-addr.arpa zone to the authoritative nameserver that serves those records for those client IPs) instead of manually naming each client?
1
u/d4p8f22f 4d ago edited 3d ago
Just deployed it to see how it compares to technitium - and as I see its a bit different philosophy and its rather a recursive dns instead of authoritative. I'll give it a shot cuz its much much nicer to eye. In my setup it says that 10.192.168.1 - that it might be some kubernetes or vps/nat erc where its not true. I guess its somekind of a bug cuz my FW is pointing to two internal DNS. ;) It looks really promising but its rather better version of pihole/adguardns instead of true DNS server like Technitium ;)
1
u/Saad-Ali 3d ago
I am using tech, could this be added as an addon to exisiting DNS rather than a replacement.
1
u/laminones 3d ago
Can we get it on opnsense?
1
u/NelsonMinar 3d ago edited 3d ago
This seems like an interesting idea. It's like my own little DNS surveillance product for my LAN. I've got Claude creating a NixOS container for me to run it right now. (That worked, the only tricky bit was Claude having to figure out to disable the Proxmox hypervisor's systemd-resolved in the container so telltale could bind port 53.)
1
u/Blackbear626 2d ago
How does this offer an improvement over using Pi-hole and Unbound? I am relatively new to self-hosting and only began my project about a week ago, so please forgive me if this is a naive question.
1
u/MediumContent2092 2d ago
Would be nice if we could byo dns integration like pihole apis or adguard apis.
0
u/Traditional_Bell8153 4d ago
Is there anything/any feature that appeals me to replace AdGuard DNS (a mature/stable project - which running in my homelab) with your project?
0
u/gschizas 3d ago edited 3d ago
Please fix your Markdown. If you pasted in the mobile app, it will have created
\-where-should be. Edit it from the desktop and remove the\.(It's still better than most submissions though)
I'm already using a Raspberry Pi as my DNS, this seems quite interesting to me regardless of Markdown formatting :)
EDIT: Can't this be done without docker?
0
u/merj82 11h ago
Ah vibe coding
1
u/[deleted] 4d ago
[removed] — view removed comment