feat(fs): expose overlayfs API for macOS (#8)

* feat(fs): expose overlayfs API for macOS

Add public API for using OverlayFS functionality in libkrun on macOS by exposing
the implementation through a new FsImplConfig enum. This allows clients to
configure either passthrough or overlayfs filesystem modes.

Key changes:
- Add FsImplConfig enum to select between Passthrough and Overlayfs modes
- Add FsImplShare enum to handle different sharing configurations
- Refactor Fs implementation to delegate operations to selected backend
- Update Config struct to include layers configuration
- Clean up and reorganize filesystem server code
- Add comprehensive test coverage for overlayfs operations

The implementation maintains the existing passthrough functionality while adding
the ability to configure overlayfs mode with multiple read-only layers and a
writable top layer.

* feat(overlayfs): add special handling for init.krun lookup

Add special case handling in the lookup method to return a predefined entry
when looking up "init.krun" file. This allows exposing the init binary with
specific permissions (755) and size based on the included binary data.

* fix(overlayfs): improve init.krun inode handling and documentation

- Set init.krun inode ID dynamically using next_inode counter
- Reorder init.krun inode check before handle data lookup in read()
- Add documentation about default values for config options
- Clarify proc_sfd_rawfd usage in sandboxing scenarios
- Update comments to specifically reference init.krun

* refactor(fs): remove debug println statements from overlayfs

Author: appcypher

include/libkrun.h

@@ -59,9 +59,34 @@ int32_t krun_set_vm_config(uint32_t ctx_id, uint8_t num_vcpus, uint32_t ram_mib)
  *
  * Returns:
  *  Zero on success or a negative error number on failure.
+ *  Documented errors:
+ *       -EEXIST when a root device is already set
+ *
+ * Notes:
+ *  This function is mutually exclusive with krun_set_overlayfs_root.
  */
 int32_t krun_set_root(uint32_t ctx_id, const char *root_path);
 
+/**
+ * Sets up an OverlayFS to be used as root for the microVM. Not available in libkrun-SEV.
+ *
+ * Arguments:
+ *  "ctx_id"      - the configuration context ID.
+ *  "root_layers" - an array of string pointers to filesystem paths representing
+ *                  the layers to be used for the OverlayFS. The array must be
+ *                  NULL-terminated and contain at least one layer.
+ *
+ * Returns:
+ *  Zero on success or a negative error number on failure.
+ *  Documented errors:
+ *       -EINVAL when no layers are provided
+ *       -EEXIST when a root device is already set
+ *
+ * Notes:
+ *  This function is mutually exclusive with krun_set_root.
+ */
+int32_t krun_set_overlayfs_root(uint32_t ctx_id, const char *const root_layers[]);
+
 /**
  * DEPRECATED. Use krun_add_disk instead.
  *

src/devices/src/virtio/fs/device.rs

@@ -15,6 +15,8 @@ use vm_memory::{ByteValued, GuestMemoryMmap};
 use super::super::{
     ActivateResult, DeviceState, FsError, Queue as VirtQueue, VirtioDevice, VirtioShmRegion,
 };
+use super::kinds::{FsImplConfig, FsImplShare};
+use super::macos::overlayfs;
 use super::passthrough;
 use super::worker::FsWorker;
 use super::ExportTable;
@@ -51,7 +53,7 @@ pub struct Fs {
     device_state: DeviceState,
     config: VirtioFsConfig,
     shm_region: Option<VirtioShmRegion>,
-    passthrough_cfg: passthrough::Config,
+    fs_config: FsImplConfig,
     worker_thread: Option<JoinHandle<()>>,
     worker_stopfd: EventFd,
     #[cfg(target_os = "macos")]
@@ -61,7 +63,7 @@ pub struct Fs {
 impl Fs {
     pub(crate) fn with_queues(
         fs_id: String,
-        shared_dir: String,
+        fs_share: FsImplShare,
         queues: Vec<VirtQueue>,
     ) -> super::Result<Fs> {
         let mut queue_events = Vec::new();
@@ -76,10 +78,15 @@ impl Fs {
         let mut config = VirtioFsConfig::default();
         config.tag[..tag.len()].copy_from_slice(tag.as_slice());
         config.num_request_queues = 1;
-
-        let fs_cfg = passthrough::Config {
-            root_dir: shared_dir,
-            ..Default::default()
+        let fs_config = match fs_share {
+            FsImplShare::Passthrough(root_dir) => FsImplConfig::Passthrough(passthrough::Config {
+                root_dir,
+                ..Default::default()
+            }),
+            FsImplShare::Overlayfs(layers) => FsImplConfig::Overlayfs(overlayfs::Config {
+                layers,
+                ..Default::default()
+            }),
         };
 
         Ok(Fs {
@@ -94,20 +101,20 @@ impl Fs {
             device_state: DeviceState::Inactive,
             config,
             shm_region: None,
-            passthrough_cfg: fs_cfg,
+            fs_config,
             worker_thread: None,
             worker_stopfd: EventFd::new(EFD_NONBLOCK).map_err(FsError::EventFd)?,
             #[cfg(target_os = "macos")]
             map_sender: None,
         })
     }
 
-    pub fn new(fs_id: String, shared_dir: String) -> super::Result<Fs> {
+    pub fn new(fs_id: String, fs_share: FsImplShare) -> super::Result<Fs> {
         let queues: Vec<VirtQueue> = defs::QUEUE_SIZES
             .iter()
             .map(|&max_size| VirtQueue::new(max_size))
             .collect();
-        Self::with_queues(fs_id, shared_dir, queues)
+        Self::with_queues(fs_id, fs_share, queues)
     }
 
     pub fn id(&self) -> &str {
@@ -124,11 +131,20 @@ impl Fs {
 
     pub fn set_export_table(&mut self, export_table: ExportTable) -> u64 {
         static FS_UNIQUE_ID: AtomicU64 = AtomicU64::new(0);
+        let fsid = FS_UNIQUE_ID.fetch_add(1, Ordering::Relaxed);
 
-        self.passthrough_cfg.export_fsid = FS_UNIQUE_ID.fetch_add(1, Ordering::Relaxed);
-        self.passthrough_cfg.export_table = Some(export_table);
+        match &mut self.fs_config {
+            FsImplConfig::Passthrough(cfg) => {
+                cfg.export_fsid = fsid;
+                cfg.export_table = Some(export_table);
+            }
+            FsImplConfig::Overlayfs(cfg) => {
+                cfg.export_fsid = fsid;
+                cfg.export_table = Some(export_table);
+            }
+        }
 
-        self.passthrough_cfg.export_fsid
+        fsid
     }
 
     #[cfg(target_os = "macos")]
@@ -215,6 +231,7 @@ impl VirtioDevice for Fs {
             .iter()
             .map(|e| e.try_clone().unwrap())
             .collect();
+
         let worker = FsWorker::new(
             self.queues.clone(),
             queue_evts,
@@ -224,13 +241,13 @@ impl VirtioDevice for Fs {
             self.irq_line,
             mem.clone(),
             self.shm_region.clone(),
-            self.passthrough_cfg.clone(),
+            self.fs_config.clone(),
             self.worker_stopfd.try_clone().unwrap(),
             #[cfg(target_os = "macos")]
             self.map_sender.clone(),
         );
-        self.worker_thread = Some(worker.run());
 
+        self.worker_thread = Some(worker.run());
         self.device_state = DeviceState::Activated(mem);
         Ok(())
     }