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
39 changes: 24 additions & 15 deletions Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,8 +237,10 @@ describes the source definitions.
with `--restore-network-policy`.
Omitting the option preserves the existing guest-gateway-to-host-loopback
mapping, from the IPv4 gateway to host IPv4 loopback and from the IPv6
gateway to host IPv6 loopback, without publishing guest ports. `deny` blocks
general gateway and host-local destinations and rejects every
gateway to host IPv6 loopback, without publishing guest ports. The guest
then reaches every host-loopback listener that its egress policy permits,
which is why microVM consoles take no TCP endpoint; see `--virtio-console`.
`deny` blocks general gateway and host-local destinations and rejects every
`--host-loopback-forward`.

`--network-proxy <IPv4:TCP-PORT>` preserves one exact proxy endpoint when
Expand Down Expand Up @@ -1038,24 +1040,31 @@ Serial devices can be configured to appear as different devices inside the guest

A microVM accepts these explicit attachment policies:

* `listen=PATH` or `listen=tcp:IP:PORT`: save the canonical endpoint and
recreate the optional listener on restore. Unix sockets must be beside the
snapshot directory. Windows pipes use the
`//./pipe/openvmm-microvm-<NAME>` namespace. TCP ports must be nonzero.
TCP addresses must be loopback addresses. A restore caller can resupply
`--virtio-console listen=<FRESH-ENDPOINT>` with `--restore-snapshot` to
replace the saved listener identity while preserving the attachment
contract. Omitting the option recreates the saved listener endpoint.
* `connect=PATH` or `connect=tcp:IP:PORT`: require a client connection before
vCPUs start. Cold boot and restore use a five-second timeout. The
restore command must explicitly resupply the matching client attachment.
* `listen=PATH`: save the canonical endpoint and recreate the optional
listener on restore. Unix sockets must be beside the snapshot directory.
Windows pipes use the `//./pipe/openvmm-microvm-<NAME>` namespace. A
restore caller can resupply `--virtio-console listen=<FRESH-ENDPOINT>` with
`--restore-snapshot` to replace the saved listener identity while
preserving the attachment contract. Omitting the option recreates the
saved listener endpoint.
* `connect=PATH`: require a client connection before vCPUs start. Cold boot
and restore use a five-second timeout. The restore command must explicitly
resupply the matching client attachment.
* `console`: require the restore caller to supply the same inherited terminal
attachment. Portb recovery output moves to stderr while the terminal is
attached to `hvc1`. A guest-requested exit writes the boot console output
that the device accepted before OpenVMM exits.
* `none`: keep the device present and explicitly discard guest TX while
disconnected.

A microVM refuses TCP endpoints, `listen=tcp:IP:PORT` and
`connect=tcp:IP:PORT`, and a snapshot whose boot console has one. Unless
`--host-loopback deny` is given, a guest's gateway maps the guest's TCP flows
onto host loopback, so any guest on the host whose egress policy permits the
port could connect to a loopback TCP listener, its own console's or another
VM's, or to the listener that a client endpoint connects to. The boot console
does not authenticate its client, so such a guest would drive the console.

A generic byte stream guarantees no replay up to OpenVMM's backend write
boundary; it cannot prove that the remote application consumed bytes without
its own acknowledgment protocol.
Expand Down Expand Up @@ -1138,8 +1147,8 @@ The `BACKEND` argument is the same for all serial devices:
up to listen on the given path. Serial input and output is relayed to this
pipe/socket.
* `listen=tcp:IP:PORT`: As with `listen=PATH`, but listen for TCP
connections on the given IP address and port. A microVM requires a
loopback IP such as `127.0.0.1` or `::1`.
connections on the given IP address and port. A microVM's consoles
refuse it and `connect=tcp:IP:PORT`; see `--virtio-console`.
* `connect=PATH`: Connect to an existing named pipe or Unix socket.
* `connect=tcp:IP:PORT`: Connect to an existing TCP listener.

Expand Down
40 changes: 35 additions & 5 deletions openvmm/openvmm_entry/src/cli_args/microvm.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1027,17 +1027,23 @@ impl Options {
"microVM requires virtio-console on its fixed MMIO transport"
);
if let Some(console) = &self.virtio_console {
anyhow::ensure!(
!matches!(
console,
SerialConfigCli::Tcp(_) | SerialConfigCli::ConnectTcp(_)
),
"{}",
crate::microvm::MICROVM_CONSOLE_TCP_REFUSED
);
anyhow::ensure!(
matches!(
console,
SerialConfigCli::Pipe(_)
| SerialConfigCli::Tcp(_)
| SerialConfigCli::ConnectPipe(_)
| SerialConfigCli::ConnectTcp(_)
| SerialConfigCli::Console
| SerialConfigCli::None
),
"microVM virtio-console requires listen=..., connect=..., console, or none"
"microVM virtio-console requires listen=PATH, connect=PATH, console, or none"
);
}
anyhow::ensure!(
Expand Down Expand Up @@ -2440,15 +2446,39 @@ mod tests {
.unwrap();
valid_mshv.validate_microvm_options().unwrap();
}
let console_endpoint = if cfg!(windows) {
"listen=//./pipe/openvmm-microvm-console-test"
} else {
"listen=console.sock"
};
let valid_console = Options::try_parse_from([
"openvmm",
"--machine",
"microvm",
"--virtio-console",
"listen=tcp:127.0.0.1:5555",
console_endpoint,
])
.unwrap();
valid_console.validate_microvm_options().unwrap();
// Guests reach loopback TCP through their gateways, so the boot
// console takes no TCP endpoint.
for tcp in ["listen=tcp:127.0.0.1:5555", "connect=tcp:127.0.0.1:5555"] {
let error = Options::try_parse_from([
"openvmm",
"--machine",
"microvm",
"--virtio-console",
tcp,
])
.unwrap()
.validate_microvm_options()
.unwrap_err();
assert_eq!(
error.to_string(),
crate::microvm::MICROVM_CONSOLE_TCP_REFUSED,
"{tcp}"
);
}
let valid_control_console = Options::try_parse_from([
"openvmm",
"--machine",
Expand Down Expand Up @@ -2570,7 +2600,7 @@ mod tests {
"--machine",
"microvm",
"--virtio-console",
"listen=tcp:127.0.0.1:5555",
console_endpoint,
"--virtio-console-pcie-port",
"port0",
],
Expand Down
9 changes: 0 additions & 9 deletions openvmm/openvmm_entry/src/microvm/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,6 @@ impl<'a> MicrovmConfigBuilder<'a> {
self.resources.console_socket_cleanup = microvm_console_socket_cleanup(path)?;
Some(backend)
}
SerialConfigCli::Tcp(address) => Some(serial_io::bind_tcp_serial(&address)?),
SerialConfigCli::ConnectPipe(path) => Some(
serial_io::connect::connect_serial_with_timeout(
&path,
Expand All @@ -321,14 +320,6 @@ impl<'a> MicrovmConfigBuilder<'a> {
)
})?,
),
SerialConfigCli::ConnectTcp(address) => {
Some(serial_io::connect::connect_tcp_serial(
&address,
Duration::from_millis(
openvmm_defs::microvm::MICROVM_CONSOLE_RECONNECT_TIMEOUT_MS,
),
)?)
}
SerialConfigCli::Console => {
let (backend, _, relay) = setup_host_console(
"virtio-console",
Expand Down
Loading
Loading