Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -250,9 +250,12 @@ describes the source definitions.
`--host-loopback-forward <tcp|udp:HOST-PORT:GUEST-PORT>` 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
Expand Down Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
37 changes: 29 additions & 8 deletions openvmm/openvmm_entry/src/microvm/verify.rs
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ fn success_line(hypervisor: &str, node: &inspect::Node) -> anyhow::Result<String
/// the error chain, or `none`, and the escaped error chain.
fn failure_line(hypervisor: &str, err: &anyhow::Error) -> 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 {
Expand All @@ -109,22 +109,23 @@ 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:?}")
}
_ => format!("fatal error: {err:?}"),
}
}

/// 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..];
Expand Down Expand Up @@ -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")
);
}
}
59 changes: 58 additions & 1 deletion vm/devices/net/net_consomme/src/resolver.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -124,3 +129,55 @@ impl ResolveResource<NetEndpointHandleKind, ConsommeHandle> 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})"
)
);
}
}
Loading