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
7 changes: 6 additions & 1 deletion Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -1056,7 +1056,12 @@ Serial devices can be configured to appear as different devices inside the guest
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.
disconnected. A restore caller can supply
`--virtio-console listen=<FRESH-ENDPOINT>`, a Unix socket beside the
snapshot directory or a `//./pipe/openvmm-microvm-<NAME>` pipe, to read the
restored guest's console. The listener keeps discarding guest TX while no
client is connected, so the guest never waits for a client. A restore
refuses every other replacement of a disconnected console.

A microVM refuses TCP endpoints, `listen=tcp:IP:PORT` and
`connect=tcp:IP:PORT`, and a snapshot whose boot console has one. Unless
Expand Down
14 changes: 11 additions & 3 deletions Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,9 +159,17 @@ timeout; only the listener endpoint identity may change. Restore callers use
listener, `--microvm-control-console listen=<FRESH-ENDPOINT>` with
`--microvm-control-auth-stdin`. OpenVMM validates an approved replacement
without reopening or canonicalizing the captured listener path, so the source
generation's private directory need not survive until restore. Client,
inherited-provider, and disconnected attachments retain their stricter saved
identity requirements.
generation's private directory need not survive until restore. Client and
inherited-provider attachments retain their stricter saved identity
requirements. A disconnected boot console, which `--virtio-console none`
captures, may take a listener at restore,
`--virtio-console listen=<FRESH-ENDPOINT>`: a Unix socket beside the snapshot
directory, or a named pipe in the `//./pipe/openvmm-microvm-<NAME>` namespace,
as a saved listener must be. The device is the one that the snapshot saved, so
the listener keeps discarding guest TX while no client is connected, and a
restored guest never waits for a client that went away. A disconnected console
takes no other attachment, and a disconnected control console stays
disconnected.

