Skip to content

fix: avoid macOS mDNS 5s delay on .local hosts entries - #96

Open
kayjoosten wants to merge 1 commit into
mainfrom
fix/local-domain-dns-delay
Open

fix: avoid macOS mDNS 5s delay on .local hosts entries#96
kayjoosten wants to merge 1 commit into
mainfrom
fix/local-domain-dns-delay

Conversation

@kayjoosten

Copy link
Copy Markdown
Contributor

If applied, this commit will make the documented /etc/hosts lines for the core and stepup environments resolve instantly on macOS instead of taking ~5 seconds per fresh hostname lookup.

Why is this change needed?
Prior to this change, the /etc/hosts lines had the IP address followed directly by a real hostname. On macOS, any .local hostname looked up this way is first tried via multicast DNS (Bonjour), which times out after ~5 seconds before falling back to /etc/hosts -- regardless of the entry being present. A typical login flow crosses several *.dev.openconext.local subdomains in sequence, so this tax stacks up to several seconds per redirect hop.

How does it address the issue?
Adds a throwaway alias word ("oc1"/"oc2") directly after the IP address on each affected line. A word in that position is enough to make macOS treat the line as a normal /etc/hosts entry and skip the mDNS attempt, cutting resolution to milliseconds. Updates both README.md files and the line init.sh prints during setup, with a short comment explaining why the leading word is there.

Links / references:
https://www.peterbe.com/plog/make-.local-domains-not-slow-in-macos

If applied, this commit will make the documented /etc/hosts lines for
the core and stepup environments resolve instantly on macOS instead
of taking ~5 seconds per fresh hostname lookup.

Why is this change needed?
Prior to this change, the /etc/hosts lines had the IP address
followed directly by a real hostname. On macOS, any .local hostname
looked up this way is first tried via multicast DNS (Bonjour), which
times out after ~5 seconds before falling back to /etc/hosts --
regardless of the entry being present. A typical login flow crosses
several *.dev.openconext.local subdomains in sequence, so this tax
stacks up to several seconds per redirect hop.

How does it address the issue?
Adds a throwaway alias word ("oc1"/"oc2") directly after the IP
address on each affected line. A word in that position is enough to
make macOS treat the line as a normal /etc/hosts entry and skip the
mDNS attempt, cutting resolution to milliseconds. Updates both
README.md files and the line init.sh prints during setup, with a
short comment explaining why the leading word is there.

Links / references:
https://www.peterbe.com/plog/make-.local-domains-not-slow-in-macos
@kayjoosten

kayjoosten commented Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

Use ipv6 instead of the hack

@pmeulen

pmeulen commented Aug 6, 2026

Copy link
Copy Markdown
Member

Note that .local is a special-use domain name for hostnames on local networks that are resolved via Multicast DNS (RFC 6762). This explains the use of mDNS on systems that support it (like macOS). So the actual issue is/was that mDNS was used to resolve the IPv6 address of each *.dev.openconext.local domain, which has a 5 second timeout on OSX.

We however use .local like a private domain as-in (*.dev.openconext.local). There is historical precedent for this, but this causes name resolution side effects that will differ from device to device because of mDNS. The current best practice would be to use a .test TLD (RFC 6761), i.e. use *.openconext.test. Because of the switching costs involved I'd say we stay on .local for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants