Guide: add consomme networking backend page by jstarks · Pull Request #3108 · microsoft/openvmm

jstarks · 2026-03-23T20:57:03Z

Add a dedicated Guide page for the consomme user-mode NAT backend, covering protocol handling (TCP split-proxy, UDP, DNS, ICMP, ARP/NDP, DHCP), default network topology, checksum/segmentation offload support, and known limitations. Includes a Mermaid data flow diagram.

Copilot

Pull request overview

Adds a new reference page under Guide/ documenting the consomme user-mode NAT networking backend, intended to explain how guest Ethernet frames are translated into host networking behavior and what limitations apply.

Changes:

Added Guide/src/reference/backends/consomme.md describing protocol handling (TCP/UDP/DNS/ICMP/ARP/NDP/DHCP), default topology, offloads, and limitations, plus a Mermaid flow diagram.
Wired the new page into the Guide navigation by adding it to Guide/src/SUMMARY.md.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
Guide/src/reference/backends/consomme.md	New backend reference page describing Consomme behavior, data flow, and limitations.
Guide/src/SUMMARY.md	Adds the Consomme page under Reference → Device Backends → Networking.

Copilot · 2026-03-23T21:01:47Z

Guide/src/reference/backends/consomme.md

+Each unique guest source address gets a host-side UDP socket bound to
+an ephemeral port. Datagrams are forwarded in both directions. Idle
+bindings are cleaned up after 5 minutes (per RFC 4787).


This description is slightly inaccurate: Consomme creates/keys UDP bindings per unique guest source socket (IP + port), not just per source address, and the timeout is configurable (default 5 minutes). Consider rewording to reflect the guest_addr keying and that 5 minutes is the default rather than a fixed value.

Suggested change

Each unique guest source address gets a host-side UDP socket bound to

an ephemeral port. Datagrams are forwarded in both directions. Idle

bindings are cleaned up after 5 minutes (per RFC 4787).

Each unique guest source socket (guest IP + source port) gets a

host-side UDP socket bound to an ephemeral port. Datagrams are

forwarded in both directions. Idle bindings are cleaned up after a

configurable timeout (5 minutes by default, per RFC 4787).

Copilot · 2026-03-23T21:01:48Z

Guide/src/reference/backends/consomme.md

+Queries to the gateway on port 53 are intercepted and forwarded to the
+host's DNS resolver. On Windows, this uses the `DnsQueryRaw` API, which
+forwards the raw DNS packet without parsing — the host resolver handles
+all the logic and returns a raw response. This means guest DNS


The DNS section currently states “On Windows, this uses the DnsQueryRaw API …”. Since the crate has a Unix DNS resolver backend too, please add a brief note describing the Unix/Linux behavior (e.g., uses system resolver configuration from resolv.conf and forwards via host UDP/TCP sockets), or otherwise qualify the statement so readers don’t assume this is Windows-only.

Suggested change

all the logic and returns a raw response. This means guest DNS

all the logic and returns a raw response. On Unix-like hosts, Consomme

uses the system resolver configuration (for example `/etc/resolv.conf`)

and forwards queries via host UDP/TCP sockets. This means guest DNS

Copilot · 2026-03-23T21:01:48Z

Guide/src/reference/backends/consomme.md

+ordinary host sockets. It runs entirely unprivileged — no admin rights,
+no driver installation, no system-wide network configuration. Because
+all traffic flows through standard socket APIs, host networking policies
+(firewalls, VPN routing, proxy settings) apply naturally, just as they
+would for any other application.


The intro claims Consomme runs “entirely unprivileged — no admin rights”. On Unix/Linux, ICMP forwarding uses an ICMP socket and may require either CAP_NET_RAW or net.ipv4.ping_group_range to be configured to allow unprivileged ping sockets. Please qualify this statement (e.g., note the Linux sysctl requirement for ICMP, or scope the claim to TCP/UDP/DNS/DHCP).

Suggested change

ordinary host sockets. It runs entirely unprivileged — no admin rights,

no driver installation, no system-wide network configuration. Because

all traffic flows through standard socket APIs, host networking policies

(firewalls, VPN routing, proxy settings) apply naturally, just as they

would for any other application.

ordinary host sockets. For TCP, UDP, DNS, and DHCP traffic it runs

entirely unprivileged — no admin rights, no driver installation, no

