Linux clone3 set_tid怎样为容器初始化进程设置线程 ID

如果你要让一个新建的容器进程在自己的 PID namespace 中成为 PID 1，关键不是修改已经存在的线程，而是在调用 clone3() 时同时设置 CLONE_NEWPID、set_tid 和 set_tid_size。最常见的单层写法是：准备一个值为 1 的 pid_t 数组，把数组地址放进 clone_args.set_tid，并把长度设为 1。

先记住一句话：set_tid[] 请求的是新进程在 PID namespace 中可见的 PID，不是 pthread 库意义上的线程 ID。多个 namespace 同时设置时，数组从最内层向外层排列；要让新 namespace 的 init 进程成为 PID 1，必须让最内层对应的数组元素为 1。

官方文档入口：https://www.kernel.org/doc/html/latest/

先分清 set_tid、child_tid 和线程 ID

clone3() 的 clone_args 里有几个名字相近的字段，混在一起会导致容器启动逻辑判断错误：

因此，标题里的“线程 ID”更准确地理解为 Linux 内核语境中的任务标识；面向容器时，真正要控制的是新进程在不同 PID namespace 里的可见 PID。set_tid 并不能把一个已经运行的线程改成任意编号，也不能替代线程库创建线程的流程。

升级范围：clone3 与 set_tid 的前置条件

clone3() 是较新的系统调用接口，glibc 没有提供同名的普通封装，示例通常通过 syscall(SYS_clone3, ...) 直接进入内核。set_tid 从 Linux 5.5 起可用；使用它时，调用者需要在目标 PID namespace 所属的 user namespace 中具备 CAP_SYS_ADMIN，Linux 5.9 起也可以使用 CAP_CHECKPOINT_RESTORE。

如果同时创建新的 PID namespace，还要把 CLONE_NEWPID 放入 flags。只有新 namespace 中的第一个进程才能成为该 namespace 的 init；当请求的 PID 大于 1 时，目标 namespace 里必须已经存在 PID 1，否则该层只能请求 1。这个规则也是容器恢复和固定进程号场景最容易忽略的边界。

在实际运行时还要注意三件事：

1. 内核可能支持 clone3()，但 seccomp 策略仍可能阻止该系统调用。
2. 目标 user namespace 的能力检查是逐层进行的，宿主机有能力不等于所有目标层级都有能力。
3. 容器 init 的生命周期仍由父进程负责回收；设置 PID 不会自动完成信号转发、孤儿进程处理或文件系统隔离。

set_tid[] 的顺序为什么是由内向外

假设一个进程创建后会出现在三层嵌套的 PID namespace 中，希望它在最内层看到 7、中间层看到 42、最外层看到 31496。数组必须写成：

set_tid[0] = 7;       // 最内层 PID namespace 的可见 PID
set_tid[1] = 42;      // 下一层父 PID namespace 的可见 PID
set_tid[2] = 31496;   // 最外层 PID namespace 的可见 PID
set_tid_size = 3;     // 只请求三层，不多填未存在的层级

这个顺序与“从外层向内层读图”的习惯相反。内核把数组第一个元素解释为最深、最内侧的 PID namespace，之后的元素依次对应祖先 namespace。set_tid_size 不能大于当前嵌套的 PID namespace 数量；目标层的 PID 已经被占用时，调用会失败而不会悄悄改用下一个空闲 PID。

用 clone3() 创建 PID 1 的容器 init

下面的示例只展示系统调用参数如何组织：父进程创建一个新的 PID namespace，并请求子进程在该 namespace 中成为 PID 1。子进程随后替换为一个简单的 shell 进程；生产容器运行时应替换为自己的 init 程序，并补上挂载、网络、用户和 cgroup 等隔离步骤。

// clone3_set_tid.c：展示如何请求新 PID namespace 中的 PID 1
#define _GNU_SOURCE
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 

int main(void) {
    // 新 namespace 的第一个进程必须使用 PID 1，数组只有最内层这一项。
    pid_t requested_pid[] = {1};
    struct clone_args args = {0};

    // CLONE_NEWPID 让子进程成为新 PID namespace 的 init 候选。
    args.flags = CLONE_NEWPID;
    args.exit_signal = SIGCHLD;
    args.set_tid = (uint64_t)requested_pid;
    args.set_tid_size = 1;

    // glibc 没有 clone3() 封装，直接使用 syscall 传入结构体大小。
    long child = syscall(SYS_clone3, &args, sizeof(args));
    if (child == -1) {
        // errno 需要结合能力、PID 冲突、内核版本和 seccomp 一起判断。
        fprintf(stderr, "clone3 failed: %s\n", strerror(errno));
        return EXIT_FAILURE;
    }

    if (child == 0) {
        // 子进程在自己的 PID namespace 中执行容器入口程序。
        execl("/bin/sh", "sh", "-c", "exec /bin/sh", (char *)NULL);
        // exec 失败时直接退出，避免把错误状态伪装成容器正常运行。
        perror("exec");
        _exit(127);
    }

    // 父进程仍用宿主视角的返回值等待子进程，负责回收它。
    int status = 0;
    if (waitpid((pid_t)child, &status, 0) == -1) {
        perror("waitpid");
        return EXIT_FAILURE;
    }
    return WIFEXITED(status) ? WEXITSTATUS(status) : EXIT_FAILURE;
}

