console: add Unix domain socket backend support

- Introduce `BackendType::Uds` for VM communication via Unix sockets
- Refactor address generation logic with `generate_vm_sock_addrs`
- Add CLI parameter `--vm-sock` to specify UDS path
- Update documentation and error handling

Signed-off-by: Hang SU <[email protected]>
Suggested-by: Xuewei Niu <[email protected]>

Author: Hang SU

vhost-device-console/CHANGELOG.md

@@ -4,6 +4,7 @@
 ### Added
 
 - [#811](https://github.com/rust-vmm/vhost-device/pull/811) Being able to specify max queue size
+- [#821](https://github.com/rust-vmm/vhost-device/pull/821) Add Unix domain socket backend support
 
 ### Changed
 

vhost-device-console/README.md

@@ -6,14 +6,17 @@ This program is a vhost-user backend that emulates a VirtIO Console device.
 The device's binary takes as parameters a socket path, a socket number which
 is the number of connections, commonly used across all vhost-devices to
 communicate with the vhost-user frontend devices, and the backend type
-"nested" or "network".
+"nested" or "network" or "uds".
 
 The "nested" backend allows input/output to the guest console through the
 current terminal.
 
 The "network" backend creates a local TCP port (specified on vhost-device-console
 arguments) and allows input/output to the guest console via that socket.
 
+The "uds" backend creates a unix domain socket (specified on vhost-device-console
+arguments) and allows input/output to the guest console via that socket.
+
 This program is tested with QEMU's `vhost-user-device-pci` device.
 Examples' section below.
 
@@ -39,14 +42,23 @@ vhost-device-console --socket-path=<SOCKET_PATH>
 
  The localhost's port to be used for each guest, this part will be increased with
  0,1,2..socket_count-1.
+ This option is only valid when backend type is "network".
 
--- option:: -b, --backend=nested|network
+-- option:: -b, --backend=nested|network|uds
 
   The backend type vhost-device-console to be used. The current implementation
-  supports two types of backends: "nested", "network" (described above).
+  supports 3 types of backends: "nested", "network", "uds".
   Note: The nested backend is selected by default and can be used only when
         socket_count equals 1.
 
+.. option:: --uds-path=uds-file-path
+
+  The unix domain socket to be used for each guest, this path will be suffixed with
+  0,1,2..socket_count-1. e.g.: `--uds-path=/tmp/vm.sock --socket-count=2`
+  leads to two connectable vhost-user sockets:
+  /tmp/vm.sock0, /tmp/vm.sock1
+  This option is only valid when backend type is "uds".
+
 .. option:: -q, --max-queue-size=SIZE
 
   The maximum size of virtqueues. It is optional, and the default value is
@@ -62,10 +74,10 @@ VIRTIO_CONSOLE_F_SIZE features.
 ## Features
 
 The current device gives access to multiple QEMU guest by providing a login prompt
-either by connecting to a localhost server port (network backend) or by creating an
-nested command prompt in the current terminal (nested backend). This prompt appears
-as soon as the guest is fully booted and gives the ability to user run command as a
-in regular terminal.
+either by connecting to a localhost server port (network backend) or a unix socket
+file (uds backend) or by creating an nested command prompt in the current terminal
+(nested backend). This prompt appears as soon as the guest is fully booted and
+gives the ability to user run command as a in regular terminal.
 
 ## Examples
 
@@ -83,10 +95,15 @@ For testing the device the required dependencies are:
 The daemon should be started first:
 ```shell
 host# vhost-device-console --socket-path=/tmp/console.sock --socket-count=1 \
-                           --tcp-port=12345 --backend=network
+                           --tcp-port=12345 --backend=network # for network backend
+```
+or
+```shell
+host# vhost-device-console --socket-path=/tmp/console.sock --socket-count=1 \
+                           --uds-path=/tmp/vm.sock --backend=uds # for uds backend
 ```
 >Note: In case the backend is "nested" there is no need to provide
-       "--socket-count" and "--tcp-port" parameters.
+       "--socket-count", "--tcp-port" and "--uds-path" parameters.
 
 The QEMU invocation needs to create a chardev socket the device can
 use to communicate as well as share the guests memory over a memfd.
@@ -119,9 +136,26 @@ host# qemu-system
     ...
 ```
 
+#### Test the device with UML
+Start the daemon as above section, then run the following cmdline for
+Kernel Mode Linux [`virtio console`](https://github.com/torvalds/linux/blob/848e076317446f9c663771ddec142d7c2eb4cb43/include/uapi/linux/virtio_ids.h#L34):
+```text
+host# linux root=/dev/ubda1 rw ubd0=$YOUR-PATH/kata-ubuntu-latest.image   \
+    <normal UML options>                                             \
+    virtio_uml.device=/tmp/console.sock0:3 console=tty0 console=hvc0 \
+    init=/bin/systemd                                                \
+    systemd.unit=kata-containers.target agent.debug_console
+```
+Test with [kata-ubuntu-latest.image](https://github.com/kata-containers/kata-containers/releases/),
+you can also use systemd to setup pty manually without kata-agent help.
+
 Eventually, the user can connect to the console by running:
 ```test
-host# stty -icanon -echo && nc localhost 12345 && stty echo
+host# stty -icanon -echo && nc localhost 12345 && stty echo # for network backend
+```
+or
+```test
+host# stty -icanon -echo && nc -U /tmp/vm.sock0 && stty echo # for uds backend
 ```
 
 >Note: `stty -icanon -echo` is used to force the tty layer to disable buffering and send / receive each character individually. After closing the connection please run `stty echo` so character are printed back on the local terminal console.

vhost-device-console/src/backend.rs

@@ -42,11 +42,14 @@ pub enum Error {
     ThreadPanic(String, Box<dyn Any + Send>),
     #[error("Error using multiple sockets with Nested backend")]
     WrongBackendSocket,
+    #[error("Invalid uds file")]
+    InvalidUdsFile,
 }
 
 #[derive(PartialEq, Eq, Debug)]
 pub struct VuConsoleConfig {
     pub socket_path: PathBuf,
+    pub uds_path: PathBuf,
     pub backend: BackendType,
     pub tcp_port: String,
     pub socket_count: u32,
@@ -86,6 +89,26 @@ impl VuConsoleConfig {
                     |i: u32| -> String { "127.0.0.1:".to_owned() + &(port_base + i).to_string() };
                 (0..self.socket_count).map(make_tcp_port).collect()
             }
+
+            BackendType::Uds => {
+                let uds_filename = self.uds_path.file_name().expect("uds has no filename.");
+                let uds_parent = self
+                    .uds_path
+                    .parent()
+                    .expect("uds has no parent directory.");
+
+                let make_uds_path = |i: u32| -> String {
+                    let mut filename = uds_filename.to_os_string();
+                    filename.push(std::ffi::OsStr::new(&i.to_string()));
+                    uds_parent
+                        .join(&filename)
+                        .to_str()
+                        .expect("Path contains invalid UTF-8 characters")
+                        .to_string()
+                };
+
+                (0..self.socket_count).map(make_uds_path).collect()
+            }
         }
     }
 }
@@ -192,6 +215,7 @@ mod tests {
     fn test_console_valid_configuration_nested() {
         let args = ConsoleArgs {
             socket_path: String::from("/tmp/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Nested,
             tcp_port: String::from("12345"),
             socket_count: 1,
@@ -205,6 +229,7 @@ mod tests {
     fn test_console_invalid_configuration_nested_1() {
         let args = ConsoleArgs {
             socket_path: String::from("/tmp/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Nested,
             tcp_port: String::from("12345"),
             socket_count: 0,
@@ -221,6 +246,7 @@ mod tests {
     fn test_console_invalid_configuration_nested_2() {
         let args = ConsoleArgs {
             socket_path: String::from("/tmp/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Nested,
             tcp_port: String::from("12345"),
             socket_count: 2,
@@ -237,6 +263,7 @@ mod tests {
     fn test_console_valid_configuration_network_1() {
         let args = ConsoleArgs {
             socket_path: String::from("/tmp/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Network,
             tcp_port: String::from("12345"),
             socket_count: 1,
@@ -250,6 +277,7 @@ mod tests {
     fn test_console_valid_configuration_network_2() {
         let args = ConsoleArgs {
             socket_path: String::from("/tmp/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Network,
             tcp_port: String::from("12345"),
             socket_count: 2,
@@ -280,6 +308,7 @@ mod tests {
     fn test_start_backend_server_success() {
         let args = ConsoleArgs {
             socket_path: String::from("/not_a_dir/vhost.sock").into(),
+            uds_path: None,
             backend: BackendType::Network,
             tcp_port: String::from("12345"),
             socket_count: 1,
@@ -293,6 +322,7 @@ mod tests {
     fn test_start_backend_success() {
         let config = VuConsoleConfig {
             socket_path: String::from("/not_a_dir/vhost.sock").into(),
+            uds_path: PathBuf::new(),
             backend: BackendType::Network,
             tcp_port: String::from("12346"),
             socket_count: 1,

vhost-device-console/src/console.rs

@@ -15,6 +15,7 @@ pub enum BackendType {
     #[default]
     Nested,
     Network,
+    Uds,
 }
 
 #[derive(Debug)]

vhost-device-console/src/main.rs

@@ -54,11 +54,16 @@ struct ConsoleArgs {
     #[clap(short = 's', long, value_name = "SOCKET")]
     socket_path: PathBuf,
 
+    /// Virtual machine communication endpoint.
+    /// Unix domain socket path (e.g., "/tmp/vm.sock").
+    #[clap(long, required(false), value_name = "VM_SOCKET")]
+    uds_path: Option<PathBuf>,
+
     /// Number of guests (sockets) to connect to.
     #[clap(short = 'c', long, default_value_t = 1)]
     socket_count: u32,
 
-    /// Console backend (Network, Nested) to be used.
+    /// Console backend (Network, Nested, Uds) to be used.
     #[clap(short = 'b', long, value_enum, default_value = "nested")]
     backend: BackendType,
 
@@ -87,14 +92,30 @@ impl TryFrom<ConsoleArgs> for VuConsoleConfig {
 
         let ConsoleArgs {
             socket_path,
+            uds_path,
             backend,
             tcp_port,
             socket_count,
             max_queue_size,
         } = args;
 
+        // check validation of uds_path under Uds mode.
+        if backend == BackendType::Uds {
+            let path = uds_path
+                .as_ref()
+                .filter(|p| !p.as_os_str().is_empty())
+                .ok_or(Error::InvalidUdsFile)?;
+
+            if let Some(parent_dir) = path.parent() {
+                if !parent_dir.exists() {
+                    return Err(Error::InvalidUdsFile);
+                }
+            }
+        }
+
         Ok(Self {
             socket_path,
+            uds_path: uds_path.unwrap_or_default(),
             backend,
             tcp_port,
             socket_count,