From e1ca353eb23c43d38b52e9b5156252fc4c7fc62d Mon Sep 17 00:00:00 2001 From: Pedro Henrique Penna Date: Thu, 5 Nov 2026 16:32:53 -0800 Subject: [PATCH] net_consomme: give a port forward that cannot bind a stable code A port forward whose host socket OpenVMM cannot bind, as when another socket holds its port, fails the resolution of the Consomme endpoint, and so the launch of the VM worker, as at a microVM restore whose --restore-network-policy installs a forward. OpenVMM then exits with a fatal error that carries no code: fatal error: failed to launch vm worker Caused by: 0: ... 1: failed to create socket for port forward (Tcp 127.0.0.1:PORT) 2: NVX attributes that failure to the host by the text of the cause alone, which is no contract: if OpenVMM rewords it, a clone's failure falls back to a lost status of unknown outcome (microsoft/nvx#972). Lead the SocketCreation error of the Consomme resolver with the stable code [E_PORT_FORWARD_BIND], as the time ABI errors lead with theirs. fatal_error_message already leads the fatal error with the first bracketed code of the chain, so its line now reads fatal error: [E_PORT_FORWARD_BIND] failed to launch vm worker Its helper time_abi_code becomes stable_code, since the codes that it finds are no longer the time ABI's alone. The CLI guide gives the code with --host-loopback-forward and --restore-network-policy, and the snapshot guide with the time ABI's codes. Tests: a resolver test binds a forward whose port another socket holds and checks that the error leads with the code; without the code, it fails. A verify test checks that the code leads the fatal error of a chain that carries it below the VM worker's context. See microsoft/nvx#972. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Guide/src/reference/openvmm/management/cli.md | 15 +++-- Guide/src/user_guide/openvmm/snapshots.md | 5 +- openvmm/openvmm_entry/src/microvm/verify.rs | 37 +++++++++--- vm/devices/net/net_consomme/src/resolver.rs | 59 ++++++++++++++++++- 4 files changed, 100 insertions(+), 16 deletions(-) diff --git a/Guide/src/reference/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index b56b3e99391..6323399aca2 100644 --- a/Guide/src/reference/openvmm/management/cli.md +++ b/Guide/src/reference/openvmm/management/cli.md @@ -250,9 +250,12 @@ describes the source definitions. `--host-loopback-forward ` binds one localhost port and forwards it into the guest, possibly to another guest port. It requires explicit `--host-loopback allow`; duplicate bindings and more than - 64 forwards are rejected before resources are opened. Live forwards are - process-local attachments: snapshot capture rejects them, and so does a - restore, unless it installs a new policy with `--restore-network-policy`. + 64 forwards are rejected before resources are opened. A port that OpenVMM + cannot bind, such as one that another socket holds, fails the VM's launch + with the stable code `E_PORT_FORWARD_BIND`, which leads OpenVMM's fatal + error. Live forwards are process-local attachments: snapshot capture rejects + them, and so does a restore, unless it installs a new policy with + `--restore-network-policy`. Networked snapshots record the `portable` profile, drain accepted TX and endpoint-ready RX at the capture boundary, rewind unused guest RX @@ -574,9 +577,9 @@ describes the source definitions. that it never had. OpenVMM validates the policy as at a cold boot, binds it to the captured identity, which the NIC keeps, and installs it, with its forwards bound, before any vCPU runs; a policy that fails validation, or a - forward that cannot bind its port, fails the restore. A restore that wants - no connectivity passes the template's own deny-all. The restore cannot - readdress the NIC. OpenVMM rejects the option before any vCPU + forward that cannot bind its port (`E_PORT_FORWARD_BIND`), fails the restore. + A restore that wants no connectivity passes the template's own deny-all. The + restore cannot readdress the NIC. OpenVMM rejects the option before any vCPU starts for a cold boot, for a `workload-start` or `instance-checkpoint` snapshot, for a snapshot without a NIC, and for a NIC captured with any other policy. The guest keeps its captured command line, so it learns its DNS diff --git a/Guide/src/user_guide/openvmm/snapshots.md b/Guide/src/user_guide/openvmm/snapshots.md index 01e5115f718..4b2b3587ed5 100644 --- a/Guide/src/user_guide/openvmm/snapshots.md +++ b/Guide/src/user_guide/openvmm/snapshots.md @@ -440,7 +440,10 @@ timer and a periodically counting PIT channel 0 (`E_LAPIC_PERIODIC`, `E_LAPIC_TSC_DEADLINE`, `E_PIT_ACTIVE`). A time ABI error leads its message with a stable code in brackets, for -example `[E_TSC_RATE_TOLERANCE]`, and OpenVMM exits with status 1. For host +example `[E_TSC_RATE_TOLERANCE]`, and OpenVMM exits with status 1. OpenVMM's +fatal error leads with the first such code of its error chain, which may also +be `E_PORT_FORWARD_BIND`, the code of a port forward whose host socket OpenVMM +cannot bind, as at a restore that installs a new network policy. For host qualification, `--x-time-abi-verify` builds the partition, runs these checks without starting the guest, prints one `NVX-TIME-ABI-VERIFY:` line, and exits with status 0 or 1. diff --git a/openvmm/openvmm_entry/src/microvm/verify.rs b/openvmm/openvmm_entry/src/microvm/verify.rs index 1f2cc267b23..6dbf63f33a5 100644 --- a/openvmm/openvmm_entry/src/microvm/verify.rs +++ b/openvmm/openvmm_entry/src/microvm/verify.rs @@ -90,7 +90,7 @@ fn success_line(hypervisor: &str, node: &inspect::Node) -> anyhow::Result String { let detail = format!("{err:#}"); - let code = time_abi_code(&detail).unwrap_or("none"); + let code = stable_code(&detail).unwrap_or("none"); let mut escaped = String::new(); for c in detail.chars() { if escaped.len() >= MAX_DETAIL_LEN { @@ -109,12 +109,13 @@ fn failure_line(hypervisor: &str, err: &anyhow::Error) -> String { format!("{PREFIX} v=1 status=fail backend={hypervisor} code={code} detail=\"{escaped}\"") } -/// Formats the process's fatal-error message. A time ABI failure leads with -/// its stable code wherever the error chain carries it, so callers can match -/// the start of the message. +/// Formats the process's fatal-error message. A failure with a stable code, +/// such as a time ABI failure or a port forward that cannot bind, leads with +/// its code wherever the error chain carries it, so callers can match the +/// start of the message. pub(crate) fn fatal_error_message(err: &anyhow::Error) -> String { let chain = format!("{err:#}"); - match time_abi_code(&chain) { + match stable_code(&chain) { Some(code) if !chain.starts_with(&format!("[{code}]")) => { format!("fatal error: [{code}] {err:?}") } @@ -122,9 +123,9 @@ pub(crate) fn fatal_error_message(err: &anyhow::Error) -> String { } } -/// Returns the first bracketed time ABI code, such as `E_TSC_SYNC_UNSUPPORTED`, -/// in an error chain. -fn time_abi_code(detail: &str) -> Option<&str> { +/// Returns the first bracketed stable code, such as `E_TSC_SYNC_UNSUPPORTED` +/// or `E_PORT_FORWARD_BIND`, in an error chain. +fn stable_code(detail: &str) -> Option<&str> { let mut rest = detail; while let Some(start) = rest.find("[E_") { let candidate = &rest[start + 1..]; @@ -224,4 +225,24 @@ mod tests { assert_eq!(message, format!("fatal error: {err:?}")); assert_eq!(message.lines().next(), Some("fatal error: no code here")); } + + #[test] + fn fatal_error_message_leads_with_the_code_of_a_port_forward_that_cannot_bind() { + // The resolver of the VM's NIC fails the launch of the VM worker, as + // at a restore that installs a new network policy. + let err = anyhow::anyhow!( + "[E_PORT_FORWARD_BIND] failed to create socket for port forward (Tcp 127.0.0.1:18080)" + ) + .context("failed to resolve the network endpoint") + .context("failed to launch vm worker"); + let message = fatal_error_message(&err); + assert_eq!( + message, + format!("fatal error: [E_PORT_FORWARD_BIND] {err:?}") + ); + assert_eq!( + message.lines().next(), + Some("fatal error: [E_PORT_FORWARD_BIND] failed to launch vm worker") + ); + } } diff --git a/vm/devices/net/net_consomme/src/resolver.rs b/vm/devices/net/net_consomme/src/resolver.rs index acf475e0dd3..c5d3f684435 100644 --- a/vm/devices/net/net_consomme/src/resolver.rs +++ b/vm/devices/net/net_consomme/src/resolver.rs @@ -39,7 +39,12 @@ pub enum ResolveConsommeError { ConflictingIpv4Configuration, #[error("Consomme exact static IPv6 configuration requires exact static IPv4 configuration")] StaticIpv6WithoutStaticIpv4, - #[error("failed to create socket for port forward ({details})")] + /// The host socket of a port forward cannot be created or bound, as when + /// another socket holds its port. The message leads with the stable code + /// `[E_PORT_FORWARD_BIND]`, which survives conversion to a string across + /// the worker boundary and error wrapping: callers match it, so its + /// spelling is part of OpenVMM's interface. + #[error("[E_PORT_FORWARD_BIND] failed to create socket for port forward ({details})")] SocketCreation { #[source] source: std::io::Error, @@ -124,3 +129,55 @@ impl ResolveResource for ConsommeResolver Ok(endpoint.into()) } } + +#[cfg(test)] +mod tests { + use super::*; + use net_backend_resources::consomme::HostIpAddress; + use net_backend_resources::consomme::HostPortConfig; + use net_backend_resources::mac_address::MacAddress; + use std::net::Ipv4Addr; + use std::net::TcpListener; + use test_with_tracing::test; + + #[test] + fn a_port_forward_that_cannot_bind_leads_with_its_stable_code() { + // Another socket holds the port that the forward binds. + let held = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).unwrap(); + let port = held.local_addr().unwrap().port(); + let resource = ConsommeHandle { + cidr: None, + static_ipv4: None, + static_ipv6: None, + ports: vec![HostPortConfig { + protocol: HostPortProtocol::Tcp, + host_address: Some(HostIpAddress::Ipv4(Ipv4Addr::LOCALHOST)), + host_port: HostPort::Fixed(port), + guest_port: 80, + }], + recv: None, + allow_host_local_access: None, + map_gateway_to_host_loopback: None, + gateway_loopback_proxy_port: None, + private_network_ingress: None, + host_loopback_ingress: false, + }; + let input = ResolveEndpointParams { + mac_address: MacAddress::new([0x52, 0x54, 0, 0, 0, 2]), + }; + let Err(error) = ConsommeResolver.resolve(resource, input) else { + panic!("bound port {port}, which another socket holds"); + }; + assert!( + matches!(error, ResolveConsommeError::SocketCreation { .. }), + "{error}" + ); + assert_eq!( + error.to_string(), + format!( + "[E_PORT_FORWARD_BIND] failed to create socket for port forward \ + (Tcp 127.0.0.1:{port})" + ) + ); + } +}