Unraid CoreDNS Plugin (Zero Docker)

A robust, reliable plugin to run CoreDNS natively on Unraid without Docker. Starts early on boot, stores config on flash, writes logs to RAM, and exposes a native Unraid WebUI with full service control.

Designed specifically for Tailscale split DNS — CoreDNS answers queries for your internal zone before the Unraid array is mounted.

🚀 Key Features

• No Docker required — runs directly alongside emhttpd
• Boot-early DNS — starts before the array mounts; essential for Tailscale split DNS
• Zero flash wear — all runtime files (PID, logs) live in RAM (/var/run, /var/log)
• Config on flash — Corefile and hosts.internal persist safely at /boot/config/plugins/coredns/config/
• Native WebGUI — Settings → CoreDNS with service controls, Corefile editor, log viewer
• Upgrade-safe — Corefile, hosts.internal, and settings.json are never overwritten on upgrade
• Port conflict detection — warns if port 53 is already claimed (e.g., by dnsmasq)
• Watchdog — automatically restarts CoreDNS if it crashes, with boot-loop protection

📥 Installation

Install through the Unraid WebGUI:

1. Navigate to Plugins → Install Plugin
2. Paste the following URL:

https://github.com/atnplex/coredns-unraid/releases/latest/download/coredns-unraid.plg

3. Click Install

To update, re-paste the URL and click Install. All your settings, Corefile, and host overrides are preserved.

📁 Directory Layout

Path	Purpose
/boot/config/plugins/coredns/config/Corefile	CoreDNS configuration (source of truth)
/boot/config/plugins/coredns/config/hosts.internal	Static host overrides
/boot/config/plugins/coredns/config/settings.json	Plugin settings (port, bind, autostart)
/var/run/coredns/coredns.pid	PID file (RAM — recreated on boot)
/var/log/coredns/coredns.log	Service log (RAM — not on flash)
/usr/local/bin/coredns	CoreDNS binary
/usr/local/emhttp/plugins/coredns/	WebUI and scripts

⚙️ Configuration

1. Open Settings → CoreDNS in the Unraid WebGUI
2. Set Bind Address and Port (default: 0.0.0.0:5353 — safe for first install)
3. Edit the Corefile in the textarea editor; click Validate to check syntax
4. Click Save Corefile
5. Enable Autostart on boot if desired
6. Click ▶ Start

⚠️ Port 53 and Port Conflicts

Unraid may run dnsmasq on port 53 for DHCP/DNS. The plugin:

• Defaults to port 5353 to avoid conflicts on fresh install
• Shows a warning banner in the WebUI if port 53 or the configured port is in use
• Will not start if the configured port is already taken

To use port 53 (required for most DNS clients):

1. Identify what is listening on port 53: ss -tlunp | grep ':53 '
2. Stop or reconfigure the conflicting service (e.g., disable dnsmasq DNS resolver)
3. Change the port to 53 in Settings → CoreDNS

🌐 Tailscale Split DNS Setup

CoreDNS is ideal for Tailscale split DNS. Example setup:

Step 1 — Edit the Corefile

In Settings → CoreDNS, edit the Corefile to add an internal zone block:

. {
    bind 0.0.0.0
    log
    errors
    cache 300
    forward . 1.1.1.1 1.0.0.1
}

home.arpa {
    bind 0.0.0.0
    log
    errors
    cache 60
    hosts /boot/config/plugins/coredns/config/hosts.internal {
        fallthrough
    }
    forward . 1.1.1.1
}

Step 2 — Add host entries to hosts.internal

In the WebUI hosts editor (or directly on the flash drive):

# /boot/config/plugins/coredns/config/hosts.internal
100.64.0.10    unraid.home.arpa
100.64.0.11    vps1.home.arpa
100.64.0.12    vps2.home.arpa

Step 3 — Configure Tailscale DNS

In the Tailscale admin console → DNS → Nameservers:

1. Add a custom nameserver for the domain home.arpa
2. Set the nameserver IP to your Unraid host's Tailscale IP (e.g., 100.64.0.10)
3. Set the port to 53

Tailscale will now forward *.home.arpa queries to CoreDNS on your Unraid host.

Important Notes

• Tailscale DNS forwarding expects port 53 for this setup; do not rely on a custom DNS port in the Tailscale client flow.
• Ensure CoreDNS is listening on port 53 on the Tailscale-reachable interface before enabling split DNS.
• If your Unraid is behind a firewall, ensure UDP/TCP port 53 is accessible on the Tailscale interface.
• home.arpa is a reserved IANA suffix appropriate for home networks. You can use any domain.

🔧 Service Control

Use the WebUI buttons or the command line:

# Commands (run as root on Unraid)
/usr/local/emhttp/plugins/coredns/scripts/corednsd start
/usr/local/emhttp/plugins/coredns/scripts/corednsd stop
/usr/local/emhttp/plugins/coredns/scripts/corednsd restart
/usr/local/emhttp/plugins/coredns/scripts/corednsd reload     # validate + restart
/usr/local/emhttp/plugins/coredns/scripts/corednsd status
/usr/local/emhttp/plugins/coredns/scripts/corednsd version
/usr/local/emhttp/plugins/coredns/scripts/corednsd validate [/path/to/Corefile]
/usr/local/emhttp/plugins/coredns/scripts/corednsd enable     # enable autostart
/usr/local/emhttp/plugins/coredns/scripts/corednsd disable    # disable autostart

# Or via the RC script:
/etc/rc.d/rc.coredns {start|stop|restart|status}

✅ Testing Checklist

After install, verify:

• CoreDNS binary installed: /usr/local/bin/coredns -version
• Default Corefile created: /boot/config/plugins/coredns/config/Corefile
• Start works: corednsd start → exit 0, PID file created
• Valid Corefile validation passes: corednsd validate
• Invalid Corefile validation fails cleanly (edit with bad syntax, test)
• DNS responds: dig @127.0.0.1 -p 5353 google.com
• Stop works: corednsd stop → PID file removed
• Restart from WebUI button works
• Logs visible in WebUI (Settings → CoreDNS → log viewer)
• Logs are in RAM, not on flash: check /var/log/coredns/ vs /boot/
• Reinstall preserves your Corefile (test by editing and reinstalling .plg)
• Autostart works across reboot (enable in UI, reboot, check ps | grep coredns)
• Port conflict warning shows if port already in use
• WebUI status badge reflects real service state

🔒 Known Limitations

1. Port 53 conflicts — Unraid dnsmasq may own port 53. Default is port 5353.
2. No custom plugin builds — v1 uses the stock CoreDNS binary only.
3. Corefile validation — Uses a "start for 1.5s + kill" approach since CoreDNS has no --dry-run. This can take ~2s and may generate brief process noise.
4. No DNSSEC, DoH, or DoT in v1.
5. No zone editor UI — Corefile is a text editor; complex config is manual.
6. Log rotation — Logs are bounded to 5000 lines in RAM only; no persistent log history.

📝 License

MIT — see LICENSE

🛡️ Upstream

• CoreDNS: https://github.com/coredns/coredns
• Tailscale DNS docs: https://tailscale.com/docs/reference/dns-in-tailscale