rockylinux/rocky-toolbox

Rocky Linux Toolbox 镜像文档

1. 镜像概述与主要用途

Rocky Linux Toolbox 镜像是基于 https://github.com/containers/toolbox 工具的容器化命令行环境镜像。Toolbox 构建于 https://podman.io 和 https://opencontainers.org 标准容器技术之上，允许用户在隔离的容器中使用命令行环境，同时与主机系统无缝集成。

该镜像主要用途是为 Rocky Linux 系统（尤其是 OSTree 架构的操作系统）提供可 mutable 的开发与调试环境。OSTree 系统通常不鼓励在主机直接安装软件（多数甚至不含 DNF/YUM 等包管理器），而 Toolbox 通过容器化方式解决这一问题：用户可在 Toolbox 容器内安装开发工具、编辑器、SDK 等软件，且不会影响主机系统。

2. 核心功能与特性

2.1 与主机系统无缝集成

Toolbox 容器默认提供以下主机资源访问能力：

• 用户主目录（/home/<user>）
• Wayland/X11 显示服务套接字
• 网络（含 Avahi 服务发现）
• 可移动设备（如 USB 存储）
• systemd 日志
• SSH 代理
• D-Bus 服务
• ulimits 资源限制
• /dev 设备文件与 udev 数据库

2.2 完全可变性环境

容器内环境支持完整的包管理操作（如 dnf install），用户可自由安装、升级或卸载软件，所有变更仅作用于容器内部，不影响主机系统。

2.3 跨 Rocky Linux 版本兼容性

默认根据主机系统版本创建容器（如 Rocky Linux 9 主机对应 rocky-toolbox-9 容器），同时支持通过参数指定自定义镜像，适配不同版本需求。

3. 使用场景与适用范围

3.1 OSTree 系统开发调试

对于 OSTree 架构的 Rocky Linux 系统（如 immutable 版本），Toolbox 是唯一可行的开发环境搭建方式，可在容器内安装编译器、调试器等工具。

3.2 保持主机系统清洁

在常规 Rocky Linux 系统中，使用 Toolbox 可避免直接在主机安装大量开发工具，减少系统冗余与依赖冲突风险。

3.3 渐进式容器化过渡

作为轻量级容器方案，Toolbox 为用户提供低门槛的容器化实践途径，无需深入学习容器技术即可快速上手。

4. 安装方法

在 Rocky Linux 主机系统中，需先安装 Toolbox 工具：

bash
sudo dnf install toolbox

注意：多数 OSTree 架构的操作系统默认预装 Toolbox。

5. 使用方法

5.1 创建 Toolbox 环境

在 Rocky Linux 主机执行以下命令创建默认容器：

bash
[user@hostname ~] toolbox create
已创建容器：rocky-toolbox-9
进入容器：toolbox enter

默认容器名称格式为 rocky-toolbox-<major-version-id>（如 Rocky Linux 9 主机生成 rocky-toolbox-9），镜像基于 rockylinux/rocky-toolbox:<版本>。

5.2 进入 Toolbox 容器

创建容器后，通过以下命令进入交互式环境：

bash
[user@hostname ~] toolbox enter
⬢[user@toolbox ~]$

提示符前缀 ⬢ 表示当前处于 Toolbox 容器内。

5.3 删除 Toolbox 容器

5.3.1 检查容器状态

先确认容器是否运行：

bash
[user@hostname ~] toolbox list
镜像 ID        镜像名称                  创建时间
215122d241c2    rockylinux/rocky-toolbox:9  1 分钟前

容器 ID        容器名称          创建时间       状态    镜像名称
24e4c5535369    rocky-toolbox-9   1 分钟前       运行中  rockylinux/rocky-toolbox:9

5.3.2 停止运行中的容器

若容器处于运行状态，需先停止：

bash
[user@hostname ~] podman stop rocky-toolbox-9
rocky-toolbox-9

5.3.3 删除容器

bash
[user@hostname ~] toolbox rm rocky-toolbox-9

6. 发行版支持

Toolbox 默认根据主机 /usr/lib/os-release 文件中的 ID 和 VERSION-ID 生成容器镜像名称，格式为 <ID>-toolbox:<VERSION-ID>。例如：

• Rocky Linux 9 主机默认镜像为 rocky-toolbox:9

可通过 toolbox create --image 选项覆盖默认镜像，例如使用自定义镜像：

bash
toolbox create --image my-custom-toolbox:latest

建议使用操作系统发行方提供的默认镜像，以确保兼容性。

7. 镜像要求

Toolbox 对 OCI 镜像有特定要求，以确保容器能正确定制与集成。自定义镜像需满足以下条件：

7.1 必需工具

镜像中需包含以下工具（路径需在 $PATH 中）：
getent(1), id(1), ln(1), mkdir(1), passwd(1), readlink(1), rm(1), rmdir(1), sleep(1), test(1), touch(1), unlink(1), useradd(8), usermod(8)

7.2 路径要求

以下路径需满足特定条件：

• /etc/host.conf：可选，若存在则不可为 bind mount
• /etc/hosts：可选，若存在则不可为 bind mount
• /etc/krb5.conf.d：必须为目录，不可为 bind mount
• /etc/localtime：可选，若存在则不可为 bind mount
• /etc/machine-id：可选，不可为 bind mount
• /etc/resolv.conf：可选，若存在则不可为 bind mount
• /etc/timezone：可选，若存在则不可为 bind mount

7.3 sudo 配置

Toolbox 容器内默认启用 sudo(8) 访问，需满足：

• 镜像中存在 sudo 或 wheel 用户组
• sudo 配置允许上述组用户无密码执行命令（通过 PAM 配置 nullok 选项或 sudoers 文件 NOPASSWD 标签实现）

7.4 工具兼容性标签

镜像必须包含标签 com.github.containers.toolbox="true"，以表明其符合 Toolbox 要求。可在 Dockerfile 中添加：

dockerfile
LABEL com.github.containers.toolbox="true"

8. 归因

本镜像主要参考 Fedora 的 https://src.fedoraproject.org/container/fedora-toolbox 镜像构建仓库实现。

参考链接

• Toolbox 项目：https://github.com/containers/toolbox
• Rocky Linux Toolbox 镜像：https://github.com/containers/toolbox