[Request]: Support direct guest SMB/CIFS and NFS network volume drivers (`--driver smb` / `--driver nfs`)
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
### 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
```bash
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
```bash
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
```bash
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](https://github.com/apple/containerization/pull/681).
- **NFS Support:** Requires `CONFIG_NFS_FS=y` enabled and compiled into the guest kernel binary.
---
## Related Pull Requests
- **Implementation PR:** apple/container#1428
- **Kernel Config PR:** apple/containerization#681
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
Contributor guide
Research direction
Start with the container volume create and container run entry points, then read Utility.swift and SandboxService.swift to trace volume resolution and guest mounts. Check kernel/config-arm64 and the referenced containerization#681 dependency for required CIFS/NFS support. Done means SMB and NFS volumes persist their options without local disk images and mount directly in the guest as requested.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- linux, swift
- Domain
- cli, infrastructure, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100