MicroVM orchestrators can add `--restore-ready-path <PATH>`. OpenVMM connects
to an existing Unix domain socket on Linux or named pipe on Windows and writes
Expand Down
13 changes: 6 additions & 7 deletions openvmm/openvmm_entry/src/microvm/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ use super::console::ConsoleEndpoint;
use super::console::effective_microvm_console;
use super::console::effective_microvm_control_console;
use super::console::microvm_console_attachments_share_endpoint;
use super::console::microvm_console_disconnect_policy;
use super::console::microvm_console_socket_cleanup;
use super::console::microvm_control_broker_config;
use super::console::validate_microvm_console_attachment_namespace;
Expand Down Expand Up @@ -55,7 +56,6 @@ use std::cell::RefCell;
use std::path::PathBuf;
use std::time::Duration;
use virtio_resources::console::attachment::VirtioConsoleDisconnectPolicy;
use virtio_resources::console::attachment::VirtioConsoleReconnectPolicy;
use virtio_resources::console::control::VirtioControlConsoleBrokerConfig;
use vm_manifest_builder::MachineArch;
use vm_resource::IntoResource;
Expand Down Expand Up @@ -653,12 +653,11 @@ impl<'a> MicrovmConfigBuilder<'a> {
) -> virtio_resources::console::VirtioConsoleHandle {
virtio_resources::console::VirtioConsoleHandle {
backend,
disconnect_policy: if self.active
&& !self.console.as_ref().is_some_and(|(_, attachment, _)| {
attachment.reconnect_policy
== VirtioConsoleReconnectPolicy::DiscardWhileDisconnected
}) {
VirtioConsoleDisconnectPolicy::Retain
disconnect_policy: if self.active {
self.console.as_ref().map_or(
VirtioConsoleDisconnectPolicy::Retain,
|(_, attachment, _)| microvm_console_disconnect_policy(attachment),
)
} else {
VirtioConsoleDisconnectPolicy::Discard
},
Expand Down
299 changes: 299 additions & 0 deletions openvmm/openvmm_entry/src/microvm/console.rs
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,66 @@ pub(super) fn microvm_console_listener_replacement_matches(
&& saved.reconnect_timeout_ms == requested.reconnect_timeout_ms
}

/// Returns whether `requested` is a listener that a restore attached to
/// `saved`, a disconnected boot console: a Unix socket or named pipe that
/// keeps discarding guest output while no client is connected, so that only
/// the endpoint differs from the saved attachment.
pub(super) fn microvm_console_discarding_listener_matches(
saved: &openvmm_helpers::snapshot::microvm::SnapshotAttachment,
requested: &openvmm_helpers::snapshot::microvm::SnapshotAttachment,
) -> bool {
saved.stable_id == MICROVM_CONSOLE_STABLE_ID
&& saved.kind == MICROVM_CONSOLE_ATTACHMENT_KIND
&& saved.reconnect_policy == "discard-while-disconnected"
&& saved.identity_kind == "disconnected"
&& saved.stable_id == requested.stable_id
&& saved.kind == requested.kind
&& saved.required == requested.required
&& saved.reconnect_policy == requested.reconnect_policy
&& matches!(
requested.identity_kind.as_str(),
"unix-socket" | "named-pipe"
)
&& saved.length == requested.length
&& saved.reconnect_timeout_ms == requested.reconnect_timeout_ms
}

/// Returns the attachment of a listener at `requested`, a Unix socket or named
/// pipe, that a restore attaches to a disconnected boot console. Like the
/// disconnected attachment, it discards guest output while no client is
/// connected, so the guest never waits for a client.
fn microvm_console_discarding_listener(
requested: &SerialConfigCli,
) -> anyhow::Result<ConsoleEndpoint> {
use virtio_resources::console::attachment::VirtioConsoleReconnectPolicy;

anyhow::ensure!(
matches!(requested, SerialConfigCli::Pipe(_)),
"a restore attaches only a socket or pipe listener to a disconnected virtio-console"
);
let (effective, mut attachment, mut snapshot) = microvm_console_attachment_from_cli(requested)?;
attachment.reconnect_policy = VirtioConsoleReconnectPolicy::DiscardWhileDisconnected;
snapshot.reconnect_policy = "discard-while-disconnected".to_owned();
Ok((effective, attachment, snapshot))
}

/// Returns what the boot console's device does with guest output while no
/// client is connected to its host endpoint: a disconnected attachment, or a
/// listener that a restore attached to one, discards it, and every other
/// attachment retains it until a client connects.
pub(crate) fn microvm_console_disconnect_policy(
attachment: &virtio_resources::console::attachment::VirtioConsoleAttachment,
) -> virtio_resources::console::attachment::VirtioConsoleDisconnectPolicy {
use virtio_resources::console::attachment::VirtioConsoleDisconnectPolicy;
use virtio_resources::console::attachment::VirtioConsoleReconnectPolicy;

if attachment.reconnect_policy == VirtioConsoleReconnectPolicy::DiscardWhileDisconnected {
VirtioConsoleDisconnectPolicy::Discard
} else {
VirtioConsoleDisconnectPolicy::Retain
}
}

pub(crate) struct MicrovmConsoleSocketCleanup {
#[cfg(unix)]
path: PathBuf,
Expand Down Expand Up @@ -529,6 +589,20 @@ fn microvm_console_attachment_from_snapshot_with_identity(
"snapshot microVM console identity is not canonical"
);
if let Some(requested) = requested {
// A restore may attach a socket or pipe listener to a disconnected
// boot console, which then keeps discarding guest output while no
// client is connected.
if !control_console
&& attachment.reconnect_policy == "discard-while-disconnected"
&& matches!(requested, SerialConfigCli::Pipe(_))
{
let listener = microvm_console_discarding_listener(requested)?;
anyhow::ensure!(
microvm_console_discarding_listener_matches(attachment, &listener.2),
"restore-time virtio-console listener does not match the snapshot attachment contract"
);
return Ok(listener);
}
let requested = if control_console {
microvm_control_console_attachment_from_cli(requested)?
} else {
Expand Down Expand Up @@ -713,6 +787,9 @@ mod tests {
use super::*;
use clap::Parser as _;
use test_with_tracing::test;
use virtio_resources::console::attachment::VirtioConsoleAttachmentMode;
use virtio_resources::console::attachment::VirtioConsoleBackendKind;
use virtio_resources::console::attachment::VirtioConsoleDisconnectPolicy;
use virtio_resources::console::attachment::VirtioConsoleReconnectPolicy;

fn socket_attachment(path: &Path) -> openvmm_helpers::snapshot::microvm::SnapshotAttachment {
Expand Down Expand Up @@ -1088,6 +1165,228 @@ mod tests {
assert_eq!(restored_snapshot, snapshot);
}

/// Asserts that `restored`, what a restore attached to a disconnected
/// boot console `snapshot`, is a listener at `endpoint` of the backend
/// `backend_kind`, which discards guest output while no client is
/// connected, and which differs from the saved attachment in its endpoint
/// alone.
fn assert_discarding_listener(
snapshot: &openvmm_helpers::snapshot::microvm::SnapshotAttachment,
restored: &ConsoleEndpoint,
endpoint: &Path,
backend_kind: VirtioConsoleBackendKind,
) {
let (config, resource, restored_attachment) = restored;
let SerialConfigCli::Pipe(path) = config else {
panic!("restore did not attach a listener");
};
assert!(path.ends_with(endpoint.file_name().unwrap()));
assert_eq!(resource.mode, VirtioConsoleAttachmentMode::Listen);
assert_eq!(resource.backend_kind, backend_kind);
assert_eq!(
resource.reconnect_policy,
VirtioConsoleReconnectPolicy::DiscardWhileDisconnected
);
assert!(!resource.required);
assert_eq!(resource.reconnect_timeout_ms, 0);
assert_eq!(
microvm_console_disconnect_policy(resource),
VirtioConsoleDisconnectPolicy::Discard
);
assert_eq!(
restored_attachment.reconnect_policy,
"discard-while-disconnected"
);
assert_ne!(restored_attachment.identity, snapshot.identity);
assert!(microvm_console_discarding_listener_matches(
snapshot,
restored_attachment
));
assert!(!microvm_console_listener_replacement_matches(
snapshot,
restored_attachment
));
}

#[cfg(unix)]
#[test]
fn disconnected_attachment_takes_a_restore_listener_that_keeps_discarding() {
let (_, _, snapshot) = microvm_console_attachment_from_cli(&SerialConfigCli::None).unwrap();
let directory = tempfile::tempdir().unwrap();
let endpoint = directory.path().join("clone.console");

let restored = microvm_console_attachment_from_snapshot(
&snapshot,
Some(&SerialConfigCli::Pipe(endpoint.clone())),
)
.unwrap();

assert_discarding_listener(
&snapshot,
&restored,
&endpoint,
VirtioConsoleBackendKind::UnixSocket,
);
assert_eq!(restored.2.identity_kind, "unix-socket");
// The listener's socket must be beside the snapshot, as a listener
// that a snapshot recorded must be.
validate_microvm_console_attachment_namespace(
&restored.2,
&directory.path().join("snapshot"),
)
.unwrap();
let elsewhere = tempfile::tempdir().unwrap();
assert!(
validate_microvm_console_attachment_namespace(
&restored.2,
&elsewhere.path().join("snapshot")
)
.is_err()
);
}

#[cfg(windows)]
#[test]
fn disconnected_attachment_takes_a_restore_pipe_listener_that_keeps_discarding() {
let (_, _, snapshot) = microvm_console_attachment_from_cli(&SerialConfigCli::None).unwrap();
let endpoint = PathBuf::from("//./pipe/openvmm-microvm-clone-console");

let restored = microvm_console_attachment_from_snapshot(
&snapshot,
Some(&SerialConfigCli::Pipe(endpoint.clone())),
)
.unwrap();

assert_discarding_listener(
&snapshot,
&restored,
&endpoint,
VirtioConsoleBackendKind::NamedPipe,
);
assert_eq!(restored.2.identity_kind, "named-pipe");
assert!(
microvm_console_attachment_from_snapshot(
&snapshot,
Some(&SerialConfigCli::Pipe(PathBuf::from("//./pipe/unrelated")))
)
.is_err()
);
}

#[test]
fn disconnected_attachment_refuses_every_other_restore_attachment() {
let (_, _, snapshot) = microvm_console_attachment_from_cli(&SerialConfigCli::None).unwrap();
#[cfg(unix)]
let directory = tempfile::tempdir().unwrap();
#[cfg(unix)]
let client = directory.path().join("client.console");
#[cfg(windows)]
let client = PathBuf::from("//./pipe/openvmm-microvm-client-console");
for (requested, what) in [
(
SerialConfigCli::Tcp("127.0.0.1:5555".parse().unwrap()),
"a TCP listener",
),
(
SerialConfigCli::ConnectTcp("127.0.0.1:5555".parse().unwrap()),
"a TCP client",
),
(
SerialConfigCli::ConnectPipe(client),
"a socket or pipe client",
),
(SerialConfigCli::Console, "the terminal"),
] {
assert!(
microvm_console_attachment_from_snapshot(&snapshot, Some(&requested)).is_err(),
"a disconnected boot console took {what} at a restore"
);
}
}

#[cfg(unix)]
#[test]
fn disconnected_control_console_refuses_a_restore_listener() {
use std::os::unix::fs::PermissionsExt as _;

let (_, _, snapshot) =
microvm_control_console_attachment_from_cli(&SerialConfigCli::None).unwrap();
let directory = tempfile::tempdir().unwrap();
std::fs::set_permissions(directory.path(), std::fs::Permissions::from_mode(0o700)).unwrap();
let requested = SerialConfigCli::Pipe(directory.path().join("control.sock"));

assert!(
microvm_console_attachment_from_snapshot_with_identity(
&snapshot,
Some(&requested),
MICROVM_CONTROL_CONSOLE_STABLE_ID,
MICROVM_CONTROL_CONSOLE_ATTACHMENT_KIND,
true,
)
.is_err()
);
}

#[test]
fn only_a_disconnected_boot_console_takes_a_discarding_listener() {
let disconnected = microvm_console_attachment_from_cli(&SerialConfigCli::None)
.unwrap()
.2;
let listener = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
reconnect_policy: "discard-while-disconnected".to_owned(),
identity_kind: "unix-socket".to_owned(),
identity: b"/snapshots/clone.console".to_vec(),
..disconnected.clone()
};
assert!(microvm_console_discarding_listener_matches(
&disconnected,
&listener
));

// A listener that retains output, or whose contract changes beyond
// its endpoint, is no discarding replacement.
let retaining = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
reconnect_policy: "recreate-listener".to_owned(),
..listener.clone()
};
let required = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
required: true,
..listener.clone()
};
let tcp = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
identity_kind: "tcp".to_owned(),
identity: b"127.0.0.1:5555".to_vec(),
..listener.clone()
};
for requested in [&retaining, &required, &tcp, &disconnected] {
assert!(!microvm_console_discarding_listener_matches(
&disconnected,
requested
));
}

// Neither does a saved listener, nor the control console.
let saved_listener = socket_attachment(Path::new("source.sock"));
assert!(!microvm_console_discarding_listener_matches(
&saved_listener,
&listener
));
let control = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
stable_id: MICROVM_CONTROL_CONSOLE_STABLE_ID.to_owned(),
kind: MICROVM_CONTROL_CONSOLE_ATTACHMENT_KIND.to_owned(),
..disconnected
};
let control_listener = openvmm_helpers::snapshot::microvm::SnapshotAttachment {
stable_id: MICROVM_CONTROL_CONSOLE_STABLE_ID.to_owned(),
kind: MICROVM_CONTROL_CONSOLE_ATTACHMENT_KIND.to_owned(),
..listener
};
assert!(!microvm_console_discarding_listener_matches(
&control,
&control_listener
));
}

#[test]
fn control_attachment_has_distinct_identity_and_rejects_tcp() {
let (_, resource, snapshot) =
Expand Down
Loading
Loading