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})" + ) + ); + } +}