allow redirecting guest serial output to a file

Add a new field, `serial_out_path`, to the logger configuration
(available both via API and CLI) which can be set to the path of a file
into which the output of the guest's serial console should be dumped.

Have the file behave identically to our log file (e.g. it must already
exist, Firecracker does not create it).

If we redirect serial output to a log file, disable serial input via
stdin.

Signed-off-by: Patrick Roy <[email protected]>

Author: roypat

CHANGELOG.md

@@ -35,6 +35,10 @@ and this project adheres to
   requests to `/mmds/config` to enforce MMDS to always respond plain text
   contents in the IMDS format regardless of the `Accept` header in requests.
   Users need to regenerate snapshots.
+- [#5350](https://github.com/firecracker-microvm/firecracker/pull/5350): Added a
+  `--serial-out-path` CLI option and a `serial_out_path` field to `PUT /logger`,
+  which allows specifying a file into which Firecracker should redirect guest
+  serial console output instead of stdout.
 
 ### Changed
 

src/firecracker/src/api_server/request/logger.rs

@@ -36,6 +36,7 @@ mod tests {
 
         let expected_config = LoggerConfig {
             log_path: Some(PathBuf::from("log")),
+            serial_out_path: None,
             level: Some(LevelFilter::Warn),
             show_level: Some(false),
             show_log_origin: Some(false),
@@ -55,6 +56,7 @@ mod tests {
 
         let expected_config = LoggerConfig {
             log_path: Some(PathBuf::from("log")),
+            serial_out_path: None,
             level: Some(LevelFilter::Debug),
             show_level: Some(false),
             show_log_origin: Some(false),

src/firecracker/src/main.rs

@@ -208,6 +208,11 @@ fn main_exec() -> Result<(), MainError> {
                     .takes_value(true)
                     .help("Path to a fifo or a file used for configuring the logger on startup."),
             )
+            .arg(
+                Argument::new("serial-out-path")
+                    .takes_value(true)
+                    .help("Path to a fifo or a file used for serial output."),
+            )
             .arg(
                 Argument::new("level")
                     .takes_value(true)
@@ -300,6 +305,7 @@ fn main_exec() -> Result<(), MainError> {
         .set(String::from(instance_id))
         .unwrap();
     let log_path = arguments.single_value("log-path").map(PathBuf::from);
+    let serial_out_path = arguments.single_value("serial-out-path").map(PathBuf::from);
     let level = arguments
         .single_value("level")
         .map(|s| vmm::logger::LevelFilter::from_str(s))
@@ -311,6 +317,7 @@ fn main_exec() -> Result<(), MainError> {
     LOGGER
         .update(LoggerConfig {
             log_path,
+            serial_out_path,
             level,
             show_level,
             show_log_origin,

src/firecracker/swagger/firecracker.yaml

@@ -1022,6 +1022,11 @@ definitions:
         type: string
         description: The module path to filter log messages by.
         example: api_server::request
+      serial_out_path:
+        type: string
+        description:
+          Path to the named pipe of file for guest serial console output. If not specified,
+          serial console output will be printed to stdout.
 
   MachineConfiguration:
     type: object

src/vmm/src/device_manager/mod.rs

@@ -7,6 +7,7 @@
 
 use std::convert::Infallible;
 use std::fmt::Debug;
+use std::os::unix::prelude::OpenOptionsExt;
 use std::sync::{Arc, Mutex};
 
 use acpi::ACPIDeviceManager;
@@ -32,6 +33,7 @@ use crate::devices::legacy::{IER_RDA_BIT, IER_RDA_OFFSET, SerialDevice};
 use crate::devices::pseudo::BootTimer;
 use crate::devices::virtio::device::VirtioDevice;
 use crate::devices::virtio::transport::mmio::{IrqTrigger, MmioTransport};
+use crate::logger::LOGGER;
 use crate::resources::VmResources;
 use crate::snapshot::Persist;
 use crate::vstate::memory::GuestMemoryMmap;
@@ -126,12 +128,25 @@ impl DeviceManager {
     fn setup_serial_device(
         event_manager: &mut EventManager,
     ) -> Result<Arc<Mutex<SerialDevice>>, std::io::Error> {
-        Self::set_stdout_nonblocking();
-
-        let serial = Arc::new(Mutex::new(SerialDevice::new(
-            Some(std::io::stdin()),
-            SerialOut::Stdout(std::io::stdout()),
-        )?));
+        let (serial_in, serial_out) =
+            match LOGGER.0.lock().expect("logger poisoned").serial_out_path {
+                Some(ref path) => (
+                    None,
+                    std::fs::OpenOptions::new()
+                        .custom_flags(libc::O_NONBLOCK)
+                        .read(true)
+                        .write(true)
+                        .open(path)
+                        .map(SerialOut::File)?,
+                ),
+                None => {
+                    Self::set_stdout_nonblocking();
+
+                    (Some(std::io::stdin()), SerialOut::Stdout(std::io::stdout()))
+                }
+            };
+
+        let serial = Arc::new(Mutex::new(SerialDevice::new(serial_in, serial_out)?));
         event_manager.add_subscriber(serial.clone());
         Ok(serial)
     }

src/vmm/src/devices/legacy/serial.rs

@@ -7,6 +7,7 @@
 
 //! Implements a wrapper over an UART serial device.
 use std::fmt::Debug;
+use std::fs::File;
 use std::io::{self, Read, Stdin, Write};
 use std::os::unix::io::{AsRawFd, RawFd};
 use std::sync::{Arc, Barrier};
@@ -129,18 +130,21 @@ impl SerialEvents for SerialEventsWrapper {
 pub enum SerialOut {
     Sink,
     Stdout(std::io::Stdout),
+    File(File),
 }
 impl std::io::Write for SerialOut {
     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
         match self {
             Self::Sink => Ok(buf.len()),
             Self::Stdout(stdout) => stdout.write(buf),
+            Self::File(file) => file.write(buf),
         }
     }
     fn flush(&mut self) -> std::io::Result<()> {
         match self {
             Self::Sink => Ok(()),
             Self::Stdout(stdout) => stdout.flush(),
+            Self::File(file) => file.flush(),
         }
     }
 }

src/vmm/src/logger/logging.rs

@@ -28,6 +28,7 @@ pub static INSTANCE_ID: OnceLock<String> = OnceLock::new();
 /// Default values matching the swagger specification (`src/firecracker/swagger/firecracker.yaml`).
 pub static LOGGER: Logger = Logger(Mutex::new(LoggerConfiguration {
     target: None,
+    serial_out_path: None,
     filter: LogFilter { module: None },
     format: LogFormat {
         show_level: false,
@@ -72,6 +73,10 @@ impl Logger {
             guard.target = Some(file);
         };
 
+        if let Some(serial_out_path) = config.serial_out_path {
+            guard.serial_out_path = Some(serial_out_path);
+        }
+
         if let Some(show_level) = config.show_level {
             guard.format.show_level = show_level;
         }
@@ -104,6 +109,7 @@ pub struct LogFormat {
 #[derive(Debug)]
 pub struct LoggerConfiguration {
     pub target: Option<std::fs::File>,
+    pub serial_out_path: Option<PathBuf>,
     pub filter: LogFilter,
     pub format: LogFormat,
 }
@@ -186,6 +192,8 @@ impl Log for Logger {
 pub struct LoggerConfig {
     /// Named pipe or file used as output for logs.
     pub log_path: Option<PathBuf>,
+    /// Named pipe of file used as output for guest serial console.
+    pub serial_out_path: Option<PathBuf>,
     /// The level of the Logger.
     pub level: Option<LevelFilter>,
     /// Whether to show the log level in the log.
@@ -366,6 +374,7 @@ mod tests {
         // Create logger.
         let logger = Logger(Mutex::new(LoggerConfiguration {
             target: Some(target),
+            serial_out_path: None,
             filter: LogFilter {
                 module: Some(String::from("module")),
             },

src/vmm/src/rpc_interface.rs

@@ -1185,6 +1185,7 @@ mod tests {
         )));
         check_unsupported(runtime_request(VmmAction::ConfigureLogger(LoggerConfig {
             log_path: Some(PathBuf::new()),
+            serial_out_path: None,
             level: Some(crate::logger::LevelFilter::Debug),
             show_level: Some(false),
             show_log_origin: Some(false),