mikrotik-doh-failover#

Failover DNS-over-HTTPS (DoH) configuration for MikroTik RouterOS, as diffable .rsc scripts.

Docs · Releases · Changelog · Issues · Security · For agents

<img src="https://github.com/paulmann/mikrotik-doh-failover/raw/main/assets/social-preview.png" alt="mikrotik-doh-failover: one verified DoH upstream for RouterOS, with a plain-DNS fallback that flips use-doh-server automatically" width="100%">

RouterOS routes a LAN's DNS through the router, but by default that upstream leg
is plaintext. This project configures one verified DoH upstream with a
plain-DNS fallback, forces classic LAN DNS to the router, and adds a scheduled
health-check that switches between DoH and plain DNS on failure. It is the
"how to reproduce and maintain" companion to the article
«Архитектура отказоустойчивого DNS-over-HTTPS в RouterOS»
on sysadministrator.ru.

Documentation status. Counts in this README were measured from the
published tree on 2026-10-22 (v0.1.0). Long-form design rationale is in
docs/; the scripts were verified on RouterOS 7.23.1 and 7.24.5.

Contents#

• What this is and why

• Capabilities

• By the numbers

• How it works

• Installation

• First steps

• Reliability and limits

• Security

• Requirements and compatibility

• Documentation

• Contributing

• License

What this is and why#

A common broken approach to "DoH on MikroTik" is to add several DoH servers via
/ip dns static-server type=doh and expect failover. That syntax does not exist
and does not produce redundancy; RouterOS supports exactly one use-doh-server.
Another common failure is verify-doh-cert=yes without a trusted CA, which
silently stops all resolution.

This project avoids both:

• one active DoH upstream, with plain servers as bootstrap and fallback;

• a managed failover script that clears use-doh-server on failure and
  restores it after recovery;

• an explicit CA import — verified that the built-in trust store does not
  cover the Cloudflare chain on 7.23/7.24;

• bootstrap static A records so the DoH hostname resolves even if plain DNS
  is down.

Every claim in this README and in docs/ was verified on real devices; the
version and device-mode are stated where behaviour differs.

Capabilities#

By the numbers#

Measured from the published tree on 2026-10-22 (v0.1.0):

How it works#

flowchart LR
    Client["LAN client"] -->|"DNS 53"| ForceDNS["force-DNS redirect"]
    ForceDNS --> Resolver["Router resolver"]
    Resolver --> Mode{"DoH healthy?"}
    Mode -->|"yes"| DoH["DoH upstream<br/>verify-doh-cert=yes"]
    Mode -->|"no"| Plain["plain family DNS"]
    Monitor["health monitor 3m"] -->|"flips use-doh-server"| Resolver
    CA["Trusted CA"] -->|"TLS validation"| DoH
    NTP["NTP"] -->|"clock"| CA

Installation#

Requirements:

• RouterOS 7.20+ (verified 7.23.1, 7.24.5);

• NTP synchronized;

• device-mode advanced for the automatic failover scheduler.

Quick start (Cloudflare Family):

# 1. Upload certs/cloudflare-doh-ca.crt to the router, then:
/import file-name=00-install-ca.rsc
/import file-name=01-configure-doh.rsc
/import file-name=02-security-policies.rsc
/import file-name=05-dns-health-monitor.rsc

For other providers (Quad9, Google, Cloudflare standard/security) edit the
values in routeros/config.example.rsc.

First steps#

/ip dns cache flush
:put [:resolve example.com]     # real IP
:put [:resolve pornhub.com]     # 0.0.0.0 with the Family filter
/log print where message~"connection error"

Reliability and limits#

Scheduler rejected: not allowed by device-mode#

On devices with device-mode=home (for example the RB4011iGS+ tested here),
RouterOS rejects /system scheduler add and /tool fetch with
not allowed by device-mode. This is an expected RouterOS limit, not a script
defect: the DoH config and force-DNS still work, but the failover monitor can
only be run manually. Options:

1. leave home and run /system script run DNS_HealthMonitor_Failover by hand;

2. switch to advanced to enable the scheduler:

   /system/device-mode/update device-mode=advanced

   then confirm the change and reboot.

Security#

• The resolver drops DNS from WAN and only redirects classic DNS (53); client
  DoH (443) and DoT (853) bypass is documented, not hidden.

• Choosing Cloudflare/Quad9/Google means trusting that third party with your
  queries; DoH hides them from the local link only.

• CA bootstrap must use a trusted source; check-certificate=no is bootstrap-only.

• See SECURITY.md for reporting and the security model.

Requirements and compatibility#

Documentation#

Contributing#

Read CONTRIBUTING.md. Security issues: SECURITY.md,
never a public issue.

License#

MIT © 2026 Mikhail Deynekin.