Elevator pitch
Expose the serial port and the virtio console over TCP, on a backend path they share. The two roles differ only in who starts the connection. In the listen role Cloud Hypervisor binds a port and accepts a client. In the connect role it dials a remote listener. In both roles the device reads from and writes to the connection.
Motivation
The serial console is limited to a local Unix socket in a listen role, so reaching it from the network needs a socat bridge, which the Windows debugging guide in the repository already does. Native TCP removes that bridge, matches QEMU so existing tooling works unchanged, and adds a connect role that does not exist today. Concrete drivers follow.
- QEMU interoperability. Tooling for QEMU serial over TCP works unchanged. This is the primary reason.
- Windows KDCOM kernel debugging. The serial port carries the WinDbg KDCOM protocol. docs/windows-kdcom-debugging.md bridges it to TCP with socat, and native TCP drops that step.
- Linux kgdb over serial and crash capture, which arrives before guest networking exists.
- Dialing home boot and panic output to a fixed remote collector with reconnect, which needs the connect role.
Prior art
QEMU chardev socket. server=on listens, server=off connects, wait gates boot, reconnect retries. Cloud Hypervisor already has the listen half for Unix sockets.
API/CLI
Yes. A new serial option, for example
--serial tcp=<host>:<port>,server=on|off,wait=on|off,reconnect=<secs>
The existing --serial socket=<path> is unchanged.
Testing
Yes. Parser unit tests next to the existing socket test, plus a functional test over a loopback port. Only a local port is needed, so CI gains nothing new.
Interactions
Independent of hotplug. Live migration rebinds or reconnects on the destination like the current socket backend, dropping any client. Landlock skips the filesystem rule for a network endpoint. Seccomp already allows the accept path in the serial manager thread.
Implementation
None yet.
Full feature description
The work has two parts, in order.
First, close the existing serial and console divergence. Serial supports socket mode and binds a listener in pre_create_console_devices, while the virtio console rejects the same mode and returns NoSocketOptionSupportForConsoleDevice, and its endpoint type has no socket variant. The step is to map where serial and console diverge for these backends, socket included, then unify the path they share so both drive their backend the same way. That gives console the socket support it lacks today.
Second, add the TCP backend on that shared path, with two roles.
- Listen role. Bind host and port and accept a client, reusing the buffering and single client reconnect the Unix socket backend already has.
- Connect role. Dial a remote listener rather than wait for one, with optional reconnect. This is new in Cloud Hypervisor.
In both roles the device reads from and writes to the same connection. Only the initiator differs. Because it rides on the unified path, socket and TCP behave the same on serial and console.
Plain remote access already works with socat, so native TCP is a convenience there. The connect role and QEMU option parity are the new parts.
Topics for later, out of scope here.
- Multiple concurrent readers beyond the single client model.
- QEMU telnet negotiation for plain telnet clients.
Elevator pitch
Expose the serial port and the virtio console over TCP, on a backend path they share. The two roles differ only in who starts the connection. In the listen role Cloud Hypervisor binds a port and accepts a client. In the connect role it dials a remote listener. In both roles the device reads from and writes to the connection.
Motivation
The serial console is limited to a local Unix socket in a listen role, so reaching it from the network needs a socat bridge, which the Windows debugging guide in the repository already does. Native TCP removes that bridge, matches QEMU so existing tooling works unchanged, and adds a connect role that does not exist today. Concrete drivers follow.
Prior art
QEMU chardev socket. server=on listens, server=off connects, wait gates boot, reconnect retries. Cloud Hypervisor already has the listen half for Unix sockets.
API/CLI
Yes. A new serial option, for example
The existing
--serial socket=<path>is unchanged.Testing
Yes. Parser unit tests next to the existing socket test, plus a functional test over a loopback port. Only a local port is needed, so CI gains nothing new.
Interactions
Independent of hotplug. Live migration rebinds or reconnects on the destination like the current socket backend, dropping any client. Landlock skips the filesystem rule for a network endpoint. Seccomp already allows the accept path in the serial manager thread.
Implementation
None yet.
Full feature description
The work has two parts, in order.
First, close the existing serial and console divergence. Serial supports socket mode and binds a listener in pre_create_console_devices, while the virtio console rejects the same mode and returns NoSocketOptionSupportForConsoleDevice, and its endpoint type has no socket variant. The step is to map where serial and console diverge for these backends, socket included, then unify the path they share so both drive their backend the same way. That gives console the socket support it lacks today.
Second, add the TCP backend on that shared path, with two roles.
In both roles the device reads from and writes to the same connection. Only the initiator differs. Because it rides on the unified path, socket and TCP behave the same on serial and console.
Plain remote access already works with socat, so native TCP is a convenience there. The connect role and QEMU option parity are the new parts.
Topics for later, out of scope here.