编译时只需要链接系统调用和标准 C 库，示例命令中的注释说明了每个参数的作用：

# 使用系统头文件中的 clone_args 和 SYS_clone3 定义编译示例
cc -O2 -Wall -Wextra clone3_set_tid.c -o clone3_set_tid

这个示例的返回值有两个观察角度：父进程拿到子进程在自己 namespace 中的 PID，子进程在新 PID namespace 中看到自己的 PID 为 1。不要把父进程返回的数值直接当成容器内的 PID；同一个任务在不同 namespace 中本来就可以有不同的可见 PID。

旧代码迁移时要改哪些地方

常见错误码怎么定位

• EPERM：通常先查目标 PID namespace 所属 user namespace 中的 CAP_SYS_ADMIN 或 CAP_CHECKPOINT_RESTORE，再查创建 CLONE_NEWPID 是否有权限。
• EEXIST：至少一个请求的 PID 已经存在于对应 namespace。不要盲目重试同一个数字，应重新读取 namespace 状态或让恢复协调器选择未占用的目标。
• EINVAL：重点检查 set_tid_size 是否超过 namespace 层数、PID 值是否合法，以及是否错误地把 CLONE_NEWPID 和线程/父进程关系标志组合在一起。
• ENOSYS 或被策略拦截：先区分内核不提供 clone3() 与 seccomp 拒绝两种情况。旧内核可以回退到 clone()，但它并不提供 set_tid[] 的同等接口，因此不能假设回退后仍能固定 namespace PID。

排查时应把“调用是否进入内核”“能力是否覆盖每一层”“请求的 PID 是否已存在”“数组顺序是否正确”分别记录。将所有失败都归因于权限，会把真正的 EEXIST 或 EINVAL 问题拖到错误的方向。

容器运行时的迁移清单

1. 确认最低内核版本满足 clone3() 和 set_tid 的使用条件，并确认目标架构提供对应系统调用号。
2. 把每个 PID namespace 的目标值画成由内向外的列表，再生成 set_tid[]，不要直接复用外层视角的数组。
3. 明确谁持有目标 user namespace 的能力；只在宿主机拥有能力不代表恢复进程在所有层级都满足检查。
4. 当目标 namespace 里没有 init 时，只能为该层请求 PID 1；请求更大的值前先确认 PID 1 已经存在。
5. 把 EPERM、EEXIST、EINVAL 和系统调用不可用分别映射到独立的错误处理分支。
6. 父进程继续负责等待、回收和信号管理；set_tid 只解决创建时的 PID 选择，不替代容器 init 的职责。

相关问题

set_tid[0] 为什么不是最外层 PID？

因为内核按最深的 PID namespace 开始解释数组。后续元素才对应祖先层级，这样恢复嵌套 namespace 时可以用一个数组表达由内到外的 PID 关系。

set_tid 能不能把普通线程改成指定 TID？

不能。它参与的是 clone3() 创建新任务时的 PID 选择；已经存在的线程不会因为设置该字段而被改号，child_tid 也只是把内核写回值放到指定内存位置。

容器内 PID 1 和宿主机看到的 PID 一定相同吗？

不相同。容器内 PID 1 是该 PID namespace 的视角，父进程在宿主 namespace 中收到的是另一个可见 PID。跨 namespace 记录进程时必须同时保存视角或 namespace 信息。

为什么 clone3() 失败但 clone() 可以用？

可能是旧内核不提供 clone3，也可能是 seccomp 只允许旧接口。clone() 的参数模型更老，不能直接替代 set_tid；如果业务依赖固定 PID，就需要明确声明恢复能力不可用，而不是静默当成成功。

总的判断顺序是：先确认目标 namespace 层级，再按内到外准备 set_tid[]，随后检查能力与 PID 1 前置条件，最后才根据错误码决定重试、换 PID 或走兼容路径。这样才能把“为容器初始化进程设置线程 ID”还原为一个可审查的 clone3 参数问题。