Go New Mount API — Complete GuideGo 语言 New Mount API 完全指南

1. Overview1. 概述

Workflow Comparison工作流对比

mount("proc", "/proc",
      "proc", 0,
      "hidepid=2,subset=pid")

fsfd = fsopen("proc")
fsconfig(fsfd, SET_STRING, "hidepid", "invisible")
fsconfig(fsfd, SET_STRING, "subset", "pid")
fsconfig(fsfd, CMD_CREATE)
mntfd = fsmount(fsfd)
move_mount(mntfd, "", FDCWD, "/proc")

2. Quick Start: Your First Go Program2. 快速上手：你的第一个 Go 程序

package main

import (
    "fmt"
    "os"

    "golang.org/x/sys/unix"
)

func main() {
    // 1. Open tmpfs filesystem context
    fsfd, err := unix.Fsopen("tmpfs", unix.FSOPEN_CLOEXEC)
    if err != nil {
        fmt.Fprintf(os.Stderr, "fsopen(tmpfs): %v\n", err)
        os.Exit(1)
    }
    defer unix.Close(fsfd)

    // 2. Set parameters
    if err := unix.FsconfigSetString(fsfd, "size", "100M"); err != nil {
        fmt.Fprintf(os.Stderr, "fsconfig size: %v\n", err)
        os.Exit(1)
    }
    if err := unix.FsconfigSetString(fsfd, "mode", "1777"); err != nil {
        fmt.Fprintf(os.Stderr, "fsconfig mode: %v\n", err)
        os.Exit(1)
    }

    // 3. Create the filesystem instance
    if err := unix.FsconfigCreate(fsfd); err != nil {
        fmt.Fprintf(os.Stderr, "fsconfig create: %v\n", err)
        os.Exit(1)
    }

    // 4. Create a mount object
    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, 0)
    if err != nil {
        fmt.Fprintf(os.Stderr, "fsmount: %v\n", err)
        os.Exit(1)
    }
    defer unix.Close(mntfd)

    // 5. Attach to target path
    if err := unix.MoveMount(mntfd, "", unix.AT_FDCWD, "/mnt/mytmp",
        unix.MOVE_MOUNT_F_EMPTY_PATH); err != nil {
        fmt.Fprintf(os.Stderr, "move_mount: %v\n", err)
        os.Exit(1)
    }

    fmt.Println("tmpfs mounted at /mnt/mytmp")
}

3.1 fsopen — Open a Filesystem Context3.1 fsopen — 打开文件系统上下文

Creates a blank filesystem configuration context for subsequent parameter setting and mounting.

创建一个空白的文件系统配置上下文，用于后续的参数设置和挂载。

func unix.Fsopen(fsName string, flags int) (fd int, err error)

Requires CAP_SYS_ADMIN.

需要 CAP_SYS_ADMIN 权限。

3.2 fsconfig — Configure Parameters & Issue Commands3.2 fsconfig — 配置参数 & 执行命令

// Set a string parameter
func unix.FsconfigSetString(fd int, key, value string) error

// Set a boolean flag
func unix.FsconfigSetFlag(fd int, key string) error

// Set a file descriptor parameter
func unix.FsconfigSetFd(fd int, key string, fdValue int) error

// Set a binary blob parameter
func unix.FsconfigSetBinary(fd int, key string, value []byte) error

// Create the filesystem instance
func unix.FsconfigCreate(fd int) error

// Reconfigure an existing instance
func unix.FsconfigReconfigure(fd int) error

3.3 fsmount — Create a Mount Object3.3 fsmount — 创建挂载对象

func unix.Fsmount(fsfd int, flags int, mountAttrs int) (mntfd int, err error)

3.4 move_mount — Attach to Target3.4 move_mount — 挂载到目标

func unix.MoveMount(fromFd int, fromPath string, toFd int, toPath string, flags int) error

Most common usage (mount from mntfd):

最常见的用法（从 mntfd 挂载）：

unix.MoveMount(mntfd, "", unix.AT_FDCWD, "/mnt/target",
    unix.MOVE_MOUNT_F_EMPTY_PATH)

3.5 fspick — Pick an Existing Instance3.5 fspick — 选择已有实例

Used for online reconfiguration of an existing mount's parameters (no unmount needed). Available since Linux 5.8.

用于在线重配置一个已有挂载点的参数（无需卸载重挂）。从 Linux 5.8 开始可用。

