Shared Folders and USB
This chapter covers two ways to bridge host and guest: shared folders for files and USB passthrough for devices.
Shared Folders #
A shared folder makes a directory on your host visible inside the guest, so you can move files back and forth without networking. QuantaBox implements sharing with virtio-9p (the Plan 9 filesystem protocol over virtio).
Adding a Shared Folder
In Settings → Shared Folders, add a folder and set:
| Option | Meaning |
|---|---|
| Name | The mount name the guest uses (the mount tag). |
| Host Path | The directory on the host to share. |
| Read-Only | If set, the guest cannot modify the shared files. |
| Auto-Mount | If set, the guest mounts the share automatically at boot (via the guest agent / cloud-init). |
Mounting Inside the Guest
On a Linux guest, if auto-mount is not used, mount the share manually:
sudo mkdir -p /mnt/<name>
sudo mount -t 9p -o trans=virtio <name> /mnt/<name>Replace <name> with the share's mount name. To mount at every boot, add an equivalent entry to /etc/fstab.
Security Model
Shares use the mapped-xattr security model, which stores guest file ownership and permissions in host extended attributes rather than applying them to the host files directly. This keeps host and guest permission models cleanly separated. Use Read-Only for any folder the guest should never modify.
USB Passthrough #
USB passthrough connects a real USB device on your host directly to a guest, so the guest can use it as if it were physically attached. This is useful for USB drives, security keys, cameras, and peripherals.
Enabling USB
In Settings → USB, enable USB and choose a controller version:
| Controller | USB Version | Speed |
|---|---|---|
| xHCI | USB 3.0+ | 5 Gbps and above |
| EHCI | USB 2.0 | Up to 480 Mbps |
Use xHCI unless a guest specifically needs a USB 2.0 controller.
Passing a Device Through
QuantaBox can enumerate the host's USB devices (by vendor and product ID) so you can select one to attach to the guest. Once passed through, the device leaves the host's control and appears inside the guest.
- A device passed to a guest is unavailable to the host until released.
- Passing through a storage device while the host has it mounted can cause data corruption. Unmount it on the host first.
- Some devices need host privileges to access; on Linux this may require appropriate permissions/udev rules.
Choosing the Right Tool #
| To Move | Use |
|---|---|
| Files between host and guest | A shared folder |
| A whole USB drive or a hardware device | USB passthrough |
| Files to/from a networked guest | SSH/SCP (see Console and Remote Access) |
Next Steps #
Continue to Backup, Export and Import to move and protect whole VMs.