[Request]: Support direct guest SMB/CIFS and NFS network volume drivers (`--driver smb` / `--driver nfs`)

[tonycoco]

Feature or enhancement request details

Summary / Problem Statement

Currently, mounting remote network file shares (SMB/CIFS or NFS) into a container on macOS requires a multi-hop path through the host filesystem:

1. Mount the remote share on the macOS host (via Finder, mount_smbfs, or mount_nfs).
2. Expose the host mount point into the Linux guest VM via virtiofs.
3. Bind-mount the virtiofs share into the target container.

Pain Points of Host-Side Mounts (virtiofs Hop)

• Performance & Latency Overhead: Network share traffic double-hops through the macOS VFS layer and virtiofs synchronization mechanisms before reaching the Linux guest VM, significantly degrading I/O throughput and increasing file latency.
• Host Lifecycle Coupling: The container's availability is tied to interactive user host mounts. If the host network mount drops, sleeps, or disconnects, the container workload breaks.
• Permission & Ownership Translation: Mapping host macOS UID/GID identities through virtiofs to container user identities frequently introduces file locking, permission errors, and metadata inconsistencies.

---

Proposed Solution & Architecture

Introduce direct-to-guest volume drivers for SMB/CIFS (--driver smb) and NFS (--driver nfs) in container volume create.

Architecture

• Metadata-Only Volumes: When created with --driver smb or --driver nfs, no local block disk image is allocated. Instead, the remote share path, credentials, and mount options are persisted as volume metadata.
• Direct VM Guest Mount: At container start, Utility.swift resolves the volume into a Filesystem.smb or Filesystem.nfs specification. SandboxService.swift translates this into a .any Linux VM guest mount with type cifs or nfs respectively.
• Zero Host-Side Hops: The Linux guest VM kernel establishes the TCP connection directly to the remote NAS or file server, bypassing macOS host mounts and virtiofs entirely.

---

Real-World Use Cases

1. High-Performance Access to NAS & Large Datasets (AI/ML, Media Processing)

Workloads processing multi-terabyte datasets, media libraries, or analytics pipelines stored on network storage (Synology, TrueNAS, enterprise SAN/NAS) benefit from direct Linux kernel CIFS/NFS mounts. Eliminating the virtiofs hop maximizes sequential throughput and avoids host-side caching bottlenecks.

2. Automated CI/CD Pipelines & Unattended Builds

Build containers running unattended automated tests or compiling artifacts can connect directly to shared network artifact caches or repositories using service credentials, without requiring interactive macOS host mounts or user-level desktop sessions.

3. Multi-Container Shared Persistent State across Nodes

Containers requiring shared read/write access to common configuration files, shared logs, or database dump staging directories across one or multiple VM instances can utilize standard NFSv3/v4 or SMBv3 shares natively.

---

CLI Interface & Examples

Creating an SMB Volume

container volume create --driver smb \
  --opt share=//192.168.1.100/Media \
  --opt username=myuser \
  --opt password=secret \
  --opt vers=3.0 \
  --opt mfsymlinks= \
  myshare

Creating an NFS Volume

container volume create --driver nfs \
  --opt share=nas.local:/exports/data \
  --opt addr=nas.local \
  --opt vers=3 \
  --opt proto=tcp \
  --opt nolock= \
  myexport

Using the Volume in a Container

container run -v myshare:/media alpine ls -la /media

Note on Boolean Flags: Valueless flags (such as nolock or mfsymlinks) can be passed using an empty value syntax (--opt nolock=) and are serialized as bare mount flags in the guest mount data string.

---

Experimental Interface Consideration

As discussed in PR review, while the underlying volume model architecture continues to evolve, this --driver smb / --driver nfs CLI interface and option syntax can be marked and documented as Experimental. This provides users with immediate utility while retaining flexibility to iterate on the CLI shape and volume architecture in future releases.

---

Kernel Requirements & Upstream Dependencies

Direct guest CIFS/NFS mounts require support compiled into the guest Linux kernel (apple/containerization):

• SMB/CIFS Support: Requires enabling CONFIG_CIFS=y in kernel/config-arm64 (along with supporting flags such as CONFIG_CIFS_UPCALL=y, CONFIG_CIFS_XATTR=y, CONFIG_CIFS_POSIX=y, and CONFIG_CIFS_ALLOW_INSECURE_LEGACY=y). Without this, SMB mounts fail at runtime with errno 19 (ENODEV). Tracked in apple/containerization#681.
• NFS Support: Requires CONFIG_NFS_FS=y enabled and compiled into the guest kernel binary.

---

Related Pull Requests

• Implementation PR: Add SMB volume driver via direct guest CIFS mount #1428
• Kernel Config PR: Enable CIFS/SMB kernel support in arm64 config containerization#681

Code of Conduct

• I agree to follow this project's Code of Conduct