Ceph 内核客户端挂载全解析:mount.ceph 挂载辅助程序使用指南
Ceph 内核客户端挂载全解析:mount.ceph 挂载辅助程序使用指南
mount.ceph 是 Ceph 发行包中随附的挂载辅助程序(mount helper),专门用于在 Linux 主机上通过内核驱动挂载 CephFS 文件系统。它负责把 Monitor 主机名解析为 IP 地址、从磁盘读取 CephX 认证密钥并完成集群信息自动发现,而真正的读写工作由 Linux 内核客户端(ceph 内核模块)承担。读完本文,你将掌握 mount.ceph 的完整命令行语法(新旧两代设备字符串)、全部挂载选项的语义与默认值、基于配置文件与 keyring 的自动发现原理,以及从基础挂载到子目录挂载、多 Monitor、加密传输、故障自愈的完整实战方案。
mount.ceph 的角色定位:挂载辅助程序与内核客户端的分工
在 CephFS 的客户端生态中,存在两种挂载方式:内核驱动挂载和 FUSE 挂载(ceph-fuse)。内核驱动挂载是大多数场景的首选,因为它以原生内核性能工作。但在执行 mount 系统调用之前,还有大量准备工作需要完成:把 Monitor 主机名解析成 IP 地址、读取认证密钥、必要时补充 FSID 等集群信息。这些准备工作正是 mount.ceph 的职责——官方手册明确指出:
mount.ceph是用于在 Linux 主机上挂载 CephFS 的辅助程序。它负责将 Monitor 主机名解析为 IP 地址并从磁盘读取认证密钥;真正的主要工作由 Linux 内核客户端组件完成。
也就是说,mount.ceph 是一个"接线员":它把从命令行、配置文件、keyring、DNS 等处收集到的信息整理成内核客户端能理解的形式,然后调用 mount(2) 系统调用,把设备字符串和挂载选项一并交给内核。
该辅助程序随 Ceph 软件包一起安装(通常位于 /sbin/mount.ceph),可以这样确认其存在:
stat /sbin/mount.ceph
值得注意的是,即使没有 mount.ceph,CephFS 依然可以通过内核驱动挂载,只是必须把 Monitor 地址、CephX 密钥等细节全部显式传给 mount 命令(见 Mount CephFS using Kernel Driver)。
命令语法与设备字符串:新旧两代格式
mount.ceph 的命令行概要如下(对应手册 Synopsis 节):
mount.ceph name@fsid.fs_name=/[/subdir] dir [-o options]
其中:
name是 RADOS 客户端名称(即 CephX 用户名,手册中称为 "RADOS user",指任何个人或系统角色,如应用程序);fsid是集群 FSID,可用ceph fsid命令查询;fs_name是要挂载的 CephFS 文件系统名称;=之后是 CephFS 内的(绝对)路径,挂载到本地的dir挂载点;-o options是逗号分隔的挂载选项。
按照挂载辅助程序的惯例,前两个位置参数固定为"设备字符串"和"挂载点",所有选项只能在这两个固定参数之后传递——这一点在 parse_arguments() 函数中得到印证:argv[1] 和 argv[2] 被强制作为 src(设备字符串)和 node(挂载点)。
推荐的方式是通过 mount(8) 间接调用(此时 mount helper 语法仍是新格式):
mount -t ceph name@.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
注意:即使省略 FSID,设备字符串中的点号 . 仍然是必需的组成部分。
新格式设备字符串:name@fsid.fs_name=/path
这是当前推荐使用的 v2 语法。在 parse_new_dev() 函数中,设备字符串按以下规则解析:
@之前是 CephX 用户名(name),会同时记录到挂载选项name=中;@之后到第一个.之间是 FSID,其长度必须与CLUSTER_FSID_LEN - 1(36 个字符,UUID 标准长度)一致,否则报invalid device string format;- 第一个
.之后到=之间是文件系统名(fs_name),不能为空; =之后是 CephFS 内的挂载路径(可选,缺省即根目录)。
一个完整的示例(摘自手册 Description 节):
mount.ceph name@07fe3187-00d9-42a3-814b-72a4d5e7d5be.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
旧格式设备字符串:mon_addr:/path
为了向后兼容,mount.ceph 也支持旧语法。在 parse_old_dev() 函数中,设备字符串以 :/ 分隔 Monitor 地址与路径,格式为 <mon_addr>:/<path>。若未指定 name,默认用户名为 guest(源码中 CEPH_AUTH_NAME_DEFAULT 宏,见 mount.ceph.c)。旧语法示例:
mount -t ceph 192.168.0.1:/ /mnt/mycephfs
新旧格式的自动降级与回退
do_mount() 的执行流程揭示了一个重要细节:当使用新格式挂载失败(返回 -EINVAL)且内核支持时,mount.ceph 会自动回退到旧格式再次尝试——这主要是为了捕捉内核中新语法(v2)实现的 bug,常见于 teuthology 测试。该行为可由 nofallback 选项关闭(对应源码中 should_fallback() 函数,见 mount.ceph.c),测试框架 qa/tasks/cephfs/kernel_mount.py 中即使用 nofallback 来确保只验证新语法路径。
工作原理:配置自动发现与密钥获取
mount.ceph 的一个核心能力是"少填参数也能挂载"。其自动发现机制分为两大部分。
通过配置文件与 DNS 发现 Monitor 地址
如果命令行没有给出 mon_addr,mount.ceph 会尝试通过本地配置文件(ceph.conf)和/或 DNS SRV 记录确定 Monitor 地址。若集群开启了 CephX 认证,且命令行未提供 secret/secretfile,辅助程序会派生(fork)一个子进程,用标准 Ceph 库例程查找 keyring 并从中取得密钥——同时还能补全 Monitor 地址和 FSID。
这一"fork 子进程 + 降权 + 共享内存回传"的实现细节非常值得关注,对应 fetch_config_info() 函数:
- 父进程通过
mmap创建匿名共享内存; fork()出子进程,子进程调用drop_capabilities()放弃除CAP_DAC_READ_SEARCH之外的全部能力(drop_capabilities()),因为解析配置文件对特权程序而言存在安全风险;- 子进程调用 mount_ceph_get_config_info() 完成实际读取:
- 用
--name client.<用户名>初始化 CephContext(可经--conf指定配置文件); - 通过
MonClient::build_initial_monmap()构建初始 monitor map; - 根据
v2_addrs标志过滤 Monitor 地址——ms_mode=legacy时只保留 v1(legacy)地址,其余模式只保留 v2(msgr2)地址(源码中is_msgr2()/is_legacy()判断,见 conf.cc); - 从
fsid配置项读取集群 FSID; - 通过
KeyRing::from_ceph_context()加载 keyring,取出对应用户的密钥并做 base64 编码;
- 用
- 子进程退出后,父进程从共享内存中把 secret、monitor 地址、fsid 拷贝回挂载信息结构体
struct ceph_mount_info(缓冲区上限见 mount.ceph.h:Monitor 列表MON_LIST_BUFSIZE为 2KB,FSID 固定 37 字节)。
密钥的两种传递通道
获取到 secret 后,append_key_or_secret_option() 函数决定如何把密钥交给内核:
- 优先调用
set_kernel_secret()把密钥写入内核的cephkey type(key=选项只传用户名),避免密钥出现在挂载选项里; - 若内核过老(返回
-ENODEV或-ENOSYS),则回退为在选项字符串中直接附带secret=<base64>。
此外,挂载前还会调用 modprobe() 尝试加载 ceph 内核模块(modprobe()),失败不会中止流程。
基础挂载选项详解
以下选项全部对应手册 Options 节的 Basic 部分,并可在 parse_options() 函数中找到对应的解析逻辑。
| 选项 | 类型/取值 | 默认值 | 说明 |
|---|---|---|---|
conf |
路径 | 标准搜索路径 | 指定 ceph.conf 文件路径,用于初始化 Ceph context 以自动发现 Monitor 地址与认证密钥。未指定时使用 ceph.conf 的标准搜索路径。源码中该值被 strdup 保存到 cmi_conf,随后传给 fetch_config_info() |
mount_timeout |
int(秒) | 60 | 挂载超时时间。对应客户端侧的 client_mount_timeout 配置(见 src/client/Client.cc 的读取逻辑) |
ms_mode |
legacy / crc / secure / prefer-crc / prefer-secure |
prefer-crc(新语法下由源码 CEPH_DEFAULT_V2_MS_MODE 指定,见 mount.ceph.c) |
设置客户端传输连接模式,详见下表 |
mon_addr |
ip_address[:port] |
自动发现 | 集群 Monitor 地址。多个地址用 / 分隔;端口缺省为 6789 |
fsid |
UUID | 自动发现 | 集群 FSID,可用 ceph fsid 命令查询 |
secret |
base64 密钥 | — | CephX 密钥。不安全:会暴露在命令行(进程列表、shell 历史)中,优先使用 secretfile |
secretfile |
文件路径 | — | 包含 CephX 密钥的文件路径。建议权限设为 600。源码中通过 read_secret_from_file() 读取(mount.ceph.c) |
recover_session |
no / clean |
no |
客户端被 blocklist 时的自动重连模式,详见下文 |
fs |
字符串 | — | 旧语法下指定要挂载的非默认文件系统。解析时被转换为 mds_namespace(mount.ceph.c) |
mds_namespace |
字符串 | — | fs= 的同义词(已废弃) |
ms_mode 的五种连接模式
ms_mode 决定客户端与集群的 Messenger 传输协议(对应手册说明):
legacy:使用 Messenger v1 协议与集群通信;crc:使用 Messenger v2 协议,但不对线上数据进行加密(仅校验和);secure:使用 Messenger v2 协议,并对线上数据进行加密;prefer-crc:优先crc模式,若被拒绝则协商为secure模式;prefer-secure:优先secure模式,若被拒绝则协商为crc模式。
源码中 ms_mode 的解析会同时影响地址类型选择:只有 legacy 模式需要 v1 地址,其余模式均使用 v2(msgr2)地址(mount.ceph.c)。
recover_session:被 blocklist 后的自愈策略
CephFS 维护"一致性缓存",当客户端与集群网络长时间中断时,MDS 会强制驱逐(evict)并将客户端加入 blocklist(黑名单)。内核客户端此时无法安全写回脏(缓冲)数据,导致数据丢失——这是符合 POSIX 语义的预期行为,默认(no)下客户端需要重新挂载才能再次访问文件系统(详见 CephFS 故障排查文档 中关于 Disconnected+Remounted FS 的讨论)。
recover_session=clean 改变了这一行为:客户端检测到自己被 blocklist 后自动重连集群。重连过程中,客户端会丢弃脏数据/元数据、使页缓存和可写文件句柄失效。重连后文件锁变为 stale(过期),因为 MDS 已丢失这些锁的跟踪信息;如果某个 inode 含有 stale 文件锁,在应用程序释放全部 stale 文件锁之前,该 inode 的读写不被允许。
Monitor 地址的多种指定方式
mon_addr 接受 ip_address[:port] 形式。端口未指定时默认使用 Ceph 默认端口 6789。多个 Monitor 地址用斜杠 / 分隔,例如:
-o mon_addr=192.168.0.1:6789/192.168.0.2:6789
只需一个 Monitor 即可成功挂载——客户端会从任意响应的 Monitor 处学习到全部 Monitor 信息。但建议指定多个地址,以防挂载时恰好某个 Monitor 处于宕机状态。
有趣的是,源码中地址列表的内部表示使用逗号 , 分隔,仅在传给内核时转换为 /:mon_addr_as_resolve_param()、resolved_mon_addr_as_mount_opt() 与 resolved_mon_addr_as_mount_dev() 三个函数在逗号与斜杠之间来回转换(见 mount.ceph.c)。
高级挂载选项详解
以下选项对应手册 Options 节的 Advanced 部分。它们大多在 mount.ceph 中被原样"透传"给内核(源码中未识别的选项走 else 分支 skip = false,见 parse_options()),由内核 Ceph 客户端实现其语义。
缓存、预读与 I/O 大小
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
cap_release_safety |
int | 计算得出 | cap 释放安全系数 |
caps_wanted_delay_max |
int | 60 | cap 释放延迟上限(秒) |
caps_wanted_delay_min |
int | 5 | cap 释放延迟下限(秒) |
osdkeepalive |
int | 5 | 与 OSD 的 keepalive 间隔 |
osd_idle_ttl |
int(秒) | 60 | OSD 空闲判定 TTL |
rasize |
int(字节) | 8388608(8192×1024) | 最大预读(readahead)大小 |
rsize |
int(字节) | 16777216(16×1024×1024) | 最大读大小 |
wsize |
int(字节) | 16777216(16×1024×1024) | 最大写大小;writeback 使用 wsize 与 stripe unit 中的较小值 |
write_congestion_kb |
int(KB) | 根据可用内存计算 | 在途最大 writeback 量,随可用内存缩放 |
readdir_max_bytes |
int | 524288(512×1024) | 单次 readdir 最大字节数 |
readdir_max_entries |
int | 1024 | 单次 readdir 最大条目数 |
目录统计与快照目录
| 选项 | 默认值 | 说明 |
|---|---|---|
dirstat |
关闭 | 允许通过 cat 目录名 报告目录的文件统计信息。注意这些统计是惰性更新的,目录变更后可能在一段时间内过时 |
nodirstat |
— | 禁用上述目录统计报告 |
rbytes |
关闭 | 对目录将递归大小作为 st_size 报告。可能迷惑 rsync 等程序 |
norbytes |
— | 禁用递归大小报告 |
snapdirname |
.snap |
设置隐藏快照目录的名称 |
命名空间操作同步性
| 选项 | 说明 |
|---|---|
wsync |
所有命名空间操作同步执行,即命名空间操作只有收到 MDS 的回复后才算完成 |
nowsync |
允许客户端异步执行命名空间操作。启用后,若客户端拥有足够 capability,命名空间操作可能在 MDS 回复前即完成。自内核 5.16 起 nowsync 已是默认行为 |
其他行为控制选项
| 选项 | 说明 |
|---|---|
ip |
指定客户端本机 IP |
noasyncreaddir |
禁用 dcache readdir 异步读目录 |
nocrc |
写入时不做数据 CRC 校验 |
noshare |
创建新的客户端实例,而不是共享一个挂载同一集群的已有客户端实例 |
nofallback |
新语法挂载失败时禁止回退到旧语法(源码专用开关,见 should_fallback()) |
ro / rw、nosuid/suid、dev/nodev、noexec/exec、sync、remount、mandlock、noatime、nodiratime、relatime、strictatime 等 |
标准挂载标志,在 parse_options() 中被映射为对应的 MS_* 标志位传给 mount(2) |
crush_location:声明客户端在 CRUSH 层次中的位置
crush_location=x 用于指定客户端在 CRUSH 层次结构中的位置(内核 5.8 起支持)。其格式为一组 key:value 键值对,键值对之间用 | 分隔。注意 | 在 shell 中是管道符,通常需要引号包裹或转义。键是 bucket 类型名(如默认 bucket 类型中的 rack、datacenter、region),值是 bucket 名称。例如:
mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o 'crush_location=rack:myrack|datacenter:mydc|region:myregion'
每个键值对是独立匹配的:"myrack" 不必位于 "mydc" 中,"mydc" 也不必位于 "myregion" 中。该位置不是到层次根部的路径,而是一组独立匹配的节点。还支持"多路径"位置,可为多个并行层次声明局部性:
mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o 'crush_location=rack:myrack1|rack:myrack2|datacenter:mydc'
crush_location 是 read_from_replica=localize 模式计算局部性的依据。
read_from_replica:副本读策略
read_from_replica=<no|balance|localize> 控制读请求的 OSD 选择策略(详细语义见手册):
no(自 5.8 起默认):禁用副本读,始终选择主 OSD;balance:对于副本池,从 PG 的 acting set 中随机挑选一个 OSD 服务读请求;对于纠删码池,挑选存储数据的 shard(相比经由主 OSD 路由可带来性能提升,但需要 Umbrella 服务器与客户端支持,内核客户端支持计划在后续版本中提供);localize:对于副本池,挑选距离客户端"最近"的 OSD 服务读请求。局部性度量基于crush_location给出的客户端位置计算,bucket 类型值最小的匹配胜出——例如,匹配到同 rack 的 OSD 比匹配到同 datacenter 的 OSD 更近,后者又比匹配到同 region 的更近。
balance 与 localize 仅在 Octopus 及之后版本(即执行过 ceph osd require-osd-release octopus)中对一般用途安全;否则应仅用于快照等只读负载。
实战示例:从基础到进阶
以下示例全部源自手册 Examples 节,均可直接复制使用。在动手前先创建挂载点:
mkdir /mnt/mycephfs
1. 挂载整个文件系统
mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs
这里省略了 FSID 与 Monitor 地址——mount.ceph 会从本地 ceph.conf 和 keyring 自动发现(前提是客户端主机上存在相应配置与密钥文件)。
2. 只挂载命名空间的一部分
mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs
设备字符串 = 之后的绝对路径即为要挂载的 CephFS 子目录。
3. 显式指定 Monitor IP
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1
4. 指定非标准端口
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000
5. 多 Monitor 地址
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1/192.168.0.2/192.168.0.3
6. 直接传入 CephX 密钥(不推荐)
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
该方式会把密钥留在 shell 命令历史中,不推荐用于生产环境。
7. 通过密钥文件传入(推荐)
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secretfile=/etc/ceph/fs_username.secret
密钥文件权限应设置为 600,避免其他用户读取。
8. 集群未启用认证
若集群禁用了 CephX 认证,省略所有凭据相关选项即可:
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs
9. 旧语法挂载
mount -t ceph 192.168.0.1:/ /mnt/mycephfs
旧语法下如需指定用户,可加 -o name=admin;多文件系统集群中挂载非默认 FS 时,旧语法使用 -o fs=cephfs2(或等价的 mds_namespace=cephfs2),详见 Mount CephFS using Kernel Driver。
10. 组合使用:加密传输 + 密钥文件 + 自动重连
mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs \
-o ms_mode=secure,secretfile=/etc/ceph/cephuser.secret,recover_session=clean
命令行选项与调试
mount.ceph 自身支持以下命令行开关(对应 usage() 帮助输出):
| 短选项 | 长选项 | 说明 |
|---|---|---|
-h |
--help |
打印帮助 |
-n |
--no-mtab |
不更新 /etc/mtab |
-v |
--verbose |
详细输出调试信息 |
-f |
--fake |
模拟挂载,不真正执行 mount(fakeflag 置位后 call_mount_system_call() 跳过 mount(2),见 mount.ceph.c) |
-o |
--options |
传递 Ceph 挂载选项(逗号分隔) |
挂载成功后,mount.ceph 还会更新 /etc/mtab 条目(除非指定 -n),对应 update_mtab_entry() 调用。
故障排查与常见错误
mount.ceph 在挂载失败时会输出有针对性的错误信息(见 do_mount() 的 errno 分支):
mount error: ceph filesystem not supported by the system(ENODEV):系统内核不支持 CephFS,需要检查内核版本或加载ceph内核模块;mount error: no mds (Metadata Server) is up. The cluster might be laggy, or you may not be authorized(EHOSTUNREACH):没有可用的 MDS 实例,集群可能处于 laggy 状态,或者客户端未被授权;- 其他错误以
mount error <errno> = <strerror>形式输出。
当怀疑是网络中断导致 MDS 强制驱逐并 blocklist 了客户端时,dmesg 中会出现类似以下序列(摘自 CephFS 故障排查):
ceph: mds0 caps stale
libceph: mds0 socket closed (con state OPEN)
libceph: mds0 session reset
ceph: mds0 closed our session
ceph: mds0 reconnect start
ceph: mds0 reconnect denied
出现 reconnect denied 即表明客户端已被 blocklist。此时默认(recover_session=no)需要重新挂载;如需自动恢复,可提前使用 recover_session=clean 挂载。
若怀疑 mount.ceph 的自动发现有问题,可加 -v 查看其解析、选项组装与挂载尝试的详细日志(mount_ceph_debug() 只在 verboseflag 为真时输出,见 mount.ceph.c)。
特性可用性与内核版本要求
由于内核 CephFS 客户端随 Linux 内核(而非 Ceph 发行包)分发,部分挂载选项有内核版本门槛(对应手册 Feature Availability 节):
recover_session=选项:Linux 主线内核 v5.4 加入;wsync与nowsync选项:v5.7 加入(nowsync自 v5.16 起成为默认行为);crush_location与read_from_replica(balance/localize):自内核 5.8 起支持。
较老的内核可能包含有缺陷的 Ceph 客户端,或无法支持较新 Ceph 集群的特性。作为粗略参考,Ceph 10.x(Jewel)时期建议至少使用 4.x 内核;若必须使用更老的内核,建议改用 FUSE 客户端(ceph-fuse)而非内核客户端。使用发行版自带内核时,兼容性维护责任在发行商一方,建议与厂商确认。
相关文档
- mount.ceph 手册(man 8):本文的权威来源,包含全部选项的完整定义;
- 使用内核驱动挂载 CephFS:面向操作的完整挂载指南,含新/旧语法对照与多文件系统场景;
- CephFS 故障排查:blocklist、断连重挂载与常见错误分析;
- ceph-fuse(man 8) 与 ceph(man 8):FUSE 挂载方式与 Ceph 管理命令参考;
- 实现源码:src/mount/mount.ceph.c、src/mount/conf.cc、src/mount/mount.ceph.h;
- 测试参考:qa/tasks/cephfs/kernel_mount.py(新旧语法挂载与
nofallback测试逻辑)、qa/tasks/vstart_runner.py(vstart 环境下直接调用mount.ceph的挂载封装)。