{"id":24110406,"url":"https://github.com/kometen/dns-load-balancer","last_synced_at":"2025-07-13T16:34:12.817Z","repository":{"id":261491385,"uuid":"884461639","full_name":"kometen/dns-load-balancer","owner":"kometen","description":"Forward DNS queries to DNS-servers","archived":false,"fork":false,"pushed_at":"2025-05-09T11:38:09.000Z","size":119,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-09T12:34:55.348Z","etag":null,"topics":["dns","dns-over-tls","forwarder","rust"],"latest_commit_sha":null,"homepage":"https://github.com/kometen/dns-load-balancer","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kometen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2024-11-06T19:45:54.000Z","updated_at":"2025-05-09T11:38:12.000Z","dependencies_parsed_at":"2024-12-13T09:36:56.522Z","dependency_job_id":null,"html_url":"https://github.com/kometen/dns-load-balancer","commit_stats":null,"previous_names":["kometen/dns-load-balancer"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kometen%2Fdns-load-balancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kometen%2Fdns-load-balancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kometen%2Fdns-load-balancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kometen%2Fdns-load-balancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kometen","download_url":"https://codeload.github.com/kometen/dns-load-balancer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253850537,"owners_count":21973662,"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":["dns","dns-over-tls","forwarder","rust"],"created_at":"2025-01-11T01:15:00.923Z","updated_at":"2025-05-13T00:35:42.963Z","avatar_url":"https://github.com/kometen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dns-load-balancer\n\nA fast and flexible DNS forwarder designed for modern multi-environment setups.\nIt queries multiple upstream DNS servers in parallel (with optional DNS-over-TLS), and returns the first successful response — no more waiting for broken or unreachable DNS endpoints to timeout.\n\n## ✨ Why use this?\n\nIf you’ve ever:\n- Used a VPN to access internal DNS (e.g., Kubernetes `cluster.local` services)\n- Had DNS fail or hang when the VPN dropped\n- Manually edited `/etc/resolv.conf` to switch between internal and public DNS\n- Needed to mix plaintext and TLS-based DNS forwarders\n\n...then `dns-load-balancer` solves that cleanly.\n\nIt acts as a local resolver that can:\n- Query several upstream servers in parallel\n- Short-circuit and respond as soon as **any** server returns a valid response\n- Use **DNS-over-TLS** (DoT) selectively per upstream\n- Handle quirks like Kubernetes `cluster.local` domains gracefully\n\n## ⚙️ How it works\n\nWhen a DNS query is received, `dns-load-balancer`:\n1. Sends the request to all configured upstream servers (TLS or plaintext)\n2. Returns the **first successful response** (A/AAAA/other)\n3. If no valid result is found, returns a not-found error\n\nFor `cluster.local` queries, it can be configured to ignore non-`A` requests (e.g., AAAA) to reduce latency in environments like Kubernetes.\n\n## 🛠 Installation\n\n### Option 1: Homebrew (macOS \u0026 Linux)\n\n```sh\nbrew tap kometen/dns-load-balancer\nbrew install dns-load-balancer\n```\n\n### Option 2: Manual (FreeBSD)\n\n**Prerequisites:**\n\n```sh\npkg install rust cmake llvm\ncargo install --locked bindgen-cli\nexport LIBCLANG_PATH=/usr/local/llvm19/lib/libclang.so\n```\n\n**Build and install:**\n\n```sh\ncargo build --release\ncp ./target/release/dns_load_balancer /usr/local/bin/dns-load-balancer\n```\n\n**Enable as a service:**\n\n1. Copy the `dnsloadbalancer` service file to `/usr/local/etc/rc.d/`\n\n2. Make it executable:\n\n```sh\nchmod 0755 /usr/local/etc/rc.d/dnsloadbalancer\n```\n\n3. Add to `/etc/rc.conf`:\n\n```sh\ndnsloadbalancer_enable=\"YES\"\n```\n\n4. Start it:\n\n```sh\nservice dnsloadbalancer start\n```\n\n## 🔧 Configuration\n\nGenerate an example config:\n\n```sh\ndns-load-balancer example \u003e /usr/local/etc/dns-load-balancer.toml\n```\n\nEdit it to your needs:\n\n```toml\n[[servers]]\naddress = \"1.1.1.1\"\nuse_tls = true\ndescription = \"Cloudflare DNS\"\n\n[[servers]]\naddress = \"8.8.8.8\"\nuse_tls = true\ndescription = \"Google DNS\"\n\n[[servers]]\naddress = \"10.152.183.10\"\nuse_tls = false\ndescription = \"Kubernetes internal DNS\"\n```\n\nIf you want to run on port 53 (privileged), run as root or via a service manager. Otherwise, you can choose any unprivileged port (e.g., 5353) and configure BIND to forward to it.\n\n## 🧩 Integrating with BIND\n\nTo use `dns-load-balancer` as a forwarder for BIND:\n\nIn `named.conf`:\n```conf\noptions {\n    listen-on { 10.254.253.4; }; // Your primary interface\n    forwarders {\n        127.0.0.1 port 5353;\n    };\n    forward only;\n};\n```\n\n## ✅ Example Use Case\n\n```sh\n$ host postgresql.invoice.svc.cluster.local\npostgresql.invoice.svc.cluster.local has address 10.152.183.95\n```\n\nWhen disconnected from VPN:\n\n```sh\nDNS resolution failed: Failed to resolve hostname: postgresql.invoice.svc.cluster.local.\nRoot cause: no record found for Query { name: ..., type: AAAA }\n```\n\nWithout needing to change config, the load balancer continues resolving public domains using Cloudflare or Google DNS, and will only fail for cluster-specific records when the VPN is down.\n\n## 📦 Features\n\t•\t✅ Parallel DNS querying\n\t•\t✅ DNS-over-TLS (DoT) support\n\t•\t✅ Kubernetes-aware: filter non-A records\n\t•\t✅ Simple TOML config\n\t•\t✅ Usable as a local forwarder for BIND, Unbound, etc.\n\t•\t✅ Works on FreeBSD, Linux, macOS\n\n💡 Inspired by a real need\n\nThis project was built to avoid DNS pain when juggling public and private networks, especially when VPNs are flaky or DNS servers are inconsistent. It started as a quick solution built with Claude AI and Rust — and turned out to be much more useful than expected.\n\n⸻\n\nFeel free to contribute, file issues, or fork for your own use cases.\nHappy resolving! 🎉\n\n```mermaid\nstateDiagram\n    state \"client\" as client1\n    state \"client\" as client2\n    state \"dns load balancer\" as DLB\n    state \"First response returned\" as response\n    state \"Cloudflare DNS\u003c/br \u003e1.1.1.1\u003c/br \u003eTLS\" as cloudflare\n    state \"Google DNS\u003c/br \u003e8.8.8.8\u003c/br \u003eTLS\" as google\n    state \"Kubernetes DNS\u003c/br \u003e10.152.183.10\u003c/br \u003etext\" as kubernetes\n    \n    client1 --\u003e DLB : query\n\n    DLB --\u003e cloudflare:::center\n    DLB --\u003e google:::center\n    DLB --\u003e kubernetes:::center\n    \n    cloudflare --\u003e response\n    google --\u003e response\n    kubernetes --\u003e response\n    \n    response --\u003e client2\n    \n    classDef center text-align:center\n        \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkometen%2Fdns-load-balancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkometen%2Fdns-load-balancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkometen%2Fdns-load-balancer/lists"}