func unix.Fspick(dirfd int, pathName string, flags int) (fd int, err error)

4.1 proc — Process Information Filesystem4.1 proc — 进程信息文件系统

Parameters

参数表

func mountProc(target string) error {
    fsfd, err := unix.Fsopen("proc", unix.FSOPEN_CLOEXEC)
    if err != nil { return fmt.Errorf("fsopen(proc): %w", err) }
    defer unix.Close(fsfd)

    unix.FsconfigSetString(fsfd, "hidepid", "invisible")
    unix.FsconfigSetString(fsfd, "subset", "pid")
    unix.FsconfigSetString(fsfd, "gid", "1000") // proc group
    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("fsconfig create: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NODEV|unix.MOUNT_ATTR_NOEXEC)
    if err != nil { return fmt.Errorf("fsmount: %w", err) }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.2 tmpfs — In-Memory Filesystem4.2 tmpfs — 内存文件系统

Parameters

参数表

func mountTmpfs(target, size, mode string) error {
    fsfd, err := unix.Fsopen("tmpfs", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetString(fsfd, "size", size)
    unix.FsconfigSetString(fsfd, "mode", mode)
    unix.FsconfigSetString(fsfd, "nr_inodes", "100000")
    unix.FsconfigSetFlag(fsfd, "noswap")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create tmpfs: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, unix.MOUNT_ATTR_NOSUID)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.3 devpts — Pseudo-Terminal Filesystem4.3 devpts — 伪终端文件系统

Parameters

参数表

func mountDevpts(target string) error {
    fsfd, err := unix.Fsopen("devpts", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetFlag(fsfd, "newinstance")
    unix.FsconfigSetString(fsfd, "gid", "5")     // tty group
    unix.FsconfigSetString(fsfd, "mode", "0620")
    unix.FsconfigSetString(fsfd, "ptmxmode", "0000")
    unix.FsconfigSetString(fsfd, "max", "1024")

    if err := unix.FsconfigCreate(fsfd); err != nil { return err }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NOEXEC)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.4 mqueue — POSIX Message Queues4.4 mqueue — POSIX 消息队列

func mountMqueue(target string) error {
    fsfd, _ := unix.Fsopen("mqueue", unix.FSOPEN_CLOEXEC)
    defer unix.Close(fsfd)
    unix.FsconfigCreate(fsfd)
    mntfd, _ := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, unix.MOUNT_ATTR_NOSUID)
    defer unix.Close(mntfd)
    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.5 sysfs — Kernel Device Model4.5 sysfs — 内核设备模型

func mountSysfs(target string) error {
    fsfd, _ := unix.Fsopen("sysfs", unix.FSOPEN_CLOEXEC)
    defer unix.Close(fsfd)
    unix.FsconfigCreate(fsfd)
    mntfd, _ := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NODEV|unix.MOUNT_ATTR_NOEXEC)
    defer unix.Close(mntfd)
    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.6 cgroup2 — Unified Control Group v24.6 cgroup2 — 统一控制组 v2

Parameters — all flag type (FsconfigSetFlag)

参数表 — 全部为 flag 类型（FsconfigSetFlag）

func mountCgroup2(target string) error {
    fsfd, err := unix.Fsopen("cgroup2", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetFlag(fsfd, "nsdelegate")
    unix.FsconfigSetFlag(fsfd, "memory_recursiveprot")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create cgroup2: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NODEV|unix.MOUNT_ATTR_NOEXEC)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.7 debugfs — Kernel Debug Filesystem4.7 debugfs — 内核调试文件系统

4.8 tracefs — Kernel Tracing Filesystem4.8 tracefs — 内核追踪文件系统

4.9 hugetlbfs — Huge Page Filesystem4.9 hugetlbfs — 大页文件系统

4.10 overlay — Union Filesystem4.10 overlay — 联合文件系统

Parameters

参数表

func mountOverlay(target, lower, upper, work string) error {
    fsfd, err := unix.Fsopen("overlay", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetString(fsfd, "lowerdir+", lower)
    unix.FsconfigSetString(fsfd, "upperdir", upper)
    unix.FsconfigSetString(fsfd, "workdir", work)
    unix.FsconfigSetString(fsfd, "redirect_dir", "on")
    unix.FsconfigSetString(fsfd, "index", "on")
    unix.FsconfigSetString(fsfd, "xino", "auto")
    unix.FsconfigSetString(fsfd, "metacopy", "on")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create overlay: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, unix.MOUNT_ATTR_NOSUID)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

4.11 bpf — BPF Program Filesystem4.11 bpf — BPF 程序文件系统

4.12 ramfs — Non-swappable RAM Filesystem4.12 ramfs — 不可换出的内存文件系统

4.13 pstore — Persistent Storage Filesystem4.13 pstore — 持久存储文件系统

4.14 efivarfs — EFI Variable Filesystem4.14 efivarfs — EFI 变量文件系统

4.15 devtmpfs — Device Node Population4.15 devtmpfs — 设备节点填充

4.16 Filesystems Without Parameters4.16 无参数文件系统

The following filesystems accept no parameters in the new mount API. Simply fsopen → FsconfigCreate → fsmount:

以下文件系统在新挂载 API 中不接受任何参数，流程简化为 fsopen → FsconfigCreate → fsmount：

5.1 Scenario: Secure /proc Mount5.1 场景：安全挂载 /proc

A complete, production-grade secure /proc mount for container sandboxes:

完整的、生产级别的安全 /proc 挂载，用于容器沙箱：

// MountProcSafe mounts /proc in the most restrictive mode.
// Equivalent to: mount -t proc proc /proc -o hidepid=invisible,gid=1000,subset=pid
func MountProcSafe(target string, exemptGid int) error {
    fsfd, err := unix.Fsopen("proc", unix.FSOPEN_CLOEXEC)
    if err != nil {
        return fmt.Errorf("fsopen(proc): %w", err)
    }
    defer unix.Close(fsfd)

    if err := unix.FsconfigSetString(fsfd, "hidepid", "invisible"); err != nil {
        return err
    }
    if err := unix.FsconfigSetString(fsfd, "gid",
        strconv.Itoa(exemptGid)); err != nil {
        return err
    }
    if err := unix.FsconfigSetString(fsfd, "subset", "pid"); err != nil {
        return err
    }

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create proc: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NODEV|unix.MOUNT_ATTR_NOEXEC)
    if err != nil {
        return fmt.Errorf("fsmount: %w", err)
    }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

5.2 Scenario: tmpfs with Quotas5.2 场景：带配额的 tmpfs

func MountTmpfsWithQuota(target, size string, uid, gid int) error {
    fsfd, err := unix.Fsopen("tmpfs", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetString(fsfd, "size", size)
    unix.FsconfigSetString(fsfd, "mode", "1777")
    unix.FsconfigSetString(fsfd, "uid", strconv.Itoa(uid))
    unix.FsconfigSetString(fsfd, "gid", strconv.Itoa(gid))
    unix.FsconfigSetString(fsfd, "nr_inodes", "50000")
    unix.FsconfigSetFlag(fsfd, "noswap")

    // Enable quotas (requires CONFIG_TMPFS_QUOTA)
    unix.FsconfigSetFlag(fsfd, "usrquota")
    unix.FsconfigSetFlag(fsfd, "grpquota")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create tmpfs: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, unix.MOUNT_ATTR_NOSUID)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

5.3 Scenario: cgroup2 Container Runtime5.3 场景：cgroup2 容器运行时

func MountCgroup2(target string) error {
    fsfd, err := unix.Fsopen("cgroup2", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetFlag(fsfd, "nsdelegate")
    unix.FsconfigSetFlag(fsfd, "memory_recursiveprot")
    unix.FsconfigSetFlag(fsfd, "favordynmods")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create cgroup2: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_NOSUID|unix.MOUNT_ATTR_NODEV|unix.MOUNT_ATTR_NOEXEC)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

5.4 Scenario: Overlay Container rootfs5.4 场景：overlay 容器 rootfs

func MountOverlayRootFS(target, lower, upper, work string) error {
    for _, dir := range []string{target, upper, work} {
        if err := os.MkdirAll(dir, 0755); err != nil {
            return err
        }
    }

    fsfd, err := unix.Fsopen("overlay", unix.FSOPEN_CLOEXEC)
    if err != nil { return err }
    defer unix.Close(fsfd)

    unix.FsconfigSetString(fsfd, "lowerdir", lower)
    unix.FsconfigSetString(fsfd, "upperdir", upper)
    unix.FsconfigSetString(fsfd, "workdir", work)
    unix.FsconfigSetString(fsfd, "redirect_dir", "on")
    unix.FsconfigSetString(fsfd, "index", "on")
    unix.FsconfigSetString(fsfd, "xino", "auto")
    unix.FsconfigSetString(fsfd, "metacopy", "on")

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return fmt.Errorf("create overlay: %w", err)
    }

    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, unix.MOUNT_ATTR_NOSUID)
    if err != nil { return err }
    defer unix.Close(mntfd)

    return unix.MoveMount(mntfd, "", unix.AT_FDCWD, target,
        unix.MOVE_MOUNT_F_EMPTY_PATH)
}

5.5 Scenario: Runtime Reconfiguration5.5 场景：运行时重配置 proc 参数

// ReconfigureProc modifies an existing /proc mount's hidepid setting at runtime.
// Equivalent to: mount -o remount,hidepid=invisible /proc
func ReconfigureProc(hidepid, subset string) error {
    fsfd, err := unix.Fspick(unix.AT_FDCWD, "/proc", unix.FSPICK_CLOEXEC)
    if err != nil {
        return fmt.Errorf("fspick(/proc): %w", err)
    }
    defer unix.Close(fsfd)

    if hidepid != "" {
        if err := unix.FsconfigSetString(fsfd, "hidepid", hidepid); err != nil {
            return err
        }
    }
    if subset != "" {
        if err := unix.FsconfigSetString(fsfd, "subset", subset); err != nil {
            return err
        }
    }

    return unix.FsconfigReconfigure(fsfd)
}

Appx A: fsparam Type Cheat Sheet附录 A：fsparam 类型速查

Appx B: mountAttr Flags附录 B：mountAttr 属性标志

Appx C: Error Diagnostics附录 C：错误诊断

A key advantage of the new API: read detailed error messages from the context fd.

新 API 的一大优势：可以从上下文 fd 读取详细的错误消息。

func readFsconfigError(fsfd int) string {
    buf := make([]byte, 4096)
    n, err := unix.Read(fsfd, buf)
    if err != nil {
        return "(no diagnostic message)"
    }
    return string(buf[:n])
}

if err := unix.FsconfigCreate(fsfd); err != nil {
    diag := readFsconfigError(fsfd)
    return fmt.Errorf("create failed: %w [diag: %s]", err, diag)
}

Message format:

消息格式：

"e <subsystem>:<message>"  // error
"w <subsystem>:<message>"  // warning
"i <subsystem>:<message>"  // info

Appx D: Dependencies & Imports附录 D：依赖与导入

import (
    "golang.org/x/sys/unix"
)

Appx E: Real-World Best Practices & References附录 E：落地最佳实践与参考项目

The new mount API is not just theoretical — it has been adopted in production by major container runtimes and security libraries. Below are key real-world references that demonstrate battle-tested usage patterns.

新 mount API 并非纸上谈兵——它已被主流容器运行时和安全库在生产环境中采用。以下是经过实战检验的关键参考项目。

E.1 brauner/man-pages-md — Authoritative API DocumentationE.1 brauner/man-pages-md — 权威 API 文档

github.com/brauner/man-pages-md is the definitive reference for the new mount API man pages, maintained by Christian Brauner (Linux kernel maintainer for the VFS, mount, and namespace subsystems — essentially the person who designed this API). The repository provides:

github.com/brauner/man-pages-md 是新 mount API 手册页的权威参考，由 Christian Brauner（Linux 内核 VFS、mount 和 namespace 子系统的维护者——本质上就是这套 API 的设计者）维护。该仓库提供：

E.2 runc PR #5378 — libct: Switch to New Mount APIE.2 runc PR #5378 — libct：切换到新 Mount API

opencontainers/runc#5378 is the landmark pull request where runc — the reference OCI container runtime used by Docker, Kubernetes, and containerd — migrated its libct (container library) mount infrastructure from the legacy mount(2) syscall to the new mount API. This PR demonstrates production-grade usage at scale.

opencontainers/runc#5378 是标志性的 PR——runc（Docker、Kubernetes 和 containerd 使用的 OCI 参考容器运行时）将其 libct（容器库）挂载基础设施从传统 mount(2) 系统调用迁移到新 mount API。此 PR 展示了大规模生产环境的用法。

Key Takeaways

核心要点

1. Graceful fallback: runc probes kernel support at runtime and falls back to legacy mount(2) on older kernels — essential for portability across Linux distributions.
2. 优雅降级：runc 在运行时探测内核支持，并在旧内核上回退到传统 mount(2) ——这对跨 Linux 发行版的可移植性至关重要。
3. Detailed error diagnostics: The PR leverages read() on the fs_context fd to extract human-readable error messages, significantly improving debuggability compared to legacy mount(2) which only returns EINVAL.
4. 详细的错误诊断：该 PR 利用 fs_context fd 上的 read() 提取人类可读的错误消息，相比传统 mount(2) 仅返回 EINVAL，显著提升了可调试性。
5. Unified mount helper: The PR introduces a common mount wrapper that handles the full fsopen → fsconfig → fsmount → move_mount sequence, ensuring consistent error handling across all filesystem types (proc, tmpfs, devpts, cgroup2, sysfs, etc.).
6. 统一挂载辅助函数：该 PR 引入了通用挂载包装器，处理完整的 fsopen → fsconfig → fsmount → move_mount 序列，确保所有文件系统类型（proc、tmpfs、devpts、cgroup2、sysfs 等）的错误处理一致。
7. Idempotent reconfiguration: Uses fspick() + FSCONFIG_CMD_RECONFIGURE for online parameter changes without unmounting — critical for long-running container processes.
8. 幂等重配置：使用 fspick() + FSCONFIG_CMD_RECONFIGURE 实现在线参数修改而不卸载——这对长时间运行的容器进程至关重要。

// Probe whether the new mount API is available on this kernel.
// If not, fall back to unix.Mount (legacy mount(2)).
var useNewMountAPI bool

func init() {
    // Try fsopen on a trivial filesystem
    fsfd, err := unix.Fsopen("tmpfs", unix.FSOPEN_CLOEXEC)
    if err != nil {
        useNewMountAPI = false
        return
    }
    unix.Close(fsfd)
    useNewMountAPI = true
}

func mountSafe(source, target, fstype string, flags uintptr, data string) error {
    if useNewMountAPI {
        return mountNew(source, target, fstype, flags, data)
    }
    return unix.Mount(source, target, fstype, flags, data)
}

E.3 runc PR #4448 — Overlayfs Write-Protect for /proc/self/exeE.3 runc PR #4448 — 用 overlayfs 写保护 /proc/self/exe

opencontainers/runc#4448 by Aleksa Sarai (cyphar) demonstrates an elegant security hardening technique: using the new mount API to create an overlayfs mount that write-protects a container runtime's own /proc/self/exe, preventing attackers from modifying the runtime binary even if they gain write access. This is a beautiful example of the new mount API's ability to create complex, detached mount trees without polluting the global namespace.

opencontainers/runc#4448 由 Aleksa Sarai（cyphar）开发，展示了一种精巧的安全加固技术：使用新 mount API 创建 overlayfs 挂载来写保护容器运行时自身的 /proc/self/exe，防止攻击者即使获得写权限后修改运行时二进制文件。这是新 mount API 在不污染全局命名空间的情况下创建复杂、游离挂载树的绝佳范例。

Key Takeaways

核心要点

1. Detached mounts for security: Creates an overlay mount object without ever attaching it to the global VFS, then uses it purely through file descriptors — a pattern impossible with legacy mount(2).
2. 安全游离挂载：创建 overlay 挂载对象而从不附加到全局 VFS，然后纯粹通过文件描述符使用它——这是传统 mount(2) 无法实现的模式。
3. Opportunistic use: Gracefully falls back to a memfd-based approach when overlayfs isn't available or when the new mount API isn't supported — never breaks existing functionality.
4. 机会主义使用：当 overlayfs 不可用或新 mount API 不支持时优雅降级到基于 memfd 的方式——从不破坏现有功能。
5. Minimal privilege surface: Uses overlayfs read-only lowerdir to create a tamper-proof view of the runtime binary, reducing the attack surface even if the attacker has root in the container.
6. 最小化权限面：使用 overlayfs 只读 lowerdir 创建运行时二进制的防篡改视图，即使攻击者在容器中拥有 root 权限也能减小攻击面。

func sealExecutable(exePath string) (*os.File, error) {
    fsfd, err := unix.Fsopen("overlay", unix.FSOPEN_CLOEXEC)
    if err != nil {
        return nil, err // Caller should fall back to memfd
    }
    defer unix.Close(fsfd)

    // lowerdir = the original executable (read-only)
    unix.FsconfigSetString(fsfd, "lowerdir", filepath.Dir(exePath))
    // workdir = ephemeral, unused since we're read-only
    unix.FsconfigSetString(fsfd, "workdir", workDir)

    if err := unix.FsconfigCreate(fsfd); err != nil {
        return nil, err
    }

    // Get a detached mount — never attached to VFS!
    mntfd, err := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC,
        unix.MOUNT_ATTR_RDONLY)
    if err != nil {
        return nil, err
    }

    // Open the sealed binary from the detached mount
    fd, err := unix.Openat(mntfd, filepath.Base(exePath),
        unix.O_RDONLY|unix.O_CLOEXEC, 0)
    unix.Close(mntfd)
    if err != nil {
        return nil, err
    }

    return os.NewFile(uintptr(fd), "sealed-exe"), nil
}

E.4 cyphar/filepath-securejoin — Secure Path Operations via Mount APIE.4 cyphar/filepath-securejoin — 基于 Mount API 的安全路径操作

github.com/cyphar/filepath-securejoin by Aleksa Sarai is the gold standard for how the new mount API should be used in security-critical Go code. Originally a safer alternative to filepath.Join, the library has evolved to deeply integrate with the new mount API (openat2, fsopen, open_tree) to eliminate entire classes of TOCTOU (Time-of-Check-Time-of-Use) vulnerabilities that plague path-based APIs.

github.com/cyphar/filepath-securejoin 由 Aleksa Sarai 开发，是新 mount API 在安全关键 Go 代码中使用的标杆。最初作为 filepath.Join 的安全替代品，该库已深度集成了新 mount API（openat2、fsopen、open_tree），以消除困扰基于路径 API 的各类 TOCTOU（检查时间-使用时间）漏洞。

Architecture & Best Practices

架构与最佳实践

// OpenInRoot safely opens a path within a rootfs.
// This is a simplified illustration of filepath-securejoin's approach.
func OpenInRoot(root, unsafePath string) (*os.File, error) {
    // Phase 1: Open the root directory
    rootFd, err := unix.Open(root, unix.O_PATH|unix.O_CLOEXEC, 0)
    if err != nil {
        return nil, fmt.Errorf("open root %s: %w", root, err)
    }
    defer unix.Close(rootFd)

    // Phase 2: If we have privileges, create a private mount
    // of root to protect against /proc magic-link attacks.
    // This is what filepath-securejoin does opportunistically:
    //   fsfd = fsopen(rootFd)
    //   open_tree to get a private copy
    //   use the private fd for the rest of the resolution

    // Phase 3: Resolve the path using openat2(RESOLVE_IN_ROOT)
    // on Linux 5.6+, or manual component-wise resolution otherwise
    how := &unix.OpenHow{
        Flags:   unix.O_PATH | unix.O_CLOEXEC | unix.O_NOFOLLOW,
        Mode:    0,
        Resolve: unix.RESOLVE_IN_ROOT | unix.RESOLVE_NO_MAGICLINKS,
    }
    fd, err := unix.Openat2(rootFd, unsafePath, how)
    if err != nil {
        return nil, fmt.Errorf("openat2: %w", err)
    }

    return os.NewFile(uintptr(fd), unsafePath), nil
}

E.5 How These Projects Fit TogetherE.5 这些项目如何协同

These four references form a complete picture of the new mount API ecosystem:

这四个参考形成了新 mount API 生态的完整图景：

Recommended reading order: Start with brauner/man-pages-md for authoritative API reference → study runc#5378 for real-world migration patterns → explore runc#4448 for advanced detached-mount techniques → dive into filepath-securejoin for security-first API design principles.

推荐阅读顺序：从 brauner/man-pages-md 入手了解权威 API 参考 → 研究 runc#5378 学习真实迁移模式 → 探索 runc#4448 掌握高级游离挂载技巧 → 深入 filepath-securejoin 理解安全优先的 API 设计原则。

Go New Mount API — Complete Guide  ·  Based on Linux 6.x kernel source  ·  References: brauner/man-pages-md, runc, filepath-securejoin  ·  2026-07 Go 语言 New Mount API 完全指南  ·  基于 Linux 6.x 内核源码  ·  参考资料：brauner/man-pages-md、runc、filepath-securejoin  ·  2026-07