DNS Heaven

DNS Heaven is a small yet powerful DNS tool designed specifically for macOS. Its primary purpose is to fix a common issue with macOS's DNS stack, enabling command-line tools that rely on the traditional /etc/resolv.conf file (such as dig, nslookup, and Go-compiled programs) to properly utilize macOS’s native advanced DNS features.

Core Features and Advantages

1. Solving the "Split" DNS Issue on macOS

macOS features a powerful native DNS resolution system (managed via scutil) that supports many advanced capabilities. However, many traditional Unix tools and programming language libraries (especially Go) do not directly use this modern stack; instead, they read the standard /etc/resolv.conf file. For compatibility, macOS writes only a simplified DNS configuration to this file (typically just the primary DNS server and search domains), causing:

• Problem: Advanced DNS features become ineffective in these tools. For example, when using an enterprise VPN with "Split DNS" (domain-based routing) or different DNS servers configured on separate network interfaces (e.g., Wi-Fi and Ethernet), tools like dig or nslookup may fail to resolve correctly, as they cannot detect these complex rules.
• DNS Heaven’s Solution: It runs as a background daemon, continuously monitoring the system-wide DNS configuration on macOS, and proxies and translates these complex rules, ensuring that all tools querying via /etc/resolv.conf receive resolution results consistent with the native stack.

2. Automatic and Transparent DNS Proxying

1. Dynamic Configuration Fetching: DNS Heaven periodically runs scutil --dns to read the full, current DNS configuration of macOS, including DNS servers per interface, domain-specific rules, and search domains.
2. Local Proxy Server: It spawns a lightweight DNS proxy server on the local loopback address (127.0.0.1:53).
3. Resolv.conf Hijacking: It modifies the system’s /etc/resolv.conf to permanently point to 127.0.0.1. Even if macOS or network changes attempt to rewrite the file, DNS Heaven ensures it always points to itself.
4. Smart Forwarding: When receiving DNS queries from command-line tools, DNS Heaven intelligently forwards them to the correct upstream DNS server (e.g., deciding whether to route through company internal DNS or public DNS based on domain), then returns the results to the requesting tool.

3. Simple and Convenient Installation & Management

• One-Click Installation: The project provides a minimalist installation script. Run the following command in the terminal to download, install, and configure the background service:

  curl -L https://git.io/fix-my-dns-plz | sudo bash
  

• Automatic Startup: The installation script automatically sets up a LaunchAgent, ensuring DNS Heaven runs in the background after system startup, requiring no user intervention.
• Manual Installation Options: Advanced users can also download pre-compiled binaries from the GitHub Releases page or compile from source.

4. Advantages Over Other Solutions (e.g., dnsmasq)

DNS Heaven’s design philosophy is "zero-configuration" and "fully follows system settings", contrasting sharply with powerful but manually-configurable tools like dnsmasq:

Feature	DNS Heaven	dnsmasq (Traditional Usage)
Configuration Complexity	Zero-configuration — automatically syncs all system DNS settings.	Requires manual configuration of upstream forwarders, rules, etc. — more complex.
Upstream Servers	Automatically uses current network DNS (e.g., DHCP-assigned) or manually set system DNS — adapts dynamically to environment changes.	Usually requires static configuration (e.g., 8.8.8.8) — may not work when switching networks (e.g., from corporate to home).
Split DNS Support	Perfectly supported — inherits all rules from macOS’s native stack.	Supported, but requires manually writing rules for each domain — cannot automatically sync complex settings from VPNs or similar scenarios.
Core Goal	Fix compatibility issues — ensures all tools see a consistent, correct DNS view.	Provide highly customizable DNS/DHCP services — more powerful, but heavier to use.

Summary: What DNS Heaven Brings You

• Seamless Experience: After installation, no changes to your workflow are needed. Whether using native macOS apps, developer tools over VPNs, or legacy Unix command-line tools, DNS resolution behavior will remain consistent and accurate.
• System-Friendly: It does not replace macOS’s native networking stack, but acts as a smart “translator” or “adapter,” bridging the gap between modern system features and traditional tools.
• Lightweight and Reliable: Built as a small, single Go-based daemon, it consumes minimal resources and offers high stability.

Target Users: Developers, system administrators, and advanced users who frequently use command-line network tools on macOS, use VPNs (especially enterprise VPNs with Split DNS), or work in complex network environments.

License: MIT Open Source License.

Get Help & Support:

• Submit issues or feedback via GitHub Issues.