CubeSandbox 中的 virtiofsd用 Rust 实现的高性能 virtio-fs vhost-user 文件共享守护进程【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxvirtiofsd 是一个以 Rust 编写的 virtio-fs 为主线结合 hypervisor/virtiofsd 仓库内的源码、配置与配套文档系统讲解 virtiofsd 的构建方式、权限模型、全部命令行参数、QEMU 集成方法、非特权用户运行、扩展属性映射、SELinux 支持与迁移特性。读完本文你将能够在 CubeSandbox 的 Cloud Hypervisor 虚拟化环境中独立编译、配置并调优 virtiofsd为 AI 沙箱等场景提供安全可靠的宿主机-客户机文件共享通道。virtiofsd 是什么架构与仓库定位virtio-fs 是一种专为本地虚拟机间共享文件系统而设计的协议它利用宿主机内核的 FUSE 实现配合 vhost-user 协议在用户态完成请求转发从而获得接近原生文件系统的 I/O 性能。virtiofsd 正是这一协议的服务端backend实现作为 vhost-user 设备守护进程运行它监听一个 vhost-user socket等待 hypervisor如 QEMU 或 cloud-hypervisor作为 frontend 接入通过 virtio queue 接收客户机的 FUSE 请求open/read/write/getattr/listxattr 等由 passthrough 模式将请求直接落到宿主机真实文件系统上。在本仓库中virtiofsd 位于 hypervisor/virtiofsd是 CubeSandbox 所集成虚拟化栈hypervisor的组成部分。其 Cargo.toml 显示当前版本为 1.11.0采用Apache-2.0 AND BSD-3-Clause双许可证。仓库还提供了配套的 vhost-user 能力声明文件 50-virtiofsd.json其内容为{ description: virtiofsd vhost-user-fs, type: fs, binary: /usr/libexec/virtiofsd, features: [ migrate-precopy ] }从源码结构看virtiofsd 的核心代码分布在 src/main.rs参数解析与主流程、src/sandbox.rs沙箱隔离、src/seccomp.rs系统调用过滤、src/passthrough直通文件系统实现含 inode 存储、文件句柄、扩展属性映射等模块以及 src/server.rsFUSE 请求处理等文件中。从源码构建 virtiofsd系统依赖virtiofsd 依赖两个 C 库libcap-ng用于 Linux capabilities 管理和libseccomp用于 seccomp 系统调用过滤。既可以从源码自行编译这两个库也可以通过发行版软件包安装Fedora/CentOS/RHELdnf install libcap-ng-devel libseccomp-develDebian/Ubuntuapt install libcap-ng-dev libseccomp-dev编译virtiofsd 使用 Rust 与 cargo 构建。安装 Rust 工具链后执行cargo build --release从 Cargo.toml 可以看到其主要依赖包括vhost-user-backend、vhost、vm-memory、virtio-queue、clap命令行解析、capng、libseccomp-sys、syslog等其中rate_limiter直接引用同仓库下的 hypervisor/rate_limiter crate。[profile.release]启用了lto true以优化最终二进制。此外Cargo.toml 提供了一个xenfeature注意启用它会禁用 QEMU/KVM 支持。CI 构建产物每次代码合入后CI 会发布一个 virtiofsd 的debug二进制方便没有 Rust 工具链的用户直接下载测试。该二进制仅针对 x86_64 Linux 系统构建适合快速试用而非性能敏感的生产环境。权限模型与安全加固virtiofsd 必须以 root 用户运行或以用户命名空间user namespace内的 fake root 身份运行详见下文“非特权用户运行”。这是因为守护进程需要能够以任意 uid/gid 创建和访问文件。为此它在启动过程中尽可能降低权限其安全措施从 src/main.rs 的drop_capabilities()与 src/seccomp.rs 的实现可见一斑seccomp 系统调用限制通过seccomp(2)将可调用的系统调用限制在白名单内。白名单覆盖了文件系统直通所需的核心调用如openat、read、write、statx、setxattr、name_to_handle_at、open_by_handle_at等默认对越权调用执行kill动作见--seccomp参数。Linux capabilities 收缩virtiofsd 仅保留以下 capabilitiesCAP_CHOWN、CAP_DAC_OVERRIDE、CAP_FOWNER、CAP_FSETID、CAP_SETGID、CAP_SETUID、CAP_MKNOD、CAP_SETFCAP若使用--inode-file-handles还会额外保留CAP_DAC_READ_SEARCH。默认 capabilities 列表在drop_capabilities()中硬编码见 src/main.rs并可通过--modcaps调整。沙箱隔离--sandbox参数提供 namespace / chroot / none 三种隔离机制详见下文参数说明防止通过符号链接等文件系统对象逃逸出共享目录。命令行参数完全参考virtiofsd 的完整用法格式为virtiofsd [FLAGS] [OPTIONS] --fd fd|--socket-path socket-path --shared-dir shared-dir所有参数均在 src/main.rs 中通过 clap derive 定义并保留了旧版-o兼容选项parse_compat支持-o cacheauto、-o source/path、-o xattr、-o sandboxchroot等历史写法但会打印弃用警告。Flags开关类参数-h, --help打印帮助信息。-V, --version打印版本信息。--syslog输出日志到 syslog。默认输出到 stderr。日志初始化逻辑见 src/main.rs启用 syslog 时 seccomp 白名单中会额外放行sendto见 src/seccomp.rs。--print-capabilities打印 vhost-user.json 后端程序能力声明后退出内容与 50-virtiofsd.json 一致typefsfeature 为migrate-precopy。--allow-direct-io接受客户机应用传递下来的O_DIRECT标志。--announce-submounts向客户机通告哪些目录是挂载点。当共享目录下挂载了多个文件系统时各文件系统的 inode ID 只在自身范围内唯一直通给客户机可能产生重复 ID该选项会对每个遇到的子挂载报告不同的设备号来解决此问题。此外启用该选项后客户机会对每个需要同步的子挂载发送一次SYNCFS请求virtiofsd 会对每个子挂载分别调用syncfs()若不启用客户机只会对根挂载发送SYNCFS可能造成数据丢失或损坏。从 src/main.rs 可见该选项默认启用可通过--no-announce-submounts关闭。--no-killpriv-v2禁用KILLPRIV V2支持。当共享目录位于 NFS 文件系统上时必须禁用。默认禁用。--killpriv-v2启用KILLPRIV V2支持。默认禁用需要显式指定。见 src/main.rs 中killpriv_v2的取值逻辑。--no-readdirplus禁用READDIRPLUS操作。注意 src/main.rs 中readdirplus还与缓存策略联动当--cachenever时READDIRPLUS会被强制关闭。--writeback启用 writeback 缓存写回缓存。--xattr启用扩展属性xattr支持。--posix-acl启用 POSIX ACL 支持隐含启用--xattr。--security-label启用安全标签SELinux支持。--preserve-noatime始终保留O_NOATIME。默认情况下 virtiofsd 会隐式清除O_NOATIME以避免在无权访问所有导出文件时产生权限错误典型场景是非特权用户配合--sandbox none此时没有CAP_FOWNER。使用该选项可覆盖此行为、保留客户机指定的O_NOATIME标志。相关逻辑见 src/main.rs 的has_noatime_capability()以及 passthrough 配置中的clean_noatime字段。Options带值参数--shared-dir shared-dir共享目录路径。启动时若路径不存在会直接报错退出见 src/main.rs。该参数在 clap 中被标记为required_unless_present(compat_options)即使用-o source兼容写法时可不填。--tag tagvirtio 设备通告的 tag。设置后会启用VHOST_USER_PROTOCOL_F_CONFIG通告但 hypervisor 的 vhost-user frontend 可能不会协商该特性或忽略该值QEMU 8.1 及之后版本会忽略 CONFIG 特性QEMU 7.1 至 8.0 会在尝试记录“不支持该特性”的警告时崩溃。tag 不能为空且长度不能超过 36 字节UTF-8 编码见 src/main.rs 的parse_tag()与MAX_TAG_LEN常量。--socket-group socket-groupvhost-user socket 所属的组名。指定后 umask 会去掉 other 的访问位见 src/main.rs并会对 socket 执行chown到该组src/main.rs。不能与--fd、--print-capabilities同时使用。--socket-path socket-pathvhost-user socket 路径。旧参数--socket已弃用但保留兼容。注意创建 socket 前会先写入socket.pid文件并持有其锁防止多实例竞争同一 pid 文件src/main.rs。--fd fd监听 socket 的文件描述符常用于由 hypervisor/运行时提前创建 socket 的场景。与--socket-path、--socket互斥。--log-level log-level日志级别error, warn, info, debug, trace, off。默认info。若环境变量RUST_LOG已设置则优先使用RUST_LOGsrc/main.rs。--thread-pool-size thread-pool-size线程池最大线程数0表示禁用池串行处理请求。默认0。启用线程池时每个工作线程会执行unshare(CLONE_FS)以隔离文件系统上下文src/main.rs。注意部分老版本 Docker/Moby 会在没有CAP_SYS_ADMIN时通过 seccomp 拒绝该调用此时创建线程池会失败。--rlimit-nofile rlimit-nofile设置最大文件描述符数。若软限制已大于 1M 或显式传--rlimit-nofile0则不改变最大 fd 数。默认min(1000000, /proc/sys/fs/nr_open)。--modcapsmodcaps修改 capabilities 列表例如--modcapssys_admin:-chown。强烈建议始终使用号否则--modcaps -mknod会被解析成两个独立选项而非预期的--modcaps-mknod。解析逻辑在parse_modcaps()src/main.rs追加、-移除并对能力名做合法性校验另外在--inode-file-handles非 never 时不允许移除DAC_READ_SEARCH。--sandbox sandbox沙箱隔离机制取值为namespace、chroot、none默认namespacenamespace进程切换到新的文件系统命名空间并调用pivot_root(2)将共享目录树设为其根同时创建新的 mount、pid 和 net 命名空间。实现细节见 src/sandbox.rs 的enter_namespace()它通过两次 fork、双向管道同步、newuidmap/newgidmap等步骤完成隔离。chroot调用chroot(2)将共享目录树设为根。适用于容器环境——此时容器运行时已建立好命名空间virtiofsd 自身无权再创建命名空间。none不隔离守护进程不推荐。namespace 与 chroot 两种模式都能防止通过符号链接等文件系统对象逃逸出共享目录。root 用户下enter_namespace()使用CLONE_NEWPID | CLONE_NEWNS | CLONE_NEWNET非特权用户额外叠加CLONE_NEWUSER依赖 user namespace 完成隔离src/sandbox.rs。--seccomp seccompseccomp 遇到未允许系统调用时的动作none不启用、kill杀死进程、log记录日志、trap触发陷阱。默认kill。对应 src/seccomp.rs 中的SeccompAction枚举与 src/main.rs 的parse_seccomp()。--cache cache文件系统缓存策略auto、always、metadata、never默认auto。各策略在 src/passthrough/mod.rs 中有详尽注释auto默认策略客户端按 close-to-open 一致性自行决定缓存时机always客户端总是缓存文件数据仅在文件系统独占目录访问权时使用never客户端永不缓存文件数据所有 I/O 直通服务端当文件内容可能在 FUSE 客户端不知情时变化时必须选此策略metadata普通文件近似 never但允许客户机缓存目录页缓存、dentry 与属性缓存兼顾一致性与目录遍历性能。在 src/main.rs 中各策略还会映射为 entry/attr 超时时间never为 0 秒auto为 1 秒metadata与always为 86400 秒1 天。--allow-mmap对--cache{metadata, never}的共享目录允许其中的文件被mmap映射。--inode-file-handlesinode-file-handles何时使用文件句柄file handle代替O_PATH文件描述符引用 inode取值为never、prefer、mandatory默认nevernever永不使用文件句柄始终用O_PATH文件描述符prefer尝试生成文件句柄在底层文件系统不支持文件句柄或没有CAP_DAC_READ_SEARCH时回退到O_PATH描述符。适合共享目录下存在多种、部分不支持文件句柄的文件系统的场景fallback是prefer的弃用别名见 src/main.rsmandatory始终使用文件句柄若底层文件系统不支持或缺少CAP_DAC_READ_SEARCH则直接失败。使用文件句柄能减少 virtiofsd 保持打开的 fd 数量既节省资源也能规避某些场景下“只为客户机已打开的文件保持 fd”的需求——例如规避 NFS “silly rename” 造成的不良交互。注意mandatory模式会强制追加CAP_DAC_READ_SEARCHsrc/main.rs。文件句柄的生成/打开实现在 src/passthrough/file_handle.rs。--xattrmap xattrmap添加自定义规则用于在宿主机与客户机之间翻译扩展属性名称例如:map::user.virtiofs.:。完整语法与示例见下文“扩展属性映射”官方详述见 扩展属性映射文档。--uid-map:namespace_uid:host_uid:count:以非 root 身份运行时将宿主机的一段 UID 范围映射到命名空间。使用该选项前需要在subuid(5)中配置好从属用户 ID 范围对于非平凡映射virtiofsd 会调用newuidmap(1)。若不提供该选项virtiofsd 会对当前 uid 建立 1:1 映射。参数含义namespace_uid用户命名空间内 UID 范围的起始值host_uid用户命名空间外 UID 范围的起始值count两侧范围的长度。示例假设调用 UID 为 1000/etc/subuid内容为1000:100000:65536即 UID 1000 拥有从 100000 开始的 65536 个 subuid闭区间 [100000, 165535]则通过--uid-map:0:100000:65536:可将该范围映射为 virtiofsd 用户命名空间即客户机视角内的 UID [0, 65535]。也可以将自身 UID 简单映射为命名空间中的单个 UID--uid-map:0:1000:1:会把宿主 UID 1000 映射为命名空间及客户机中的 root。在 src/main.rs 中该参数支持多次指定以映射多段范围映射的实际写入逻辑含直接写/proc/[pid]/uid_map与调用newuidmap两条路径见 src/sandbox.rs。--gid-map:namespace_gid:host_gid:count:与--uid-map对称用于 GID。使用前需在subgid(5)中配置从属组 ID 范围非平凡映射调用newgidmap(1)未指定时对当前 gid 建立 1:1 映射。示例与--uid-map完全对应--gid-map:0:100000:65536:将宿主机 GID [100000, 165535] 映射为命名空间内 GID [0, 65535]--gid-map:0:1000:1:将宿主 GID 1000 映射为命名空间 root。--migration-modefind-paths定义迁移方式即如何把内部状态表示并传递给目标实例。注意使用 QEMU 时virtio-fs 迁移需要 QEMU 8.2 或更新版本。virtiofsd 内部持有客户机索引或打开的所有 inode 的引用迁移时需将这些引用转移给目标端find-paths穷举遍历共享目录为源实例持有的所有 inode 找到相对共享目录的路径把路径传给目标端由目标端打开这些路径。该方式不需要特殊权限也不要求源/目标使用同一共享目录但代价是 I/O 开销大对共享目录做 DFS且迁移期间第三方修改共享目录元数据重命名、删除、移除权限可能造成数据丢失/损坏。该参数在迁移目标端被忽略。--migration-on-errorabort|guest-error控制迁移期间出错时的响应。迁移过程中某些客户机索引或打开过的 inode 可能不可迁移或源端无法构造让目标端找到/打开该 inode 的指令或目标端无法执行这些指令。无论何种情况目标端都会被告知这些 inode并按该参数取值决策abort目标端一旦发现任何此类错误就向 vhost-user frontend如 QEMU返回硬错误从而中止迁移执行继续留在源 VMguest-error允许迁移完成但所有受影响的 inode 被标记为无效客户机访问这些 inode 只会收到错误。注意该参数仅用于目标端实例源端会忽略其值。--migration-verify-handles确保迁移目标端打开的是与源端完全相同的 inode。仅当源与目标使用同一共享目录、同一文件系统时才有效。迁移时源端告知目标端所有客户机索引或打开过的 inode 并让其重新打开启用该选项后源端为每个 inode 生成文件句柄并发送给目标端目标端为自己打开的 inode 重新生成相同文件句柄并比对是否相等以证明是同一 inode。文件句柄是每文件系统唯一的 inode 标识除 inode ID 外还包含 generation ID 以防 inode ID 复用。该选项可防止迁移期间第三方重命名或替换 inode 造成的数据丢失/损坏当共享目录除了 virtiofsd 外还有其他进程具有写权限时应当始终启用。网络文件系统场景下不要求源与目标运行在同一台主机。该参数在目标端被忽略。--migration-confirm-paths在切换到目标端之前的瞬间二次确认 inode 身份可在第三方对共享目录拥有写权限时提升迁移健壮性。当以“相对共享目录的路径”表示迁移 inode 时切换阶段会逐路径复核其仍与对应 inode 匹配若不匹配则参考/proc/self/fd中相应符号链接尝试修正。注意该选项要求在切换阶段源与目标 VM 均暂停时逐个访问客户机索引或打开过的 inode可能使该阶段持续不确定的时间。该参数在目标端被忽略。实战示例将 /mnt 共享给 QEMU 客户机将/mnt通过 vhost-user UNIX 域套接字/tmp/vfsd.sock导出host# virtiofsd --socket-path/tmp/vfsd.sock --shared-dir /mnt \ --announce-submounts --inode-file-handlesmandatory host# qemu-system \ -blockdev file,node-namehdd,filenameyour image \ -device virtio-blk,drivehdd \ -chardev socket,idchar0,path/tmp/vfsd.sock \ -device vhost-user-fs-pci,queue-size1024,chardevchar0,tagmyfs \ -object memory-backend-memfd,idmem,size4G,shareon \ -numa node,memdevmem \ -accel kvm -m 4G guest# mount -t virtiofs myfs /mnt要点客户机挂载时使用的myfs必须与-device vhost-user-fs-pci中的tagmyfs一致memory-backend-memfd必须带shareon且其size必须与-m定义的内存大小一致virtio-fs 依赖共享内存完成零拷贝数据传递。virtiofsd 内部默认仅使用 1 个请求队列加 1 个高优先级队列REQUEST_QUEUES 1NUM_QUEUES 2见 src/main.rsQEMU 侧queue-size1024用于设定 virtqueue 容量。用 virtiofs 作为 Cloud Hypervisor 客户机 rootfsCubeSandbox 集成的 Cloud Hypervisor 也支持将 virtiofs 作为客户机根文件系统无根块设备场景完整操作指南见 hypervisor/docs/virtiofs-root.md。其核心命令为sudo virtiofsd --socket-path$PWD/virtiofs-rootfs.sock --shared-dir$PWD/rootfs --cachenever sudo cloud-hypervisor \ --cpus boot1,max1 \ --kernel vmlinux \ --fs tag/dev/root,socket$PWD/virtiofs-rootfs.sock \ --memory size2G,sharedon \ --cmdline consolehvc0 rootfstypevirtiofs root/dev/root ro debug \ --api-socket $PWD/ch.sock \ --rng \ --net ...该场景有两个容易踩坑的要点hypervisor/docs/virtiofs-root.md 中特别提示tag必须使用/dev/root才能正常工作--memory必须为 shared 内存。此外由于根文件系统内容是只读的ro这里配合--cachenever使用。以非特权用户运行 virtiofsd非 root 运行 virtiofsd 时必须依赖用户命名空间见user_namespaces(7)才能切换客户机内的任意 uid/gid。在未写入uid_map与gid_map即未建立 UID/GID 映射的用户命名空间中virtiofsd 会直接失败。以下假设调用者的 UID 与 GID 均为 1000且/etc/subuid与/etc/subgid内容都为1000:100000:65536方式一使用podman-unshare(1)。它配置的用户命名空间使调用者的 UID 与主 GID即 1000分别呈现为 UID 0 与 GID 0并通过newuidmap(1)/newgidmap(1)将/etc/subuid、/etc/subgid中匹配该用户/组的范围原样映射进去host$ podman unshare -- virtiofsd --socket-path/tmp/vfsd.sock --shared-dir /mnt \ --announce-submounts --sandbox chroot 方式二使用lxc-usernsexec(1)把调用者留在映射之外让用户命名空间内的 root 映射到用户/组 100000host$ lxc-usernsexec -m b:0:100000:65536 -- virtiofsd --socket-path/tmp/vfsd.sock \ --shared-dir /mnt --announce-submounts --sandbox chroot 要获得与podman-unshare(1)相同的行为则需要两条映射规则host$ lxc-usernsexec -m b:0:1000:1 -m b:1:100000:65536 -- virtiofsd --socket-path/tmp/vfsd.sock \ --shared-dir /mnt --announce-submounts --sandbox chroot 也可以把上述命令中的--sandbox chroot换成--sandbox none。从 src/sandbox.rs 的enter()逻辑可见chroot模式仅允许 root 使用非特权用户会收到SandboxModeInvalidUID错误而--uid-map/--gid-map仅允许非特权用户在namespace沙箱下使用。非特权模式限制客户机内无法在共享目录中创建块设备或字符设备节点virtiofsd 无法使用文件句柄--inode-file-handles需要CAP_DAC_READ_SEARCH因此需要维持大量打开的文件描述符在 NFS 上不使用文件句柄还可能导致文件删除后残留隐藏文件NFS silly rename 问题virtiofsd 无法提高RLIMIT_NOFILE。扩展属性xattr映射默认情况下客户机使用的 xattr 名称会原样直通到宿主机文件系统。这在两类场景下会有问题一是该 xattr 名称被宿主机侧机制占用如 SELinux 在客户机/宿主机间的混淆二是 virtiofsd 运行在受限容器中、无法访问某些属性。映射语法通过--xattrmapmapping建立映射mapping由一系列规则组成。查找映射时第一条匹配的规则生效规则集中必须覆盖所有 xattr 名称典型做法是最后一条规则做成 catch-all 兜底。每条规则由若干字段组成字段分隔符是该规则中第一个非空白字符同一规则内必须复用该分隔符规则前后可自由加空白。使用:作分隔符时规则形式为:type:scope:key:prepend:scope取值client在客户机的 setxattr/getxattr/removexattr 请求中用key匹配属性名server在宿主机返回的 listxattr 结果中用prepend匹配属性名all单条规则同时触发 server 与 client 两侧的匹配。type取值prefix用于前缀的加/减——客户机侧匹配key并加上prepend前缀再传给服务端服务端侧剥掉prepend前缀后传给客户机ok命中即终止规则集并放行匹配的 xattr 原样通过。用于显式终止规则链或让某些 xattr 跳过后续规则bad客户机使用匹配key的名称时以EPERM拒绝宿主机侧匹配prepend的属性被隐藏。用法类似ok作为显式终止符或对特定模式的特殊处理unsupported客户机使用匹配key的名称时以ENOTSUP拒绝宿主机侧匹配prepend的属性被隐藏。用法同bad。key以字符串前缀形式测试客户机侧属性名可为空——空的client规则匹配所有客户机名称。prepend以字符串前缀形式测试宿主机侧属性名并作为新前缀使用可为空——空的server规则匹配所有宿主机名称。常用规则示例详见 扩展属性映射文档映射规则说明:prefix:client:trusted.:user.virtiofs.:匹配客户机调用中的trusted.*属性加前缀后传给宿主机:prefix:server::user.virtiofs.:从所有宿主机应答中剥掉user.virtiofs.前缀:prefix:all:trusted.:user.virtiofs.:上面两条合并为一条规则:ok:client:user.::放行user.属性的 get/set xattr:ok:server::security.:在宿主机 listxattr 结果中放行security.属性:ok:all:::终止规则搜索其余属性双向放行:bad:server::security.:隐藏宿主机 listxattr 结果中的security.属性map 简写map类型提供常见场景的短语法:map:key:prepend:它展开为若干条规则为匹配的keykey 为空时匹配所有属性加上prepend前缀。最多只能有一条map规则且必须是规则集最后一条。注意当security.capability这个 xattr 被重映射时守护进程必须额外做大量去除工作这些工作宿主机内核通常会自行完成。安全考量操作系统通常用约定前缀划分 xattr 命名空间各分区访问控制不同。Linux 上常见分区system.*访问控制取决于属性与文件系统security.*仅具有CAP_SYS_ADMIN的进程可访问trusted.*仅具有CAP_SYS_ADMIN的进程可访问user.*任何由文件权限/属主授权的进程可访问。FreeBSD 等系统则有不同的前缀与访问控制规则。重映射时必须确保不会让客户机用户绕过客户机侧访问控制。例如若把客户机的trusted.*重映射为宿主机user.virtiofs.trusted.*Linux 客户机内的非特权用户有权写user.*下的 xattr于是可借写user.virtiofs.trusted.*绕过trusted.*的访问限制。由于不同客户机 OS 的分区规则不同最稳妥的方案是一次性把所有 xattr 重映射到固定前缀如下面示例 1而选择性映射时必须显式阻断对重映射目标的直接访问如下面示例 2。映射示例为所有属性加user.virtiofs.前缀--xattrmap:prefix:all::user.virtiofs.::bad:all:::第一条规则加/剥user.virtiofs.前缀第二条规则隐藏宿主机设置的任何未加前缀属性。等价于map简写--xattrmap:map::user.virtiofs.:只前缀trusted.属性、放行其余--xattrmap/prefix/all/trusted./user.virtiofs./ /bad/server//trusted./ /bad/client/user.virtiofs.// /ok/all///每条规则实际写在一行此处分行仅为清晰展示。四条规则依次为前缀trusted.并剥user.virtiofs.隐藏宿主机上未加前缀的trusted.阻止客户机直接写user.virtiofs.路径防止绕过前面重映射目标的访问控制最后放行剩余全部属性。等价于map简写--xattrmap/map/trusted./user.virtiofs./隐藏security.属性、放行其他--xattrmap/bad/all/security./security./ /ok/all///第一条all规则同时覆盖客户机请求与宿主机返回的列表阻止客户机看到或设置宿主机上任何security.属性。SELinux 支持启用 SELinux 支持只需加--security-label。但该选项会尝试把客户机的安全上下文保存到宿主机 xattrsecurity.selinux若宿主 SELinux 策略不允许 virtiofsd 执行该操作则会失败。因此官方推荐把客户机的security.selinuxxattr 重映射为宿主机上的trusted.virtiofs.security.selinux在命令行加入--xattrmap:map:security.selinux:trusted.virtiofs.:这样客户机与宿主机在同一文件上的 SELinux xattr 相互隔离、互不干扰宿主机与客户机可以各自实施独立的 SELinux 策略。由于在宿主机上设置 trusted xattr 需要CAP_SYS_ADMIN需要给守护进程追加该 capability--modcapssys_admintrustedxattr 不随命名空间隔离因此 virtiofsd 必须在init_user_ns中持有CAP_SYS_ADMIN——即不应使用用户命名空间。需要权衡的是授予CAP_SYS_ADMIN提升了系统风险一旦 virtiofsd 被攻破攻击者可能对宿主机系统造成较大损害请务必在启用前评估这一取舍。FAQ常见集成问题如何只读共享一个客户机内不可修改的目录导出一个只读挂载点即可。例如导出share的只读视图mkdir ro-share mount -o bind,ro share ro-share virtiofsd --shared-dir ro-share ...如何用同一个 virtiofsd 共享多个目录目前 virtiofsd 仅支持共享单个目录但可以通过子挂载submounts实现。例如同时导出share0、share1mkdir -p share/{sh0,sh1} mount -o bind share0 share/sh0 mount -o bind share1 share/sh1 virtiofsd --announce-submounts --shared-dir share ...注意必须使用--announce-submounts防止数据丢失/损坏。如何给已有 QEMU 命令行添加 virtiofs 设备若命令行尚未包含-object memory-backend-memfd,idmem且没有-numa node,memdevmem或-machine选项中的memory-backendmem属性先补上若已配置其他内存后端需将其改为memory-backend-memfd-object memory-backend-memfd必须带shareon且size必须与-m定义的内存大小一致每个 virtiofs 设备挂载添加一对参数-chardev socket,id${MATCHING_ID},path${VIRTIOFSD_SOCKET_PATH}和-device vhost-user-fs-pci,queue-size1024,chardev${MATCHING_ID},tag${VIRTIOFS_TAG}替换其中的 shell 风格变量即可。从代码看 virtiofsd 的运行主流程为了更深入地理解上述参数如何生效可沿 src/main.rs 的main()追踪启动链路解析命令行含-o兼容格式并校验共享目录存在初始化日志stderr 或 syslog与信号处理SIGHUP/SIGTERM直接退出创建/复用 vhost-user listener写入 pid 文件必要时设置 socket 组所有权根据--sandbox进入沙箱namespace/chroot/none在沙箱内完成挂载隔离并取得隔离后的/proc/self/fd与/proc/self/mountinfo句柄组装passthrough::Config缓存超时、xattr、announce-submounts、文件句柄模式、writeback、killpriv-v2、迁移参数等以 root 身份收缩 capabilities创建PassthroughFs与VhostUserFsBackend启动VhostUserDaemon等待 frontend 接入并服务请求。其中 vhost-user 后端按 50-virtiofsd.json 声明为typefs、feature 为migrate-precopy对应--print-capabilities的输出与迁移相关参数的实现。值得留意的是src/main.rs 中VhostUserFsBackend完整实现了 vhost-user 的迁移协议set_device_state_fd/check_device_state以及prepare_serialization预迁移线程这与--migration-mode、--migration-on-error、--migration-verify-handles、--migration-confirm-paths四个迁移选项共同构成 virtiofsd 的 live-migration 能力。小结virtiofsd 以 Rust 实现了 virtio-fs vhost-user 后端把宿主机目录以近乎原生的性能安全地共享给虚拟机客户机。其安全模型由 seccomp 白名单、最小 capabilities 集与 namespace/chroot 沙箱三层构成--sandbox、--inode-file-handles、--cache、--xattrmap等参数分别从隔离性、fd 资源占用、缓存一致性、xattr 安全映射等维度提供了细粒度调优能力配合 QEMU/Cloud Hypervisor 的 vhost-user-fs 设备与memory-backend-memfd共享内存即可在数分钟内搭建出一条可用的宿主机-客户机文件共享通道并进一步借助迁移参数实现安全的 live migration。相关源码与文档可在 hypervisor/virtiofsd 目录下继续深读命令行解析见 src/main.rs沙箱实现见 src/sandbox.rsseccomp 白名单见 src/seccomp.rs直通文件系统见 src/passthroughxattr 映射的完整规范见 doc/xattr-mapping.md。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CubeSandbox 中的 virtiofsd：用 Rust 实现的高性能 virtio-fs vhost-user 文件共享守护进程
CubeSandbox 中的 virtiofsd用 Rust 实现的高性能 virtio-fs vhost-user 文件共享守护进程【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxvirtiofsd 是一个以 Rust 编写的 virtio-fs 为主线结合 hypervisor/virtiofsd 仓库内的源码、配置与配套文档系统讲解 virtiofsd 的构建方式、权限模型、全部命令行参数、QEMU 集成方法、非特权用户运行、扩展属性映射、SELinux 支持与迁移特性。读完本文你将能够在 CubeSandbox 的 Cloud Hypervisor 虚拟化环境中独立编译、配置并调优 virtiofsd为 AI 沙箱等场景提供安全可靠的宿主机-客户机文件共享通道。virtiofsd 是什么架构与仓库定位virtio-fs 是一种专为本地虚拟机间共享文件系统而设计的协议它利用宿主机内核的 FUSE 实现配合 vhost-user 协议在用户态完成请求转发从而获得接近原生文件系统的 I/O 性能。virtiofsd 正是这一协议的服务端backend实现作为 vhost-user 设备守护进程运行它监听一个 vhost-user socket等待 hypervisor如 QEMU 或 cloud-hypervisor作为 frontend 接入通过 virtio queue 接收客户机的 FUSE 请求open/read/write/getattr/listxattr 等由 passthrough 模式将请求直接落到宿主机真实文件系统上。在本仓库中virtiofsd 位于 hypervisor/virtiofsd是 CubeSandbox 所集成虚拟化栈hypervisor的组成部分。其 Cargo.toml 显示当前版本为 1.11.0采用Apache-2.0 AND BSD-3-Clause双许可证。仓库还提供了配套的 vhost-user 能力声明文件 50-virtiofsd.json其内容为{ description: virtiofsd vhost-user-fs, type: fs, binary: /usr/libexec/virtiofsd, features: [ migrate-precopy ] }从源码结构看virtiofsd 的核心代码分布在 src/main.rs参数解析与主流程、src/sandbox.rs沙箱隔离、src/seccomp.rs系统调用过滤、src/passthrough直通文件系统实现含 inode 存储、文件句柄、扩展属性映射等模块以及 src/server.rsFUSE 请求处理等文件中。从源码构建 virtiofsd系统依赖virtiofsd 依赖两个 C 库libcap-ng用于 Linux capabilities 管理和libseccomp用于 seccomp 系统调用过滤。既可以从源码自行编译这两个库也可以通过发行版软件包安装Fedora/CentOS/RHELdnf install libcap-ng-devel libseccomp-develDebian/Ubuntuapt install libcap-ng-dev libseccomp-dev编译virtiofsd 使用 Rust 与 cargo 构建。安装 Rust 工具链后执行cargo build --release从 Cargo.toml 可以看到其主要依赖包括vhost-user-backend、vhost、vm-memory、virtio-queue、clap命令行解析、capng、libseccomp-sys、syslog等其中rate_limiter直接引用同仓库下的 hypervisor/rate_limiter crate。[profile.release]启用了lto true以优化最终二进制。此外Cargo.toml 提供了一个xenfeature注意启用它会禁用 QEMU/KVM 支持。CI 构建产物每次代码合入后CI 会发布一个 virtiofsd 的debug二进制方便没有 Rust 工具链的用户直接下载测试。该二进制仅针对 x86_64 Linux 系统构建适合快速试用而非性能敏感的生产环境。权限模型与安全加固virtiofsd 必须以 root 用户运行或以用户命名空间user namespace内的 fake root 身份运行详见下文“非特权用户运行”。这是因为守护进程需要能够以任意 uid/gid 创建和访问文件。为此它在启动过程中尽可能降低权限其安全措施从 src/main.rs 的drop_capabilities()与 src/seccomp.rs 的实现可见一斑seccomp 系统调用限制通过seccomp(2)将可调用的系统调用限制在白名单内。白名单覆盖了文件系统直通所需的核心调用如openat、read、write、statx、setxattr、name_to_handle_at、open_by_handle_at等默认对越权调用执行kill动作见--seccomp参数。Linux capabilities 收缩virtiofsd 仅保留以下 capabilitiesCAP_CHOWN、CAP_DAC_OVERRIDE、CAP_FOWNER、CAP_FSETID、CAP_SETGID、CAP_SETUID、CAP_MKNOD、CAP_SETFCAP若使用--inode-file-handles还会额外保留CAP_DAC_READ_SEARCH。默认 capabilities 列表在drop_capabilities()中硬编码见 src/main.rs并可通过--modcaps调整。沙箱隔离--sandbox参数提供 namespace / chroot / none 三种隔离机制详见下文参数说明防止通过符号链接等文件系统对象逃逸出共享目录。命令行参数完全参考virtiofsd 的完整用法格式为virtiofsd [FLAGS] [OPTIONS] --fd fd|--socket-path socket-path --shared-dir shared-dir所有参数均在 src/main.rs 中通过 clap derive 定义并保留了旧版-o兼容选项parse_compat支持-o cacheauto、-o source/path、-o xattr、-o sandboxchroot等历史写法但会打印弃用警告。Flags开关类参数-h, --help打印帮助信息。-V, --version打印版本信息。--syslog输出日志到 syslog。默认输出到 stderr。日志初始化逻辑见 src/main.rs启用 syslog 时 seccomp 白名单中会额外放行sendto见 src/seccomp.rs。--print-capabilities打印 vhost-user.json 后端程序能力声明后退出内容与 50-virtiofsd.json 一致typefsfeature 为migrate-precopy。--allow-direct-io接受客户机应用传递下来的O_DIRECT标志。--announce-submounts向客户机通告哪些目录是挂载点。当共享目录下挂载了多个文件系统时各文件系统的 inode ID 只在自身范围内唯一直通给客户机可能产生重复 ID该选项会对每个遇到的子挂载报告不同的设备号来解决此问题。此外启用该选项后客户机会对每个需要同步的子挂载发送一次SYNCFS请求virtiofsd 会对每个子挂载分别调用syncfs()若不启用客户机只会对根挂载发送SYNCFS可能造成数据丢失或损坏。从 src/main.rs 可见该选项默认启用可通过--no-announce-submounts关闭。--no-killpriv-v2禁用KILLPRIV V2支持。当共享目录位于 NFS 文件系统上时必须禁用。默认禁用。--killpriv-v2启用KILLPRIV V2支持。默认禁用需要显式指定。见 src/main.rs 中killpriv_v2的取值逻辑。--no-readdirplus禁用READDIRPLUS操作。注意 src/main.rs 中readdirplus还与缓存策略联动当--cachenever时READDIRPLUS会被强制关闭。--writeback启用 writeback 缓存写回缓存。--xattr启用扩展属性xattr支持。--posix-acl启用 POSIX ACL 支持隐含启用--xattr。--security-label启用安全标签SELinux支持。--preserve-noatime始终保留O_NOATIME。默认情况下 virtiofsd 会隐式清除O_NOATIME以避免在无权访问所有导出文件时产生权限错误典型场景是非特权用户配合--sandbox none此时没有CAP_FOWNER。使用该选项可覆盖此行为、保留客户机指定的O_NOATIME标志。相关逻辑见 src/main.rs 的has_noatime_capability()以及 passthrough 配置中的clean_noatime字段。Options带值参数--shared-dir shared-dir共享目录路径。启动时若路径不存在会直接报错退出见 src/main.rs。该参数在 clap 中被标记为required_unless_present(compat_options)即使用-o source兼容写法时可不填。--tag tagvirtio 设备通告的 tag。设置后会启用VHOST_USER_PROTOCOL_F_CONFIG通告但 hypervisor 的 vhost-user frontend 可能不会协商该特性或忽略该值QEMU 8.1 及之后版本会忽略 CONFIG 特性QEMU 7.1 至 8.0 会在尝试记录“不支持该特性”的警告时崩溃。tag 不能为空且长度不能超过 36 字节UTF-8 编码见 src/main.rs 的parse_tag()与MAX_TAG_LEN常量。--socket-group socket-groupvhost-user socket 所属的组名。指定后 umask 会去掉 other 的访问位见 src/main.rs并会对 socket 执行chown到该组src/main.rs。不能与--fd、--print-capabilities同时使用。--socket-path socket-pathvhost-user socket 路径。旧参数--socket已弃用但保留兼容。注意创建 socket 前会先写入socket.pid文件并持有其锁防止多实例竞争同一 pid 文件src/main.rs。--fd fd监听 socket 的文件描述符常用于由 hypervisor/运行时提前创建 socket 的场景。与--socket-path、--socket互斥。--log-level log-level日志级别error, warn, info, debug, trace, off。默认info。若环境变量RUST_LOG已设置则优先使用RUST_LOGsrc/main.rs。--thread-pool-size thread-pool-size线程池最大线程数0表示禁用池串行处理请求。默认0。启用线程池时每个工作线程会执行unshare(CLONE_FS)以隔离文件系统上下文src/main.rs。注意部分老版本 Docker/Moby 会在没有CAP_SYS_ADMIN时通过 seccomp 拒绝该调用此时创建线程池会失败。--rlimit-nofile rlimit-nofile设置最大文件描述符数。若软限制已大于 1M 或显式传--rlimit-nofile0则不改变最大 fd 数。默认min(1000000, /proc/sys/fs/nr_open)。--modcapsmodcaps修改 capabilities 列表例如--modcapssys_admin:-chown。强烈建议始终使用号否则--modcaps -mknod会被解析成两个独立选项而非预期的--modcaps-mknod。解析逻辑在parse_modcaps()src/main.rs追加、-移除并对能力名做合法性校验另外在--inode-file-handles非 never 时不允许移除DAC_READ_SEARCH。--sandbox sandbox沙箱隔离机制取值为namespace、chroot、none默认namespacenamespace进程切换到新的文件系统命名空间并调用pivot_root(2)将共享目录树设为其根同时创建新的 mount、pid 和 net 命名空间。实现细节见 src/sandbox.rs 的enter_namespace()它通过两次 fork、双向管道同步、newuidmap/newgidmap等步骤完成隔离。chroot调用chroot(2)将共享目录树设为根。适用于容器环境——此时容器运行时已建立好命名空间virtiofsd 自身无权再创建命名空间。none不隔离守护进程不推荐。namespace 与 chroot 两种模式都能防止通过符号链接等文件系统对象逃逸出共享目录。root 用户下enter_namespace()使用CLONE_NEWPID | CLONE_NEWNS | CLONE_NEWNET非特权用户额外叠加CLONE_NEWUSER依赖 user namespace 完成隔离src/sandbox.rs。--seccomp seccompseccomp 遇到未允许系统调用时的动作none不启用、kill杀死进程、log记录日志、trap触发陷阱。默认kill。对应 src/seccomp.rs 中的SeccompAction枚举与 src/main.rs 的parse_seccomp()。--cache cache文件系统缓存策略auto、always、metadata、never默认auto。各策略在 src/passthrough/mod.rs 中有详尽注释auto默认策略客户端按 close-to-open 一致性自行决定缓存时机always客户端总是缓存文件数据仅在文件系统独占目录访问权时使用never客户端永不缓存文件数据所有 I/O 直通服务端当文件内容可能在 FUSE 客户端不知情时变化时必须选此策略metadata普通文件近似 never但允许客户机缓存目录页缓存、dentry 与属性缓存兼顾一致性与目录遍历性能。在 src/main.rs 中各策略还会映射为 entry/attr 超时时间never为 0 秒auto为 1 秒metadata与always为 86400 秒1 天。--allow-mmap对--cache{metadata, never}的共享目录允许其中的文件被mmap映射。--inode-file-handlesinode-file-handles何时使用文件句柄file handle代替O_PATH文件描述符引用 inode取值为never、prefer、mandatory默认nevernever永不使用文件句柄始终用O_PATH文件描述符prefer尝试生成文件句柄在底层文件系统不支持文件句柄或没有CAP_DAC_READ_SEARCH时回退到O_PATH描述符。适合共享目录下存在多种、部分不支持文件句柄的文件系统的场景fallback是prefer的弃用别名见 src/main.rsmandatory始终使用文件句柄若底层文件系统不支持或缺少CAP_DAC_READ_SEARCH则直接失败。使用文件句柄能减少 virtiofsd 保持打开的 fd 数量既节省资源也能规避某些场景下“只为客户机已打开的文件保持 fd”的需求——例如规避 NFS “silly rename” 造成的不良交互。注意mandatory模式会强制追加CAP_DAC_READ_SEARCHsrc/main.rs。文件句柄的生成/打开实现在 src/passthrough/file_handle.rs。--xattrmap xattrmap添加自定义规则用于在宿主机与客户机之间翻译扩展属性名称例如:map::user.virtiofs.:。完整语法与示例见下文“扩展属性映射”官方详述见 扩展属性映射文档。--uid-map:namespace_uid:host_uid:count:以非 root 身份运行时将宿主机的一段 UID 范围映射到命名空间。使用该选项前需要在subuid(5)中配置好从属用户 ID 范围对于非平凡映射virtiofsd 会调用newuidmap(1)。若不提供该选项virtiofsd 会对当前 uid 建立 1:1 映射。参数含义namespace_uid用户命名空间内 UID 范围的起始值host_uid用户命名空间外 UID 范围的起始值count两侧范围的长度。示例假设调用 UID 为 1000/etc/subuid内容为1000:100000:65536即 UID 1000 拥有从 100000 开始的 65536 个 subuid闭区间 [100000, 165535]则通过--uid-map:0:100000:65536:可将该范围映射为 virtiofsd 用户命名空间即客户机视角内的 UID [0, 65535]。也可以将自身 UID 简单映射为命名空间中的单个 UID--uid-map:0:1000:1:会把宿主 UID 1000 映射为命名空间及客户机中的 root。在 src/main.rs 中该参数支持多次指定以映射多段范围映射的实际写入逻辑含直接写/proc/[pid]/uid_map与调用newuidmap两条路径见 src/sandbox.rs。--gid-map:namespace_gid:host_gid:count:与--uid-map对称用于 GID。使用前需在subgid(5)中配置从属组 ID 范围非平凡映射调用newgidmap(1)未指定时对当前 gid 建立 1:1 映射。示例与--uid-map完全对应--gid-map:0:100000:65536:将宿主机 GID [100000, 165535] 映射为命名空间内 GID [0, 65535]--gid-map:0:1000:1:将宿主 GID 1000 映射为命名空间 root。--migration-modefind-paths定义迁移方式即如何把内部状态表示并传递给目标实例。注意使用 QEMU 时virtio-fs 迁移需要 QEMU 8.2 或更新版本。virtiofsd 内部持有客户机索引或打开的所有 inode 的引用迁移时需将这些引用转移给目标端find-paths穷举遍历共享目录为源实例持有的所有 inode 找到相对共享目录的路径把路径传给目标端由目标端打开这些路径。该方式不需要特殊权限也不要求源/目标使用同一共享目录但代价是 I/O 开销大对共享目录做 DFS且迁移期间第三方修改共享目录元数据重命名、删除、移除权限可能造成数据丢失/损坏。该参数在迁移目标端被忽略。--migration-on-errorabort|guest-error控制迁移期间出错时的响应。迁移过程中某些客户机索引或打开过的 inode 可能不可迁移或源端无法构造让目标端找到/打开该 inode 的指令或目标端无法执行这些指令。无论何种情况目标端都会被告知这些 inode并按该参数取值决策abort目标端一旦发现任何此类错误就向 vhost-user frontend如 QEMU返回硬错误从而中止迁移执行继续留在源 VMguest-error允许迁移完成但所有受影响的 inode 被标记为无效客户机访问这些 inode 只会收到错误。注意该参数仅用于目标端实例源端会忽略其值。--migration-verify-handles确保迁移目标端打开的是与源端完全相同的 inode。仅当源与目标使用同一共享目录、同一文件系统时才有效。迁移时源端告知目标端所有客户机索引或打开过的 inode 并让其重新打开启用该选项后源端为每个 inode 生成文件句柄并发送给目标端目标端为自己打开的 inode 重新生成相同文件句柄并比对是否相等以证明是同一 inode。文件句柄是每文件系统唯一的 inode 标识除 inode ID 外还包含 generation ID 以防 inode ID 复用。该选项可防止迁移期间第三方重命名或替换 inode 造成的数据丢失/损坏当共享目录除了 virtiofsd 外还有其他进程具有写权限时应当始终启用。网络文件系统场景下不要求源与目标运行在同一台主机。该参数在目标端被忽略。--migration-confirm-paths在切换到目标端之前的瞬间二次确认 inode 身份可在第三方对共享目录拥有写权限时提升迁移健壮性。当以“相对共享目录的路径”表示迁移 inode 时切换阶段会逐路径复核其仍与对应 inode 匹配若不匹配则参考/proc/self/fd中相应符号链接尝试修正。注意该选项要求在切换阶段源与目标 VM 均暂停时逐个访问客户机索引或打开过的 inode可能使该阶段持续不确定的时间。该参数在目标端被忽略。实战示例将 /mnt 共享给 QEMU 客户机将/mnt通过 vhost-user UNIX 域套接字/tmp/vfsd.sock导出host# virtiofsd --socket-path/tmp/vfsd.sock --shared-dir /mnt \ --announce-submounts --inode-file-handlesmandatory host# qemu-system \ -blockdev file,node-namehdd,filenameyour image \ -device virtio-blk,drivehdd \ -chardev socket,idchar0,path/tmp/vfsd.sock \ -device vhost-user-fs-pci,queue-size1024,chardevchar0,tagmyfs \ -object memory-backend-memfd,idmem,size4G,shareon \ -numa node,memdevmem \ -accel kvm -m 4G guest# mount -t virtiofs myfs /mnt要点客户机挂载时使用的myfs必须与-device vhost-user-fs-pci中的tagmyfs一致memory-backend-memfd必须带shareon且其size必须与-m定义的内存大小一致virtio-fs 依赖共享内存完成零拷贝数据传递。virtiofsd 内部默认仅使用 1 个请求队列加 1 个高优先级队列REQUEST_QUEUES 1NUM_QUEUES 2见 src/main.rsQEMU 侧queue-size1024用于设定 virtqueue 容量。用 virtiofs 作为 Cloud Hypervisor 客户机 rootfsCubeSandbox 集成的 Cloud Hypervisor 也支持将 virtiofs 作为客户机根文件系统无根块设备场景完整操作指南见 hypervisor/docs/virtiofs-root.md。其核心命令为sudo virtiofsd --socket-path$PWD/virtiofs-rootfs.sock --shared-dir$PWD/rootfs --cachenever sudo cloud-hypervisor \ --cpus boot1,max1 \ --kernel vmlinux \ --fs tag/dev/root,socket$PWD/virtiofs-rootfs.sock \ --memory size2G,sharedon \ --cmdline consolehvc0 rootfstypevirtiofs root/dev/root ro debug \ --api-socket $PWD/ch.sock \ --rng \ --net ...该场景有两个容易踩坑的要点hypervisor/docs/virtiofs-root.md 中特别提示tag必须使用/dev/root才能正常工作--memory必须为 shared 内存。此外由于根文件系统内容是只读的ro这里配合--cachenever使用。以非特权用户运行 virtiofsd非 root 运行 virtiofsd 时必须依赖用户命名空间见user_namespaces(7)才能切换客户机内的任意 uid/gid。在未写入uid_map与gid_map即未建立 UID/GID 映射的用户命名空间中virtiofsd 会直接失败。以下假设调用者的 UID 与 GID 均为 1000且/etc/subuid与/etc/subgid内容都为1000:100000:65536方式一使用podman-unshare(1)。它配置的用户命名空间使调用者的 UID 与主 GID即 1000分别呈现为 UID 0 与 GID 0并通过newuidmap(1)/newgidmap(1)将/etc/subuid、/etc/subgid中匹配该用户/组的范围原样映射进去host$ podman unshare -- virtiofsd --socket-path/tmp/vfsd.sock --shared-dir /mnt \ --announce-submounts --sandbox chroot 方式二使用lxc-usernsexec(1)把调用者留在映射之外让用户命名空间内的 root 映射到用户/组 100000host$ lxc-usernsexec -m b:0:100000:65536 -- virtiofsd --socket-path/tmp/vfsd.sock \ --shared-dir /mnt --announce-submounts --sandbox chroot 要获得与podman-unshare(1)相同的行为则需要两条映射规则host$ lxc-usernsexec -m b:0:1000:1 -m b:1:100000:65536 -- virtiofsd --socket-path/tmp/vfsd.sock \ --shared-dir /mnt --announce-submounts --sandbox chroot 也可以把上述命令中的--sandbox chroot换成--sandbox none。从 src/sandbox.rs 的enter()逻辑可见chroot模式仅允许 root 使用非特权用户会收到SandboxModeInvalidUID错误而--uid-map/--gid-map仅允许非特权用户在namespace沙箱下使用。非特权模式限制客户机内无法在共享目录中创建块设备或字符设备节点virtiofsd 无法使用文件句柄--inode-file-handles需要CAP_DAC_READ_SEARCH因此需要维持大量打开的文件描述符在 NFS 上不使用文件句柄还可能导致文件删除后残留隐藏文件NFS silly rename 问题virtiofsd 无法提高RLIMIT_NOFILE。扩展属性xattr映射默认情况下客户机使用的 xattr 名称会原样直通到宿主机文件系统。这在两类场景下会有问题一是该 xattr 名称被宿主机侧机制占用如 SELinux 在客户机/宿主机间的混淆二是 virtiofsd 运行在受限容器中、无法访问某些属性。映射语法通过--xattrmapmapping建立映射mapping由一系列规则组成。查找映射时第一条匹配的规则生效规则集中必须覆盖所有 xattr 名称典型做法是最后一条规则做成 catch-all 兜底。每条规则由若干字段组成字段分隔符是该规则中第一个非空白字符同一规则内必须复用该分隔符规则前后可自由加空白。使用:作分隔符时规则形式为:type:scope:key:prepend:scope取值client在客户机的 setxattr/getxattr/removexattr 请求中用key匹配属性名server在宿主机返回的 listxattr 结果中用prepend匹配属性名all单条规则同时触发 server 与 client 两侧的匹配。type取值prefix用于前缀的加/减——客户机侧匹配key并加上prepend前缀再传给服务端服务端侧剥掉prepend前缀后传给客户机ok命中即终止规则集并放行匹配的 xattr 原样通过。用于显式终止规则链或让某些 xattr 跳过后续规则bad客户机使用匹配key的名称时以EPERM拒绝宿主机侧匹配prepend的属性被隐藏。用法类似ok作为显式终止符或对特定模式的特殊处理unsupported客户机使用匹配key的名称时以ENOTSUP拒绝宿主机侧匹配prepend的属性被隐藏。用法同bad。key以字符串前缀形式测试客户机侧属性名可为空——空的client规则匹配所有客户机名称。prepend以字符串前缀形式测试宿主机侧属性名并作为新前缀使用可为空——空的server规则匹配所有宿主机名称。常用规则示例详见 扩展属性映射文档映射规则说明:prefix:client:trusted.:user.virtiofs.:匹配客户机调用中的trusted.*属性加前缀后传给宿主机:prefix:server::user.virtiofs.:从所有宿主机应答中剥掉user.virtiofs.前缀:prefix:all:trusted.:user.virtiofs.:上面两条合并为一条规则:ok:client:user.::放行user.属性的 get/set xattr:ok:server::security.:在宿主机 listxattr 结果中放行security.属性:ok:all:::终止规则搜索其余属性双向放行:bad:server::security.:隐藏宿主机 listxattr 结果中的security.属性map 简写map类型提供常见场景的短语法:map:key:prepend:它展开为若干条规则为匹配的keykey 为空时匹配所有属性加上prepend前缀。最多只能有一条map规则且必须是规则集最后一条。注意当security.capability这个 xattr 被重映射时守护进程必须额外做大量去除工作这些工作宿主机内核通常会自行完成。安全考量操作系统通常用约定前缀划分 xattr 命名空间各分区访问控制不同。Linux 上常见分区system.*访问控制取决于属性与文件系统security.*仅具有CAP_SYS_ADMIN的进程可访问trusted.*仅具有CAP_SYS_ADMIN的进程可访问user.*任何由文件权限/属主授权的进程可访问。FreeBSD 等系统则有不同的前缀与访问控制规则。重映射时必须确保不会让客户机用户绕过客户机侧访问控制。例如若把客户机的trusted.*重映射为宿主机user.virtiofs.trusted.*Linux 客户机内的非特权用户有权写user.*下的 xattr于是可借写user.virtiofs.trusted.*绕过trusted.*的访问限制。由于不同客户机 OS 的分区规则不同最稳妥的方案是一次性把所有 xattr 重映射到固定前缀如下面示例 1而选择性映射时必须显式阻断对重映射目标的直接访问如下面示例 2。映射示例为所有属性加user.virtiofs.前缀--xattrmap:prefix:all::user.virtiofs.::bad:all:::第一条规则加/剥user.virtiofs.前缀第二条规则隐藏宿主机设置的任何未加前缀属性。等价于map简写--xattrmap:map::user.virtiofs.:只前缀trusted.属性、放行其余--xattrmap/prefix/all/trusted./user.virtiofs./ /bad/server//trusted./ /bad/client/user.virtiofs.// /ok/all///每条规则实际写在一行此处分行仅为清晰展示。四条规则依次为前缀trusted.并剥user.virtiofs.隐藏宿主机上未加前缀的trusted.阻止客户机直接写user.virtiofs.路径防止绕过前面重映射目标的访问控制最后放行剩余全部属性。等价于map简写--xattrmap/map/trusted./user.virtiofs./隐藏security.属性、放行其他--xattrmap/bad/all/security./security./ /ok/all///第一条all规则同时覆盖客户机请求与宿主机返回的列表阻止客户机看到或设置宿主机上任何security.属性。SELinux 支持启用 SELinux 支持只需加--security-label。但该选项会尝试把客户机的安全上下文保存到宿主机 xattrsecurity.selinux若宿主 SELinux 策略不允许 virtiofsd 执行该操作则会失败。因此官方推荐把客户机的security.selinuxxattr 重映射为宿主机上的trusted.virtiofs.security.selinux在命令行加入--xattrmap:map:security.selinux:trusted.virtiofs.:这样客户机与宿主机在同一文件上的 SELinux xattr 相互隔离、互不干扰宿主机与客户机可以各自实施独立的 SELinux 策略。由于在宿主机上设置 trusted xattr 需要CAP_SYS_ADMIN需要给守护进程追加该 capability--modcapssys_admintrustedxattr 不随命名空间隔离因此 virtiofsd 必须在init_user_ns中持有CAP_SYS_ADMIN——即不应使用用户命名空间。需要权衡的是授予CAP_SYS_ADMIN提升了系统风险一旦 virtiofsd 被攻破攻击者可能对宿主机系统造成较大损害请务必在启用前评估这一取舍。FAQ常见集成问题如何只读共享一个客户机内不可修改的目录导出一个只读挂载点即可。例如导出share的只读视图mkdir ro-share mount -o bind,ro share ro-share virtiofsd --shared-dir ro-share ...如何用同一个 virtiofsd 共享多个目录目前 virtiofsd 仅支持共享单个目录但可以通过子挂载submounts实现。例如同时导出share0、share1mkdir -p share/{sh0,sh1} mount -o bind share0 share/sh0 mount -o bind share1 share/sh1 virtiofsd --announce-submounts --shared-dir share ...注意必须使用--announce-submounts防止数据丢失/损坏。如何给已有 QEMU 命令行添加 virtiofs 设备若命令行尚未包含-object memory-backend-memfd,idmem且没有-numa node,memdevmem或-machine选项中的memory-backendmem属性先补上若已配置其他内存后端需将其改为memory-backend-memfd-object memory-backend-memfd必须带shareon且size必须与-m定义的内存大小一致每个 virtiofs 设备挂载添加一对参数-chardev socket,id${MATCHING_ID},path${VIRTIOFSD_SOCKET_PATH}和-device vhost-user-fs-pci,queue-size1024,chardev${MATCHING_ID},tag${VIRTIOFS_TAG}替换其中的 shell 风格变量即可。从代码看 virtiofsd 的运行主流程为了更深入地理解上述参数如何生效可沿 src/main.rs 的main()追踪启动链路解析命令行含-o兼容格式并校验共享目录存在初始化日志stderr 或 syslog与信号处理SIGHUP/SIGTERM直接退出创建/复用 vhost-user listener写入 pid 文件必要时设置 socket 组所有权根据--sandbox进入沙箱namespace/chroot/none在沙箱内完成挂载隔离并取得隔离后的/proc/self/fd与/proc/self/mountinfo句柄组装passthrough::Config缓存超时、xattr、announce-submounts、文件句柄模式、writeback、killpriv-v2、迁移参数等以 root 身份收缩 capabilities创建PassthroughFs与VhostUserFsBackend启动VhostUserDaemon等待 frontend 接入并服务请求。其中 vhost-user 后端按 50-virtiofsd.json 声明为typefs、feature 为migrate-precopy对应--print-capabilities的输出与迁移相关参数的实现。值得留意的是src/main.rs 中VhostUserFsBackend完整实现了 vhost-user 的迁移协议set_device_state_fd/check_device_state以及prepare_serialization预迁移线程这与--migration-mode、--migration-on-error、--migration-verify-handles、--migration-confirm-paths四个迁移选项共同构成 virtiofsd 的 live-migration 能力。小结virtiofsd 以 Rust 实现了 virtio-fs vhost-user 后端把宿主机目录以近乎原生的性能安全地共享给虚拟机客户机。其安全模型由 seccomp 白名单、最小 capabilities 集与 namespace/chroot 沙箱三层构成--sandbox、--inode-file-handles、--cache、--xattrmap等参数分别从隔离性、fd 资源占用、缓存一致性、xattr 安全映射等维度提供了细粒度调优能力配合 QEMU/Cloud Hypervisor 的 vhost-user-fs 设备与memory-backend-memfd共享内存即可在数分钟内搭建出一条可用的宿主机-客户机文件共享通道并进一步借助迁移参数实现安全的 live migration。相关源码与文档可在 hypervisor/virtiofsd 目录下继续深读命令行解析见 src/main.rs沙箱实现见 src/sandbox.rsseccomp 白名单见 src/seccomp.rs直通文件系统见 src/passthroughxattr 映射的完整规范见 doc/xattr-mapping.md。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考