system-wide network configuration. ICMP (ping) forwarding on Unix/Linux

may require additional privileges (for example `CAP_NET_RAW`) or

configuring the `net.ipv4.ping_group_range` sysctl to permit

unprivileged ping sockets. Because all traffic flows through standard

socket APIs, host networking policies (firewalls, VPN routing, proxy

settings) apply naturally, just as they would for any other application.

Copilot · 2026-03-23T21:01:48Z

Guide/src/reference/backends/consomme.md

+        TCPProxy & UDPProxy & ICMPFwd --> Sockets["Winsock Sockets"]
+        DNSFwd -- "DnsQueryRaw" --> WinDNS["Windows DNS API"]
+        DHCPSrv -. "replies directly to guest" .-> VNIC
+    end
+
+    subgraph Kernel ["Host Kernel"]
+        Sockets --> HostStack["Windows TCP/IP Stack + Firewall + VPN"]
+        WinDNS --> HostStack


The Mermaid diagram is Windows-specific (“Winsock Sockets”, “Windows DNS API”, “Windows TCP/IP Stack”) but the consomme crate has both cfg(windows) and cfg(unix) implementations. Please either (a) make the diagram OS-neutral (e.g., “host sockets”, “platform DNS resolver”, “host TCP/IP stack”), or (b) explicitly label it as the Windows data path and add a short note about the Unix/Linux equivalents.

Suggested change

TCPProxy & UDPProxy & ICMPFwd --> Sockets["Winsock Sockets"]

DNSFwd -- "DnsQueryRaw" --> WinDNS["Windows DNS API"]

DHCPSrv -. "replies directly to guest" .-> VNIC

end

subgraph Kernel ["Host Kernel"]

Sockets --> HostStack["Windows TCP/IP Stack + Firewall + VPN"]

WinDNS --> HostStack

TCPProxy & UDPProxy & ICMPFwd --> Sockets["Host sockets"]

DNSFwd -- "DNS API call" --> HostDNS["Platform DNS resolver"]

DHCPSrv -. "replies directly to guest" .-> VNIC

end

subgraph Kernel ["Host Kernel"]

Sockets --> HostStack["Host TCP/IP stack + firewall + VPN"]

HostDNS --> HostStack

Copilot AI review requested due to automatic review settings March 23, 2026 20:57

github-actions bot added the Guide label Mar 23, 2026

Copilot started reviewing on behalf of jstarks March 23, 2026 20:58 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guide: add consomme networking backend page#3108

Guide: add consomme networking backend page#3108
jstarks wants to merge 1 commit intomicrosoft:mainfrom
jstarks:consomme-docs

jstarks commented Mar 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 23, 2026

Uh oh!

Copilot AI Mar 23, 2026

Uh oh!

Copilot AI Mar 23, 2026

Uh oh!

Copilot AI Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-Each unique guest source address gets a host-side UDP socket bound to
-an ephemeral port. Datagrams are forwarded in both directions. Idle
-bindings are cleaned up after 5 minutes (per RFC 4787).
+Each unique guest source socket (guest IP + source port) gets a
+host-side UDP socket bound to an ephemeral port. Datagrams are
+forwarded in both directions. Idle bindings are cleaned up after a
+configurable timeout (5 minutes by default, per RFC 4787).

-all the logic and returns a raw response. This means guest DNS
+all the logic and returns a raw response. On Unix-like hosts, Consomme
+uses the system resolver configuration (for example `/etc/resolv.conf`)
+and forwards queries via host UDP/TCP sockets. This means guest DNS

-ordinary host sockets. It runs entirely unprivileged — no admin rights,
-no driver installation, no system-wide network configuration. Because
-all traffic flows through standard socket APIs, host networking policies
-(firewalls, VPN routing, proxy settings) apply naturally, just as they
-would for any other application.
+ordinary host sockets. For TCP, UDP, DNS, and DHCP traffic it runs
+entirely unprivileged — no admin rights, no driver installation, no
+system-wide network configuration. ICMP (ping) forwarding on Unix/Linux
+may require additional privileges (for example `CAP_NET_RAW`) or
+configuring the `net.ipv4.ping_group_range` sysctl to permit
+unprivileged ping sockets. Because all traffic flows through standard
+socket APIs, host networking policies (firewalls, VPN routing, proxy
+settings) apply naturally, just as they would for any other application.

Conversation

jstarks commented Mar 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants