Skip to content

docs: fix DNS lookup delay from IPv6 resolver stall#6033

Open
RyanJHamby wants to merge 2 commits into
firecracker-microvm:mainfrom
RyanJHamby:docs/getting-started-dns-ipv6-delay
Open

docs: fix DNS lookup delay from IPv6 resolver stall#6033
RyanJHamby wants to merge 2 commits into
firecracker-microvm:mainfrom
RyanJHamby:docs/getting-started-dns-ipv6-delay

Conversation

@RyanJHamby

@RyanJHamby RyanJHamby commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Changes

Adds a resolv.conf single-request-reopen option to the guest network
setup steps in docs/getting-started.md.

Reason

Closes #5512. The getting-started guide only configures IPv4 networking
for the guest. glibc's resolver still attempts parallel A/AAAA DNS
lookups by default, and on an IPv6-connected host the AAAA query can
stall on host NAT, adding seconds per lookup.

single-request alone only serializes the two queries but keeps them
on the same source port, so it doesn't help when the drop is on the
5-tuple itself, which is the usual case here. single-request-reopen
closes and reopens the socket between the two queries, so the second
query goes out on a fresh source port with a distinct 5-tuple, which
is what actually avoids the stall. This was confirmed as the fix by
the issue reporter, and a maintainer invited a documentation PR for it.

License Acceptance

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.

PR Checklist

  • I have read and understand CONTRIBUTING.md.
  • I have run tools/devtool checkbuild --all to verify that the PR passes
    build checks on all supported architectures. (N/A — docs-only change, no
    Rust code touched; skipped since it doesn't exercise this change)
  • I have run tools/devtool checkstyle to verify that the PR passes the
    automated style checks. (test_markdown_style and
    test_markdown_internal_links both passed)
  • I have described what is done in these changes, why they are needed, and
    how they are solving the problem in a clear and encompassing way.
  • I have updated any relevant documentation (both in code and in the docs)
    in the PR.
  • I have mentioned all user-facing changes in CHANGELOG.md. (docs-only
    fix to a getting-started walkthrough; please advise if this warrants an
    entry)
  • If a specific issue led to this PR, this PR closes the issue. ([Bug] example rootfs incurs 5s DNS lookup delay #5512)
  • When making API changes, I have followed the
    Runbook for Firecracker API changes. (N/A — no API changes)
  • I have tested all new and changed functionalities in unit tests and/or
    integration tests. (N/A — docs-only change, not applicable to unit/integration
    tests; verified via markdown style checks instead)
  • I have linked an issue to every new TODO. (N/A — no new TODOs added)

  • This functionality cannot be added in rust-vmm. (N/A — this is a
    documentation fix, not new functionality)

The getting-started guide only configures IPv4 networking for the
guest, but glibc's resolver still attempts parallel A/AAAA lookups
by default. If the host has IPv6 connectivity, the guest's IPv6
query stalls until timeout before falling back to IPv4, adding
several seconds to every DNS lookup (see firecracker-microvm#5512).

Setting 'single-request-reopen' in resolv.conf makes the resolver
issue A and AAAA queries sequentially over separate sockets,
avoiding the stall.

Tested with ./tools/devtool checkstyle — all style/markdown checks
passed, including test_markdown_style and test_markdown_internal_links.

Signed-off-by: RyanJHamby <ryanhamby22@gmail.com>
@not4s not4s self-assigned this Jul 15, 2026
@not4s not4s linked an issue Jul 15, 2026 that may be closed by this pull request
2 tasks
@not4s

not4s commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Thanks for picking this up,

  1. The inline comment is a bit long, I would go with something like
  # glibc resolves A/AAAA in parallel; on an IPv6-connected host the AAAA query
  # can stall on host NAT, adding seconds per lookup.
  ssh -i $KEY_NAME root@172.16.0.2  "echo 'options single-request-reopen' >> /etc/resolv.conf"
  1. nit context for the PR: it'd be good to note why single-request-reopen specifically rather than plain single-request. single-request only serializes the two queries but reuses the same source port, so it doesn't help when the collision is on the 5-tuple itself, which is the usual case. single-request-reopen opens a new socket, so the second query gets a fresh source port and a distinct 5-tuple, which is what actually sidesteps the drop.

Comment thread docs/getting-started.md Outdated

# This guide only configures IPv4 networking for the guest. If the host has
# IPv6 connectivity, glibc's resolver will attempt parallel A/AAAA lookups by
# default, and the IPv6 attempt will stall until it times out before falling

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the IPv6 attempt will stall until it times out reads a bit strong; it's intermittent and kernel dependent, so to me 'can stall' is more accurate.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review. Updated the comment to your suggested wording.

On single-request-reopen versus single-request: single-request serializes the two queries but keeps the same source port, so if the drop is happening on the 5-tuple, which is the case here, reusing the port does not change anything and the second query still stalls. single-request-reopen closes and reopens the socket between queries, so the AAAA query goes out on a fresh source port with a distinct 5-tuple, which is what actually avoids the stall. I will add this explanation to the PR description as well.

Shortens the inline comment explaining the single-request-reopen fix
per review feedback on firecracker-microvm#6033, and softens 'will stall until it times
out' to 'can stall', since the behavior is intermittent and kernel
dependent rather than guaranteed.

Tested with ./tools/devtool checkstyle — all style/markdown checks
passed, including test_markdown_style and test_markdown_internal_links.

Signed-off-by: RyanJHamby <ryanhamby22@gmail.com>
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.

[Bug] example rootfs incurs 5s DNS lookup delay

2 participants