ContextQMD
Back to Containerization

Single File Mounts

docs/single-file-mounts.md

0.32.02.6 KB
Original Source

Single File Mounts

In Containerization, what is analogous to bind mounts goes over virtiofs. virtiofs can only share directories, not individual files. To support mounting a single file from the host into a container, Containerization shares the file's parent directory via virtiofs and then bind mounts the specific file to its final destination inside the container.

How it works

  1. Detection: During mount preparation, each virtiofs mount source is stat'd. If it's a regular file (not a directory), it enters the single-file mount path. Symlinks are resolved to the real file first.

  2. Parent directory share: The file's parent directory is shared via virtiofs into the guest VM. If multiple single-file mounts reference files in the same parent directory, only one virtiofs share is created.

  3. Guest holding mount: After the VM starts, the parent directory share is mounted to a holding location in the guest.

  4. Bind mount: When the container starts, a bind mount is created from the holding location to the requested destination path inside the container.

Example

Mounting /Users/dev/config/app.toml to /etc/app.toml in the container:

Host:      /Users/dev/config/       (shared via virtiofs)
Guest VM:  /temporary/holding/spot/ (virtiofs mount of parent dir)
Container: /etc/app.toml            (bind mount of /temporary/holding/spot/app.toml)

Trade-offs

Sharing the parent directory means that sibling files in that directory are visible to the guest VM at the holding mount point under /run. The bind mount into the container only exposes the specific file requested, but the full parent directory contents are accessible from inside the VM itself. This is a deliberate trade-off for reliability. Prior attempts at supporting single file mounts using temporary directories with hardlinks were fragile across filesystem boundaries and with certain host filesystem configurations.

Alternatives to single file mounts

If exposing the parent directory to the guest VM is not acceptable for your use case, you can avoid single-file mounts entirely:

  • Mount the whole directory: Instead of mounting a single file, mount the directory that contains it. This is functionally equivalent (the directory is shared either way) but makes the behavior explicit and gives the container access to the full directory at the destination path.

  • Stage files into a dedicated directory: Copy the files you need into a dedicated directory on the host and mount that directory instead. This gives you full control over what is visible to the guest.