wiki/存储/Ceph/知识库/15-命令速查手册.md

基于 Ceph 官方文档整理 | 文档版本：Tentacle v20.2.4 | 抓取日期：2026-09-17 | 源文：ceph/ceph@v20.2.4 doc/man/8/ 官网入口：https://docs.ceph.com/en/tentacle/man/8/

第 15 册 · Ceph 命令速查手册

本册导读

本册是速查型分册，不讲解原理，只回答一个问题："我要做什么 → 用哪个命令、怎么敲"。

全文覆盖 doc/man/8/ 下的 36 个命令，按主题分为 8 组：集群与通用、密钥与认证、MON/OSD 工具、RADOS、RBD、CephFS、RGW、ceph-volume。每个命令一节，含：用途一句话 → 语法 → 常用选项表 → 可拷贝的示例 → 注意事项/常见坑 → 来源链接。

总速查表：我要做什么 → 用哪个命令

我要做什么	命令	一句话用法
看集群健康/状态	ceph	ceph -s / ceph health detail / ceph status
看容量使用	ceph / rados	ceph df detail / rados df
看 OSD 状态与树	ceph	ceph osd tree / ceph osd df tree / ceph osd stat
看 PG 状态/卡住的 PG	ceph	ceph pg stat / ceph pg dump_stuck inactive
创建/删除/改池	ceph	ceph osd pool create <pool> <pg_num>
调整池的 size / pg_num	ceph	ceph osd pool set <pool> size 3
在线改配置	ceph	ceph config set <who> <option> <value>
只读配置文件里的值（离线）	ceph-conf	ceph-conf --name osd.0 --lookup "osd data"
创建/查看/改 keyring	ceph-authtool	ceph-authtool -C -n client.foo --gen-key keyring
管理集群内的认证实体	ceph	ceph auth get-or-create client.foo mon 'allow r'
查 monmap / 改 monmap	monmaptool	monmaptool --print monmap
导出/编辑/导入 CRUSH map	crushtool	crushtool -d crushmap -o map.txt
从 osdmap 取/灌 CRUSH map	osdmaptool	osdmaptool osdmap --export-crush cm.txt
模拟 upmap 均衡	osdmaptool	osdmaptool osdmap --upmap upmaps.out --upmap-active
评估改 CRUSH 的影响	crushdiff	crushdiff compare cm.txt
上传/下载对象	rados	rados -p foo put myobj file / rados -p foo get myobj out
做对象存储性能压测	rados	rados -p foo bench 60 write --no-cleanup
创建/删除/改 RBD 镜像	rbd	rbd create mypool/myimage --size 102400
快照 / 克隆 / 回滚	rbd	rbd snap create ... / rbd clone ... / rbd snap rollback ...
映射/卸载 RBD 块设备	rbd / rbd-nbd	rbd device map mypool/myimage
开机自动映射 RBD	rbdmap	systemctl enable rbdmap.service
挂载 CephFS（内核）	mount.ceph	mount -t ceph user@.fs_name=/ /mnt -o mon_addr=1.2.3.4
挂载 CephFS（FUSE）	ceph-fuse	ceph-fuse -m mon1:6789 /mnt/mycephfs
交互式逛 CephFS	cephfs-shell	cephfs-shell -c ~/.cephfs-shell.conf
建 RGW 用户/密钥	radosgw-admin	radosgw-admin user create --uid=johnny --display-name="johnny rotten"
查/删 RGW bucket	radosgw-admin	radosgw-admin bucket stats --bucket=foo
多站点 realm/zonegroup/zone	radosgw-admin	radosgw-admin realm create --rgw-realm=...
部署 OSD（LVM）	ceph-volume	ceph-volume lvm create --data /dev/sda
看本机磁盘清单	ceph-volume	ceph-volume inventory --format json-pretty
OSD 崩了自动拉起	ceph-run	ceph-run ceph-osd -i 0 -f
生成崩溃调试包	ceph-debugpack	ceph-debugpack debug.tar.gz
上传日志给开发者	ceph-post-file	ceph-post-file -d 'mon log' /var/log/ceph/ceph-mon.*.log
解码二进制结构体排障	ceph-dencoder	ceph-dencoder type object_info_t import /tmp/a decode dump_json
离线翻 RocksDB（omap）	ceph-kvstore-tool	ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 list
查 librados 版本	librados-config	librados-config --version
压测 CephFS（合成负载）	ceph-syn	ceph-syn --syn makedirs 10 5 3

💡 补充：本手册按"使用频率 + 主题"组织。ceph、rbd、radosgw-admin 三个命令子命令极多，已按子命令分组做表，其余命令按命令分节。

---

一、集群与通用

1.1 ceph

用途：Ceph 集群的管理与控制总入口，涵盖 auth / osd / pool / pg / mon / mgr / mds / fs / config / health / status / tell 等全部日常运维动作。

语法（synopsis，保留原文格式）：

ceph auth [ add | caps | del | export | get | get-key | get-or-create | get-or-create-key | import | list | print-key | print_key ] ...
ceph compact
ceph config [ dump | ls | help | get | show | show-with-defaults | set | rm | log | reset | assimilate-conf | generate-minimal-conf ] ...
ceph config-key [ rm | exists | get | ls | dump | set ] ...
ceph daemon <name> | <path> <command> ...
ceph daemonperf <name> | <path> [ interval [ count ] ]
ceph df {detail}
ceph fs [ add_data_pool | authorize | dump | feature ls | flag set | get | ls | lsflags | new | rename | reset | required_client_features add | required_client_features rm | rm | rm_data_pool | set | swap ] ...
ceph fsid
ceph health {detail}
ceph injectargs <injectedargs> [ <injectedargs>... ]
ceph log <logtext> [ <logtext>... ]
ceph mds [ compat | fail | rm | rmfailed | set_state | stat | repaired ] ...
ceph mon [ add | dump | enable_stretch_mode | getmap | remove | stat ] ...
ceph osd [ blocklist | blocked-by | create | new | deep-scrub | df | down | dump | erasure-code-profile | find | getcrushmap | getmap | getmaxosd | in | ls | lspools | map | metadata | ok-to-stop | ok-to-upgrade | out | pause | perf | pg-temp | force-create-pg | primary-affinity | primary-temp | repair | reweight | reweight-by-pg | rm | destroy | purge | safe-to-destroy | scrub | set | setcrushmap | setmaxosd | stat | tree | unpause | unset ] ...
ceph osd crush [ add | add-bucket | create-or-move | dump | get-tunable | link | move | remove | rename-bucket | reweight | reweight-all | reweight-subtree | rm | rule | set | set-tunable | show-tunables | tunables | unlink ] ...
ceph osd pool [ create | delete | get | get-quota | ls | mksnap | rename | rmsnap | set | set-quota | stats ] ...
ceph osd pool application [ disable | enable | get | rm | set ] ...
ceph osd tier [ add | add-cache | cache-mode | remove | remove-overlay | set-overlay ] ...
ceph pg [ debug | deep-scrub | dump | dump_json | dump_pools_json | dump_stuck | getmap | ls | ls-by-osd | ls-by-pool | ls-by-primary | map | repair | scrub | stat ] ...
ceph quorum_status
ceph report { <tags> [ <tags>... ] }
ceph status
ceph sync force {--yes-i-really-mean-it} {--i-know-what-i-am-doing}
ceph tell <name (type.id)> <command> [options...]
ceph tell <pgid> <command> [options...]
ceph version

常用全局选项

选项	参数	默认值	说明
-i infile, --in-file=infile	文件路径	无	指定输入文件，作为 payload 随命令发给 monitor 集群；仅用于特定的 monitor 命令
-o outfile, --out-file=outfile	文件路径	无	把 monitor 返回的 payload 写到文件（如 osd getmap）
--setuser user	用户名/uid	无	给 -o 指定的输出文件设置属主
--setgroup group	组名/gid	无	给 -o 指定的输出文件设置属组
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件，启动时据此确定 monitor 地址
--id CLIENT_ID, --user CLIENT_ID	id	无	认证用的 client id
--name CLIENT_NAME, -n CLIENT_NAME	TYPE.ID	无	认证用的完整 client 名
--cluster CLUSTER	集群名	无	Ceph 集群名
--admin-daemon ADMIN_SOCKET, daemon DAEMON_NAME	socket 路径/守护进程名	无	通过 /var/run/ceph 下的 admin socket 提交 admin-socket 命令
--admin-socket ADMIN_SOCKET_NOPE	—	无	文档原文提示："You probably mean --admin-daemon"
-s, --status	—	无	显示集群状态
-w, --watch	—	无	实时观察默认 cluster 通道的集群变化
-W, --watch-channel	通道名	无	实时观察任意通道（cluster、audit、cephadm，或 * 表示全部）
--watch-debug	—	无	观察 debug 事件
--watch-info	—	无	观察 info 事件
--watch-sec	—	无	观察 security 事件
--watch-warn	—	无	观察 warning 事件
--watch-error	—	无	观察 error 事件
--version, -v	—	无	显示版本
--verbose	—	无	更详细输出
--concise	—	无	更精简输出
-f {json,json-pretty,xml,xml-pretty,plain,yaml}, --format	格式名	无	输出格式。注意：yaml 仅对 orch 命令有效
--daemon-output-file OUTPUT_FILE	文件路径或 :tmp:	无	--format=json|json-pretty 时，把输出流式写到运行守护进程的那台主机上的文件；仅用于 ceph tell
--connect-timeout CLUSTER_TIMEOUT	秒	无	连接集群的超时时间
--no-increasing	—	默认关闭	用于 reweight-by-utilization / test-reweight-by-utilization：即使是低利用率 OSD 也不允许上调权重
--block	—	无	阻塞直到完成（仅 scrub 与 deep-scrub）

子命令分组速查

① 全局状态与信息

子命令	语法	说明
status / -s	ceph status	显示集群状态
health	ceph health {detail}	显示集群健康
df	ceph df {detail}	显示集群剩余空间状态
fsid	ceph fsid	显示集群 FSID/UUID
version	ceph version	显示 mon 守护进程版本
features	ceph features	显示已连接守护进程/客户端的 release 与 feature 分布
report	ceph report {<tags> [<tags>...]}	汇报集群完整状态，可带标题 tag
quorum_status	ceph quorum_status	汇报 monitor quorum 状态
log	ceph log <logtext> [<logtext>...]	把文本写入 monitor 日志
compact	ceph compact	触发 monitor RocksDB 存储 compaction
injectargs	ceph injectargs <injected_args> [<injected_args>...]	向 monitor 注入配置参数
sync force	ceph sync force {--yes-i-really-mean-it} {--i-know-what-i-am-doing}	强制同步

② auth（认证）

子命令	语法	说明
add	ceph auth add [--key-type=<cipher>] <entity> {<caps> [<caps>...]}	从输入文件添加认证信息；无输入则生成随机 key。不输出 key 信息
caps	ceph auth caps <entity> <caps> [<caps>...]	更新 entity 的 caps
del	ceph auth del <entity>	删除 entity 的全部 caps
export	ceph auth export {<entity>}	导出 keyring；不指定 entity 则导出 master keyring
get	ceph auth get <entity>	写出含指定 key 的 keyring 文件
get-key	ceph auth get-key <entity>	显示指定 key
get-or-create	ceph auth get-or-create [--key-type=<cipher>] <entity> {<caps> [<caps>...]}	获取或创建，输出 .ini 格式
get-or-create-key	ceph auth get-or-create-key <entity> {<caps> [<caps>...]}	key 已存在时给定 caps 必须匹配；输出纯文本 key
import	ceph auth import	从输入文件读入 keyring
ls	ceph auth ls	列出认证状态
print-key / print_key	ceph auth print-key <entity>	显示指定 key
rotate	ceph auth rotate [--key-type=<cipher>] <entity>	轮换 key，输出 .ini 格式
dump-keys	ceph --format=json auth dump-keys	导出整个 key 数据库（含 rotating service keys）；格式必须是 json 或 json-pretty
wipe-rotating-service-keys	ceph auth wipe-rotating-service-keys	清除所有 rotating service keys 并强制 mon 刷新。文档明确警告：不理解后果不要执行

说明：上述所有 auth 子命令中，若省略 --key-type，则使用集群的 preferred cipher。

③ config / config-key

子命令	语法	说明
config dump	ceph config dump	导出集群全部配置项
config ls	ceph config ls	列出全部配置项名称
config help	ceph config help <option>	描述指定配置项
config get	ceph config get <who> {<option>}	只显示 monitor 管理的选项
config show	ceph config show {<who>}	显示实际生效的全部配置（含编译默认值、mon 配置库、ceph.conf、运行时覆盖），因此可能与 get 不同
config show-with-defaults	ceph config show {<who>}	显示运行配置 + 编译内置默认值
config set	ceph config set <who> <option> <value> {--force}	设置选项
config rm	ceph config rm <who> <option>	清除选项
config log	ceph config log {<count>}	显示配置变更历史，count 省略时默认 10
config reset	ceph config reset <version>	回退配置到指定历史版本
config assimilate-conf	ceph config assimilate-conf -i <input-config-path> > <output-config-path>	从 stdin 吸收配置，输出最小 conf
config generate-minimal-conf	ceph config generate-minimal-conf > <minimal-config-path>	生成最小 ceph.conf
config-key rm/exists/get/ls/dump/set	ceph config-key <cmd> <key> {<val>}	monitor 提供的通用 k/v 服务，主要给 ceph-mgr 模块存选项

④ mon / mgr

子命令	语法	说明
mon add	ceph mon add <name> <IPaddr[:port]>	新增 monitor
mon dump	ceph mon dump {<int[0-]>}	导出格式化 monmap，可指定 epoch
mon getmap	ceph mon getmap {<int[0-]>}	获取 monmap
mon remove	ceph mon remove <name>	移除 monitor
mon stat	ceph mon stat	monitor 状态摘要
mon set	ceph mon set <name> <value>	设置 monmap 设置项。有效 name：auth_service_cipher、auth_allowed_ciphers、auth_preferred_cipher（取值含义见 monmaptool）
mon enable_stretch_mode	ceph mon enable_stretch_mode <tiebreaker_mon> <new_crush_rule> <dividing_bucket>	启用 stretch mode；PG 要 peer 成功需 min_size 副本在所有（当前为两个）<dividing_bucket> CRUSH bucket 中都 active
mgr dump	ceph mgr dump	导出最新 MgrMap（含 active/standby mgr）
mgr fail	ceph mgr fail <name>	标记某 mgr 失败（若为 active，standby 接管）
mgr module ls	ceph mgr module ls	列出已启用的 mgr 模块
mgr module enable	ceph mgr module enable <module>	启用模块（可用模块见 mgr dump）
mgr module disable	ceph mgr module disable <module>	停用模块
mgr metadata	ceph mgr metadata [name]	报告 mgr 守护进程元数据
mgr versions	ceph mgr versions	统计运行中的守护进程版本数量
mgr count-metadata	ceph mgr count-metadata <field>	统计任意守护进程元数据字段

⑤ osd（OSD 与 CRUSH）

子命令	语法	说明
osd stat	ceph osd stat	OSD map 摘要
osd dump	ceph osd dump {<int[0-]>}	OSD map 摘要（可指定 epoch）
osd tree	ceph osd tree {<int[0-]>}	打印 OSD 树
osd df	ceph osd df {plain|tree}	OSD 利用率
osd ls	ceph osd ls {<int[0-]>}	列出所有 OSD id
osd lspools	ceph osd lspools {<int>}	列出池
osd find	ceph osd find <int[0-]>	在 CRUSH map 中定位某 OSD
osd metadata	ceph osd metadata {int[0-]}（默认全部）	获取 OSD 元数据
osd perf	ceph osd perf	OSD perf 统计摘要
osd in / osd out	ceph osd in|out <ids> [<ids>...]	把 OSD 置为 in / out
osd down	ceph osd down <ids> [<ids>...]	把 OSD 置为 down
osd blocked-by	ceph osd blocked-by	打印哪些 OSD 正在阻塞对端的直方图
osd scrub / deep-scrub / repair	ceph osd scrub|deep-scrub|repair <who>	发起 scrub / deep-scrub / repair
osd reweight	osd reweight <int[0-]> <float[0.0-1.0]>	调整 reweight，范围 0.0 < weight < 1.0
osd reweight-by-pg	ceph osd reweight-by-pg {<int[100-]>} {<poolname> [<poolname...]} {--no-increasing}	按 PG 分布重算权重，默认过载判定阈值 120
osd reweight-by-utilization	ceph osd reweight-by-utilization {<int[100-]> {<float[0.0-]> {<int[0-]>}}} {--no-increasing}	按利用率重算；默认：过载阈值 120、最大权重变化 0.05、最多调 4 个 OSD
osd primary-affinity	ceph osd primary-affinity <osdname (id|osd.id)> <float[0.0-1.0]>	调整 primary-affinity
osd pg-temp	ceph osd pg-temp <pgid> {<id> [<id>...]}	设置 pg_temp 映射（开发者）
osd primary-temp	ceph osd primary-temp <pgid> <id>	设置 primary_temp（开发者）
osd force-create-pg	ceph osd force-create-pg <pgid>	强制创建 PG
osd pause / unpause	ceph osd pause / ceph osd unpause	暂停 / 恢复 OSD
osd set	ceph osd set pause|noup|nodown|noout|noin|nobackfill|norebalance|norecover|noscrub|nodeep-scrub|notieragent	设置集群级 flag
osd unset	ceph osd unset pause|noup|nodown|noout|noin|nobackfill|norebalance|norecover|noscrub|nodeep-scrub|notieragent	取消集群级 flag
osd create	ceph osd create {<uuid>} {<id>}	自 Luminous 起已 DEPRECATED，将来会移除；请改用 osd new
osd new	ceph osd new {<uuid>} {<id>} -i {<params.json>}	创建新 OSD 或按指定 id 重建；JSON 内可含 cephx_secret、cephx_lockbox_secret、dmcrypt_key、crush_device_class
osd rm	ceph osd rm <ids> [<ids>...]	从 OSD map 移除
osd destroy	ceph osd destroy <id> {--yes-i-really-mean-it}	标记 destroyed，删除其 CephX key 与 dm-crypt / daemon-private config key；不会从 crush 或 osdmap 移除。前提：OSD 必须先被标记 lost
osd purge	ceph osd purge <id> {--yes-i-really-mean-it}	等价于 osd destroy + osd rm + osd crush remove
osd lost	ceph osd lost <int[0-]> {--yes-i-really-mean-it}	标记 OSD 永久丢失。文档原警告：若无其他副本则销毁数据
osd safe-to-destroy	ceph osd safe-to-destroy <id> [<ids>...]	判断删除/销毁是否安全（成功码=安全，否则报错码+信息）
osd ok-to-stop	ceph osd ok-to-stop <id> [<ids>...] [--max <num>]	判断这批 OSD 能否同时停而不影响可用性；--max 时额外从 CRUSH 相邻位置补齐可停 OSD
osd ok-to-upgrade	ceph osd ok-to-upgrade <crush_bucket_name> <new_ceph_version_short> [--max <num>]	找出某 CRUSH bucket 内可同时安全升级的 OSD 集合；bucket 类型只能是 rack/chassis/host/osd
osd setmaxosd	ceph osd setmaxosd <int[0-]>	设置新的最大 OSD 值
osd getmaxosd	ceph osd getmaxosd	显示最大 OSD id
osd getmap	ceph osd getmap {<int[0-]>}	获取 OSD map
osd getcrushmap	ceph osd getcrushmap {<int[0-]>}	获取 CRUSH map
osd setcrushmap	ceph osd setcrushmap	从输入文件设置 CRUSH map
osd set-require-min-compat-client	ceph osd set-require-min-compat-client <version>	强制集群向后兼容指定客户端版本；若有已连接守护进程/客户端不兼容则失败
osd erasure-code-profile get/ls/rm/set	ceph osd erasure-code-profile set <name> {<profile> [<profile>...]}	管理 EC profile；set 末尾加 --force 可覆盖已有 profile（有风险）
osd blocklist add	ceph osd blocklist add <EntityAddr> {<float[0.0-]>}	加入 blocklist，可指定过期秒数
osd blocklist ls / rm	ceph osd blocklist ls / ceph osd blocklist rm <EntityAddr>	查看 / 移除 blocklist

⑥ osd crush（CRUSH 管理）

子命令	语法	说明
crush add	ceph osd crush add <osdname (id|osd.id)> <float[0.0-]> <args> [<args>...]	添加/更新 crushmap 位置与权重
crush add-bucket	ceph osd crush add-bucket <name> <type>	添加无父（通常是 root）bucket
crush create-or-move	ceph osd crush create-or-move <osdname (id|osd.id)> <float[0.0-]> <args> [<args>...]	创建或移动条目
crush dump	ceph osd crush dump	导出 crush map
crush get-tunable	ceph osd crush get-tunable straw_calc_version	获取 tunable（仅 straw_calc_version）
crush set-tunable	ceph osd crush set-tunable straw_calc_version <value>	设置 tunable（仅 straw_calc_version）
crush show-tunables	ceph osd crush show-tunables	显示当前 tunables
crush tunables	ceph osd crush tunables legacy|argonaut|bobtail|firefly|hammer|optimal|default	一次性把 tunables 设为某 profile
crush link / unlink	ceph osd crush link|unlink <name> <args> [<args>...]	在指定位置挂接 / 摘除条目
crush move	ceph osd crush move <name> <args> [<args>...]	移动条目
crush remove / rm	ceph osd crush remove|rm <name> {<ancestor>}	从 crush map 移除（全局或仅某祖先下）
crush rename-bucket	ceph osd crush rename-bucket <srcname> <dstname>	重命名 bucket
crush reweight	ceph osd crush reweight <name> <float[0.0-]>	改权重
crush reweight-all	ceph osd crush reweight-all	重算整树权重使其求和正确
crush reweight-subtree	ceph osd crush reweight-subtree <name> <weight>	改某 name 下所有叶子权重
crush tree	ceph osd crush tree	树形展示 bucket 与 item
crush set	ceph osd crush set（单独使用：从输入文件设置 crush map） ceph osd crush set <osdname (id|osd.id)> <float[0.0-]> <args> [<args>...]	见左
crush rule create-erasure	ceph osd crush rule create-erasure <name> {<profile>}	为 EC 池创建规则（profile 默认 default）
crush rule create-simple	ceph osd crush rule create-simple <name> <root> <type> {firstn|indep}	创建简单规则；默认 firstn，EC 池推荐 indep
crush rule dump	ceph osd crush rule dump {<name>}（默认全部）	导出规则
crush rule ls / rm	ceph osd crush rule ls / ceph osd crush rule rm <name>	列出 / 删除规则

⑦ osd pool（存储池）

子命令	语法	说明
pool create	ceph osd pool create <poolname> {<int[0-]>} {<int[0-]>} {replicated|erasure} {<erasure_code_profile>} {<rule>} {<int>} {--autoscale-mode=<on,off,warn>}	创建池
pool delete	ceph osd pool delete <poolname> {<poolname>} {--yes-i-really-really-mean-it}	删除池
pool ls	ceph osd pool ls {detail}	列出池
pool rename	ceph osd pool rename <poolname> <poolname>	重命名
pool get	ceph osd pool get <poolname> size|min_size|pg_num|pgp_num|crush_rule|write_fadvise_dontneed	取池参数；另有 tier 专用项、EC 专用 erasure_code_profile；all 取全部适用参数
pool set	ceph osd pool set <poolname> size|min_size|pg_num|pgp_num|crush_rule|hashpspool|nodelete|nopgchange|nosizechange|hit_set_type|hit_set_period|hit_set_count|hit_set_fpp|debug_fake_ec_pool|target_max_bytes|target_max_objects|cache_target_dirty_ratio|cache_target_dirty_high_ratio|cache_target_full_ratio|cache_min_flush_age|cache_min_evict_age|min_read_recency_for_promote|write_fadvise_dontneed|hit_set_grade_decay_rate|hit_set_search_last_n <val> {--yes-i-really-mean-it}	设置池参数
pool get-quota	ceph osd pool get-quota <poolname>	取对象/字节限额
pool set-quota	ceph osd pool set-quota <poolname> max_objects|max_bytes <val>	设置限额
pool stats	ceph osd pool stats {<name>}	池统计
pool mksnap / rmsnap	ceph osd pool mksnap|rmsnap <poolname> <snap>	创建 / 删除池快照
pool application enable	ceph osd pool application enable <pool-name> <app> {--yes-i-really-mean-it}	给池打应用注解（rgw/rbd/cephfs）
pool application disable	ceph osd pool application disable <pool-name> <app> {--yes-i-really-mean-it}	取消注解
pool application get	ceph osd pool application get {<pool-name>} {<app>} {<key>}	查注解（都不传则显示全部池全部应用的键值）
pool application set / rm	ceph osd pool application set <pool-name> <app> <key> <value> / ... rm <pool-name> <app> <key>	设置 / 删除键值

⑧ osd tier（分层）

子命令	语法	说明
tier add	ceph osd tier add <poolname> <poolname> {--force-nonempty}	把第二个池作为 tier 加到第一个（base）池
tier add-cache	ceph osd tier add-cache <poolname> <poolname> <int[0-]>	添加指定大小的 cache tier
tier cache-mode	ceph osd tier cache-mode <poolname> writeback|proxy|readproxy|readonly|none	设置 cache 模式
tier remove	ceph osd tier remove <poolname> <poolname>	移除 tier
tier set-overlay	ceph osd tier set-overlay <poolname> <poolname>	设置 overlay 池
tier remove-overlay	ceph osd tier remove-overlay <poolname>	移除 overlay 池

⑨ pg（放置组）

子命令	语法	说明
pg stat	ceph pg stat	PG 状态
pg dump	ceph pg dump {all|summary|sum|delta|pools|osds|pgs|pgs_brief} [...]	人类可读的 pg map（只有 all 可与 plain 同用）
pg dump_json	ceph pg dump_json {all|summary|sum|delta|pools|osds|pgs|pgs_brief} [...]	JSON 版
pg dump_pools_json	ceph pg dump_pools_json	仅池信息，JSON
pg dump_stuck	ceph pg dump_stuck {inactive|unclean|stale|undersized|degraded [...]} {<int>}	卡住的 PG
pg ls	ceph pg ls {<int>} {<pg-state> [<pg-state>...]}	按池/OSD/状态列出 PG
pg ls-by-osd	ceph pg ls-by-osd <osdname (id|osd.id)> {<int>} {<pg-state>...}	按 OSD 列
pg ls-by-pool	ceph pg ls-by-pool <poolstr> {<int>} {<pg-state>...}	按池列
pg ls-by-primary	ceph pg ls-by-primary <osdname (id|osd.id)> {<int>} {<pg-state>...}	按 primary OSD 列
pg map	ceph pg map <pgid>	显示 PG→OSD 映射
pg scrub / deep-scrub / repair	ceph pg scrub|deep-scrub|repair <pgid>	发起 scrub / deep-scrub / repair
pg debug	ceph pg debug unfound_objects_exist|degraded_pgs_exist	PG 调试信息
pg getmap	ceph pg getmap	获取二进制 pg map 到 -o/stdout
tell <pgid> scrub	ceph tell <pgid> scrub	向该 PG 当前 primary OSD 发命令
tell <pgid> deep-scrub	ceph tell <pgid> deep-scrub	同上，deep-scrub
tell <pgid> scrub-abort	ceph tell <pgid> scrub-abort	中止进行中的 scrub，并清除之前的 scrub/deep-scrub 操作请求

⑩ fs / mds（CephFS 管理）

子命令	语法	说明
fs ls	ceph fs ls	列出文件系统
fs new	ceph fs new <fs_name> <metadata> <data>	用指定元数据池/数据池创建 FS
fs get	ceph fs get <fs-name>	显示 FS 信息（设置 + ranks），是 fs dump 的子集
fs dump	ceph fs dump [epoch]	显示指定 epoch（默认当前）的 FSMap
fs set	ceph fs set <fs-name> <fs-setting> <value>	设置 FS 参数
fs rm	ceph fs rm <fs_name> {--yes-i-really-mean-it}	停用（删除）文件系统
fs rename	ceph fs rename <fs-name> <new-fs-name> {--yes-i-really-mean-it}	重命名，并同步更新池上的 application tag
fs swap	ceph fs swap <fs1-name> <fs1-id> <fs2-name> <fs2-id> [--swap-fscids] {--yes-i-really-meant-it}	交换两个 FS 的名字（可选同时交换 FSID）
fs reset	ceph fs reset <fs_name> {--yes-i-really-mean-it}	仅用于灾难恢复：重置为单 MDS map
fs add_data_pool	ceph fs add_data_pool <fs-name> <pool name/id>	添加数据池
fs rm_data_pool	ceph fs rm_data_pool <fs-name> <pool name/id>	移除数据池（该池上文件数据将不可用；默认数据池不可移除）
fs authorize	ceph fs authorize [--key-type=<cipher>] <fs_name> client.<client_id> <path> <perms> [<path> <perms>...]	给某路径授权客户端，<perms> 可为 r/rw/rwp
fs flag set	ceph fs flag set <flag-name> <flag-val> --yes-i-really-mean-it	设置全局 CephFS flag（目前只有 enable_multiple）
fs lsflags	ceph fs lsflags <fs-name>	显示 FS 上所有 flag
fs feature ls	ceph fs feature ls	列出当前版本支持的所有 CephFS 特性
fs required_client_features add/rm	ceph fs required_client_features <fs name> add|rm <feature-name>	增删客户端必备特性要求
mds stat	ceph mds stat	MDS 状态
mds fail	ceph mds fail <role|gid>	强制 MDS 进入 fail 状态
mds rm	ceph mds rm <int[0-]> <name> (type.id)>	移除非活跃 MDS
mds rmfailed	ceph mds rmfailed <int[0-]>	移除已失败的 MDS
mds set_state	ceph mds set_state <int[0-]> <int[0-20]>	设置 MDS 状态为数值状态
mds repaired	ceph mds repaired <role>	把损坏的 MDS rank 标记为已修复
mds compat show	ceph mds compat show	显示 MDS 兼容性设置
mds compat rm_compat / rm_incompat	ceph mds compat rm_compat|rm_incompat <int[0-]>	移除兼容/不兼容特性

⑪ daemon / daemonperf / tell / quorum / heap

子命令	语法	说明
daemon	ceph daemon {daemon_name|socket_path} {command} ...	通过 admin socket 提交命令
daemonperf	ceph daemonperf {daemon_name|socket_path} [{interval} [{count}]]	实时观察某守护进程的性能计数器
tell	ceph tell <name (type.id)> <command> [options...]	向指定守护进程发命令
tell help	ceph tell <name (type.id)> help	列出该守护进程所有可用命令
quorum	ceph tell mon.<id> quorum enter|exit	让指定 MON 进入/退出 quorum
heap	ceph tell <name (type.id)> heap dump|start_profiler|stop_profiler|stats	显示堆使用信息（仅在使用 tcmalloc 编译时可用）
heap release	ceph tell <name (type.id)> heap release	让 TCMalloc 立即把不再使用的内存归还内核
heap get_release_rate / set_release_rate	ceph tell <name (type.id)> heap get_release_rate|set_release_rate {<val>}	获取/设置 TCMalloc 内存释放速率；0=永不归还，1=每归还 1 页后等 1000 页；默认 1.0

典型示例

# 集群概览
ceph -s
ceph health detail
ceph df detail
ceph fsid
ceph version
ceph features

# 实时观察
ceph -w                      # 观察 cluster 通道
ceph -W cephadm              # 观察 cephadm 通道
ceph --watch-warn            # 只看 warning 事件

# 认证
ceph auth get-or-create client.foo mon 'allow r' osd 'allow rw pool=mypool'
ceph auth caps client.foo mon 'allow r' osd 'allow rw pool=mypool'
ceph auth ls
ceph auth print-key client.foo
ceph --format=json auth dump-keys

# 配置
ceph config dump
ceph config get osd.0 osd_memory_target
ceph config set osd osd_memory_target 4294967296
ceph config show osd.0
ceph config log 20
ceph config reset 3
ceph config generate-minimal-conf > /tmp/minimal.conf

# MON / MGR
ceph mon dump
ceph mon add mon4 10.0.0.14:3300
ceph mon enable_stretch_mode mon5 stretch_rule datacenter
ceph mgr module ls
ceph mgr module enable dashboard
ceph mgr fail mon1

# OSD 日常
ceph osd tree
ceph osd df tree
ceph osd perf
ceph osd out 3
ceph osd in 3
ceph osd reweight 3 0.8
ceph osd reweight-by-utilization 120 0.05 4
ceph osd primary-affinity osd.3 0.5
ceph osd scrub 3
ceph osd deep-scrub 3 --block
ceph osd ok-to-stop 3 --max 4
ceph osd safe-to-destroy 3
ceph osd set noout
ceph osd unset noout

# OSD 生命周期
ceph osd new 6d92a3c2-... 5 -i params.json     # JSON 内含 cephx_secret 等
ceph osd lost 5 --yes-i-really-mean-it
ceph osd destroy 5 --yes-i-really-mean-it
ceph osd purge 5 --yes-i-really-mean-it
ceph osd setmaxosd 100

# CRUSH
ceph osd crush add-bucket rack1 rack
ceph osd crush move rack1 root=default
ceph osd crush add osd.3 1.0 host=node1 rack=rack1
ceph osd crush reweight osd.3 0.9
ceph osd crush rule create-simple myrule default host firstn
ceph osd crush rule dump myrule
ceph osd crush tunables optimal
ceph osd getcrushmap -o /tmp/crush.bin
ceph osd setcrushmap -i /tmp/crush.bin

# 池
ceph osd pool create mypool 128 128 replicated --autoscale-mode=on
ceph osd pool ls detail
ceph osd pool set mypool size 3
ceph osd pool set mypool pg_num 256 --yes-i-really-mean-it
ceph osd pool get mypool all
ceph osd pool set-quota mypool max_bytes 100G
ceph osd pool application enable mypool rbd --yes-i-really-mean-it
ceph osd pool stats mypool
ceph osd erasure-code-profile set ec42 k=4 m=2 crush-failure-domain=host
ceph osd pool create ecpool 64 64 erasure ec42

# PG
ceph pg stat
ceph pg dump_stuck inactive unclean stale
ceph pg ls-by-pool mypool
ceph pg map 3.1f
ceph pg repair 3.1f
ceph tell 3.1f scrub-abort

# CephFS / MDS
ceph fs ls
ceph fs new myfs cephfs_metadata cephfs_data
ceph fs authorize myfs client.foo / rw
ceph fs set myfs max_mds 2
ceph mds stat
ceph mds fail 0
ceph mds repaired 0

# 守护进程直连
ceph daemon osd.0 help
ceph daemon osd.0 config show
ceph daemonperf osd.0 1 10
ceph tell osd.0 help
ceph tell mon.a quorum enter

# 输出格式
ceph -f json-pretty status
ceph osd tree --format json

注意事项 / 常见坑

• ceph osd create 自 Luminous 起已废弃，请用 ceph osd new；osd new 的 JSON 参数文件里必须提供 client.osd.<id> 的 base64 CephX key，若指定 dm-crypt 则必须同时给出对应的 lockbox CephX key。
• osd destroy 不会把 OSD 从 crush 或 osdmap 移除，只标记为 destroyed；执行前该 OSD 必须先被标记为 lost。要彻底清理用 osd purge。
• osd lost 在没有其他副本时会销毁数据，文档明确警告。
• ceph osd set full 自 Mimic 起不再被支持；full flag 在 Octopus 已不支持。
• config get 只显示 monitor 管理的选项，config show 显示实际生效值，两者可能不一致，排障时应以 show 为准。
• auth dump-keys 的输出格式必须是 json 或 json-pretty。
• --daemon-output-file 写文件在运行守护进程的那台机器上，通常不是你敲命令的机器。
• -f yaml 只对 orch 命令有效。
• --block 只对 scrub / deep-scrub 有效。
• ceph auth wipe-rotating-service-keys 文档明确要求"充分理解后果后再执行"。
• 未显式指定 --key-type 的 auth 子命令，使用集群 preferred cipher。
• osd ok-to-upgrade 的 CRUSH bucket 类型限制为 rack/chassis/host/osd，这是为避免大故障域带来的性能问题。
• heap 相关命令仅在以 tcmalloc 编译时可用。

💡 补充：本 man 页的 synopsis 中未收录 ceph orch（cephadm 编排）与 ceph telemetry 子命令，仅在全局选项 -f/--format 处提到 yaml 仅对 orch 有效。这两个子命令族已在下方 ⑫ ceph orch 与 ⑬ ceph telemetry 补齐，内容取自官方文档仓库中的 mgr/orchestrator.rst、mgr/telemetry.rst、cephadm/ 相关页面（非本 man 页）。

引自：ceph

⑫ orch（Orchestrator / cephadm 编排）

用途：ceph orch 是 Orchestrator CLI，为 orchestrator 模块（cephadm、rook 等）提供统一的命令行入口，用于声明式地部署/扩容/缩容/删除服务、管理主机与设备、升级集群。

💡 补充：ceph man 页未给出 orch 的 synopsis。下面的 synopsis 由官方文档中出现的各条 ceph orch ... 用法归纳而成，非原文逐字引用。

语法（synopsis）：

ceph orch status [--detail]
ceph orch ls [--service_type <type>] [--service_name <name>] [--export] [--format <f>] [--refresh]
ceph orch ps [--hostname <host>] [--daemon_type <type>] [--service_name <name>] [--daemon_id <id>] [--format <f>] [--refresh]
ceph orch apply <service_type> [<svc_id>] [--placement=<placement>] [--dry-run] [--unmanaged]
ceph orch apply -i <spec.yaml> [--dry-run]
ceph orch rm <service_name> [--force]
ceph orch <start|stop|restart|redeploy|reconfig> <service_name>
ceph orch host ls [--format yaml] [--host-pattern <name>] [--label <label>] [--host-status <status>] [--detail]
ceph orch host add <hostname> [<ip>] [--labels <label>[,<label>...]]
ceph orch host rm <host> [--offline] [--force] [--rm-crush-entry]
ceph orch host drain <host> [--keep-conf-keyring] [--zap-osd-devices]
ceph orch host label add|rm <hostname> <label>
ceph orch host set-addr <hostname> <addr>
ceph orch host maintenance enter|exit <hostname> [--force] [--yes-i-really-mean-it] [--offline]
ceph orch host rescan <hostname> [--with-summary]
ceph orch device ls [--hostname=...] [--wide] [--refresh]
ceph orch device zap <hostname> <path>
ceph orch daemon add <daemon-type> --placement=<placement spec>
ceph orch daemon rm <daemon name>... [--force]
ceph orch daemon <start|stop|restart|redeploy|reconfig> <daemon name>
ceph orch daemon redeploy <daemon name> --image <new-image-name>
ceph orch upgrade start [--image <image-name> | --ceph-version <version>] [--daemon-types <types>] [--hosts <hosts>] [--services <services>] [--limit <n>]
ceph orch upgrade status
ceph orch upgrade stop
ceph orch set backend <module>
ceph orch set-unmanaged|set-managed <service_name>
ceph orch pause
ceph orch resume

术语（Definition of Terms，源文原义）：

术语	含义
host	物理主机的 hostname（不是 DNS 名、pod 名、容器名或容器内 hostname）
service type	服务类型，如 nfs、mds、osd、mon、rgw、mgr、iscsi
service	逻辑服务，通常由分布在多主机上的多个实例组成以实现 HA；mds 用 fs_name 标识，rgw 用 rgw_zone，nfs 用 ganesha_cluster_id
daemon	service 的单个实例（通常是一个守护进程，也可能是 LIO、knfsd 之类的内核服务）

子命令表：

子命令	参数	说明	示例
status	[--detail]	显示当前 orchestrator 模式及其高层状态（插件是否可用/可操作）	ceph orch status
ls	[--service_type <type>] [--service_name <name>] [--export] [--format <f>] [--refresh]	列出 orchestrator 已知的服务；--export 导出为 YAML，可直接喂给 ceph orch apply -i	ceph orch ls --service_name=rgw.foo --export > rgw.yaml
ps	[--hostname <host>] [--daemon_type <type>] [--service_name <name>] [--daemon_id <id>] [--format <f>] [--refresh]	列出所有守护进程（systemd unit）及其状态	ceph orch ps --daemon_type osd --daemon_id 0
apply	<service_type> [<svc_id>] [--placement=<placement>] [--dry-run]	声明式部署/扩容/缩容服务。每条 ceph orch apply <svc> 会覆盖前一条同类型命令	ceph orch apply mds myfs --placement="3 host1 host2 host3"
apply -i	<spec.yaml> [--dry-run]	从 YAML（支持多文档）批量 apply 服务规格	ceph orch apply -i cluster.yaml
apply osd	--all-available-devices [--dry-run] [--unmanaged=true]	用所有可用设备部署 OSD	ceph orch apply osd --all-available-devices --dry-run
rm	<service_name> [--force]	删除服务及其全部守护进程	ceph orch rm rgw.myrgw
start / stop / restart	<service_name>	启停/重启服务。仅对 cephadm 容器化守护进程生效	ceph orch restart rgw.myrgw
redeploy	<service_name>	重建 /var/lib/ceph/<fsid>/<daemon-name> 目录结构（若不存在）、刷新配置、重新生成 unit 文件并重启 systemd 守护进程	ceph orch redeploy grafana
reconfig	<service_name>	刷新配置文件后重启守护进程（假定 daemon 目录已存在）	ceph orch reconfig prometheus
host ls	[--format yaml] [--host-pattern <name>] [--label <label>] [--host-status <status>] [--detail]	列出主机（含 label、status）；--detail 输出更详细信息	ceph orch host ls --detail
host add	<hostname> [<ip>] [--labels <l1>,<l2>]	纳管新主机；建议显式给出主机 IP（否则依赖 DNS 解析）	ceph orch host add host2 10.10.0.102 --labels _admin
host rm	<host> [--offline] [--force] [--rm-crush-entry]	移除主机；--offline --force 用于离线主机（文档警告：可能导致数据丢失）；默认不会移除关联的 CRUSH bucket，需显式 --rm-crush-entry	ceph orch host rm host2
host drain	<host> [--keep-conf-keyring] [--zap-osd-devices]	排空主机：打上 _no_schedule（和 _no_conf_keyring）标签并迁移/移除守护进程；--zap-osd-devices 同时擦除被移除 OSD 的设备	ceph orch host drain host2
host label add / rm	<hostname> <label>	给主机增删标签（配合 placement: label:xxx 使用）	ceph orch host label add host1 rgw
host set-addr	<hostname> <addr>	修改主机地址	ceph orch host set-addr reef1 192.168.160.11
host maintenance enter / exit	<hostname> [--force] [--yes-i-really-mean-it] [--offline]	进入/退出维护模式；enter --force 可绕过安全检查	ceph orch host maintenance enter host1
host rescan	<hostname> [--with-summary]	重新扫描主机设备；--with-summary 给出 HBA 数量等汇总	ceph orch host rescan host1 --with-summary
device ls	[--hostname=...] [--wide] [--refresh]	列出 ceph-volume 发现的磁盘；--wide 额外显示不可用原因（Reef 起有 REJECT REASONS 列）。列会随版本变化	ceph orch device ls --wide
device zap	<hostname> <path>	擦除设备以便重新使用	ceph orch device zap my_hostname /dev/sdx
daemon add	<daemon-type> --placement=<placement spec>	在指定位置手工部署一个守护进程（仅 unmanaged: true 场景，官方标注"用例非常有限"）	ceph orch daemon add osd host1:/dev/sdb
daemon rm	<daemon name>... [--force]	手工移除守护进程；受管服务（unmanaged=False）会在数秒后自动补一个新的	ceph orch daemon rm mgr.my_host.xyzxyz
daemon start/stop/restart/redeploy/reconfig	<daemon name>	对单个守护进程执行动作	ceph orch daemon restart mgr.host1.abcdef
daemon redeploy --image	<daemon name> --image <new-image-name>	用指定镜像重新部署单个守护进程	ceph orch daemon redeploy mgr.example1.abcdef --image quay.io/ceph/ceph:v18
upgrade start	[--image <image-name> | --ceph-version <version>] [--daemon-types <types>] [--hosts <hosts>] [--services <services>] [--limit <n>]	开始集群升级。自 v16.2.6 起 Docker Hub 不再使用，需指向 quay.io 镜像	ceph orch upgrade start --ceph-version 18.2.4
upgrade status	—	查看是否正在升级、目标版本。orchestrator 崩溃时会返回 Error ENOENT: Module not found	ceph orch upgrade status
upgrade stop	—	随时停止升级	ceph orch upgrade stop
set backend	<module>	选择 orchestrator 后端模块；空字符串 "" 表示禁用	ceph orch set backend cephadm
set-unmanaged / set-managed	<service_name>	设 unmanaged: true/false，停用/恢复该服务的自动部署与移除。对特殊的 osd 服务无效（会报 No service of name osd found...）	ceph orch set-unmanaged mon
pause / resume	—	暂停/恢复 cephadm 后台工作。暂停后仍做被动监控（检查主机与守护进程状态），但不做任何变更（不部署/不移除）	ceph orch pause

典型示例：

# 查看编排器状态与已部署服务
ceph orch status
ceph orch ls
ceph orch ps

# 部署监控栈（--placement 支持主机列表 / count / label / host_pattern / 正则）
ceph orch apply prometheus --placement="count:2"
ceph orch apply node-exporter --placement='*'
ceph orch apply grafana

# 部署 RGW / MDS / NFS
ceph orch apply rgw foo --port=8000 --placement="2 host1 host2"
ceph orch apply mds myfs --placement="3 host1 host2 host3"
ceph orch apply nfs foo mypool --placement="host1"

# 用 YAML 规格 apply（推荐做法：避免 apply 互相覆盖）
ceph orch ls --service-name rgw.foo --export > rgw.foo.yaml
ceph orch apply -i rgw.foo.yaml --dry-run
ceph orch apply -i rgw.foo.yaml

# 主机管理
ceph orch host ls
ceph orch host add host3 10.10.0.103
ceph orch host label add host3 mds
ceph orch host drain host3
ceph orch host rm host3 --rm-crush-entry

# 磁盘与 OSD
ceph orch device ls --wide
ceph orch apply osd --all-available-devices --dry-run
ceph orch daemon add osd host1:/dev/sdb

# 服务/守护进程动作
ceph orch restart rgw.foo
ceph orch redeploy prometheus
ceph orch daemon rm mon.oldhost1 --force

# 升级
ceph -s                                     # 先确认集群健康、主机在线
ceph orch upgrade start --ceph-version 18.2.4
ceph orch upgrade start --image quay.io/ceph/ceph:v18.2.4
ceph orch upgrade status
ceph orch upgrade stop

# 暂停 cephadm 后台动作
ceph orch pause
ceph orch resume

注意事项 / 常见坑：

• ceph orch apply <service> 每条都会覆盖同类型的前一条命令。连续执行 ceph orch apply mon host1、host2、host3，最终只有 host3 上有 mon；正确写法是 ceph orch apply mon "host1,host2,host3" 或用 YAML 规格。
• ceph orch ps 默认状态每 10 分钟才刷新一次；可用 ceph config set mgr mgr/cephadm/daemon_cache_timeout 60 缩短，或加 --refresh 立即刷新（大集群会耗时）。
• start/stop/restart/redeploy/reconfig 仅对 cephadm 容器化守护进程生效。
• host rm --offline --force 文档明确警告可能导致数据丢失；且默认不删除 CRUSH bucket，需要 --rm-crush-entry。
• 带 _no_schedule 标签的主机不会被 cephadm 部署守护进程。
• -f yaml 只对 orch 命令有效（这也是 ceph man 页唯一提到 orch 的地方）。
• orchestrator 各后端（Rook / Cephadm）对上述命令的实现程度不同：例如 host maintenance、upgrade 在 Rook 上未实现或不适用，apply prometheus/alertmanager/node-exporter 在 Rook 上不适用。
• orch device ls 的输出列在不同 release 间会变化；Health/Ident/Fault 列依赖 libstoragemgmt 集成，需先 ceph config set mgr mgr/cephadm/device_enhanced_scan true（文档提醒先在硬件上验证兼容性）。

💡 补充：ceph orch sd dump cert、ceph orch cert-store get cert cephadm_root_ca_cert、ceph orch osd ident-on|ident-off|fault-on|fault-off 等命令在官方文档中出现过，但本手册整理时未在稳定章节中给出完整选项说明，具体参数以 ceph orch --help 为准（文档未明确）。

引自：ceph

⑬ telemetry（遥测上报）

用途：telemetry 是 ceph-mgr 模块，把集群的匿名数据发回 Ceph 开发者，用于统计 Ceph 的使用方式与用户遇到的问题。数据公示在公共面板 https://telemetry-public.ceph.com/（可看到上报集群数、总容量、OSD 数量、版本分布趋势等）。

💡 补充：ceph man 页未收录 telemetry。下面的 synopsis 由 mgr/telemetry.rst 中出现的命令归纳而成，非 man 页原文。

语法（synopsis）：

ceph telemetry on [--license sharing-1-0]
ceph telemetry off
ceph telemetry status
ceph telemetry show [<channel_name>]
ceph telemetry show-device
ceph telemetry show-all
ceph telemetry preview [<channel_name>]
ceph telemetry preview-device
ceph telemetry preview-all
ceph telemetry channel ls
ceph telemetry enable channel <channel_name> [<channel_name>...] | all
ceph telemetry disable channel <channel_name> [<channel_name>...] | all
ceph telemetry collection ls
ceph telemetry diff
ceph telemetry send [--license sharing-1-0]

上报什么（Channels）：遥测报告按"通道（channel）"拆分，telemetry 开启时各通道可单独开关；telemetry 关闭时每通道设置不生效。

通道	默认值	上报内容
basic	on	集群基本信息：容量；mon/mgr/osd/mds/rgw 等守护进程数量；当前软件版本；RADOS 池与 CephFS 的数量和类型；被改动过的配置项名称（不含取值）
crash	on	守护进程崩溃信息：守护进程类型、版本、操作系统（发行版、内核版本）、stack trace（定位崩溃发生在 Ceph 代码何处）
device	on	设备指标：匿名化后的 SMART 指标
ident	off	用户主动提供的集群标识信息：集群描述、联系邮箱
perf	off	集群性能指标：整体健康、负载模式、延迟/限流/内存等问题的排查、按守护进程的性能监控

• 上报数据不含任何敏感数据：不含 pool 名、object 名、object 内容、hostname、设备序列号。
• 数据通过 HTTPS 发往 https://telemetry.ceph.com。
• 设备报告单独生成：hostname 与设备序列号会被匿名化，发往不同的 endpoint，且不与特定集群关联。
• 生成设备报告需要 smartmontools 7.0 或更高版本（否则无法输出/解析 JSON）。

如何关闭：ceph telemetry off（可随时执行，立即停止上报）。若只想停掉某一类数据，用 ceph telemetry disable channel <channel_name>。

子命令表：

子命令	参数	说明	示例
on	[--license sharing-1-0]	开启 telemetry。必须先加 --license sharing-1-0（遥测数据采用 CDLA-Sharing-1.0 许可），开启后命令输出会列出启用默认关闭通道（如 perf）的确切命令	ceph telemetry on --license sharing-1-0
off	—	关闭 telemetry；通道级设置随之失效	ceph telemetry off
status	—	打印 telemetry 模块当前配置	ceph telemetry status
show	[<channel_name>]	显示实际将上报的数据；给通道名则只显示该通道。若 telemetry 开启但该通道被关闭，仍会按你已加入的 collection 输出样本，但该数据不会真的上报	ceph telemetry show crash
preview	[<channel_name>]	telemetry 关闭时预览样本报告（不发送）	ceph telemetry preview perf
show-device	—	显示设备报告样本（含匿名化后的 SMART 数据）	ceph telemetry show-device
preview-device	—	telemetry 关闭时预览设备报告	ceph telemetry preview-device
show-all	—	telemetry 开启时，一次性生成并输出上述两份报告	ceph telemetry show-all
preview-all	—	telemetry 关闭时，一次性预览两份报告	ceph telemetry preview-all
channel ls	—	列出所有通道及 ENABLED（当前）/ DEFAULT（默认）状态与描述	ceph telemetry channel ls
enable channel	<channel_name>... 或 all	启用一个或多个/全部通道；必须 telemetry 已开启才生效	ceph telemetry enable channel basic crash device ident perf
disable channel	<channel_name>... 或 all	停用一个或多个/全部通道	ceph telemetry disable channel ident
collection ls	—	列出所有 collection（通道内的数据方面），含 NAME / STATUS / DESC	ceph telemetry collection ls
diff	—	显示「你已加入的 collection」与「新增可用 collection」之间的差异	ceph telemetry diff
send	[--license sharing-1-0]	异步一次性上报；若 telemetry 未开启需加 --license sharing-1-0	ceph telemetry send

相关配置（通过 ceph config set mgr 设置）：

配置项	默认值	说明	示例
mgr/telemetry/interval	24（小时）	报告编译与发送间隔	ceph config set mgr mgr/telemetry/interval 72
mgr/telemetry/proxy	无	集群无法直连 telemetry.ceph.com 时配置 HTTP/HTTPS 代理，可带 user:pass	ceph config set mgr mgr/telemetry/proxy https://ceph:telemetry@10.0.0.1:8080
mgr/telemetry/contact	无	报告中的联系人（可选，默认关闭）	ceph config set mgr mgr/telemetry/contact 'John Doe <john.doe@example.com>'
mgr/telemetry/description	无	集群描述（可选，默认关闭）	ceph config set mgr mgr/telemetry/description 'My first Ceph cluster'
mgr/telemetry/channel_ident	false	是否启用 ident 通道上报联系人/描述	ceph config set mgr mgr/telemetry/channel_ident true
mgr/telemetry/leaderboard	false	是否参与公共面板排行榜（展示总容量与 OSD 数）	ceph config set mgr mgr/telemetry/leaderboard true
mgr/telemetry/leaderboard_description	无	排行榜上的集群描述	ceph config set mgr mgr/telemetry/leaderboard_description 'Ceph cluster for Computational Biology at the University of XYZ'

典型示例：

# 开启 / 关闭 telemetry
ceph telemetry on --license sharing-1-0
ceph telemetry off

# 查看状态、通道与 collection
ceph telemetry status
ceph telemetry channel ls
ceph telemetry collection ls

# 开启默认关闭的 perf 通道；关闭 ident 通道
ceph telemetry enable channel perf
ceph telemetry disable channel ident
ceph telemetry enable channel basic crash device ident perf
ceph telemetry disable channel all

# 查看将要上报的内容（开启时）/ 预览样本（关闭时）
ceph telemetry show
ceph telemetry show crash
ceph telemetry preview
ceph telemetry preview perf
ceph telemetry show-all
ceph telemetry preview-all

# 设备报告
ceph telemetry show-device
ceph telemetry preview-device

# 一次性上报、查看新增 collection 差异
ceph telemetry send
ceph telemetry diff

# 调整上报间隔为 72 小时、走代理
ceph config set mgr mgr/telemetry/interval 72
ceph config set mgr mgr/telemetry/proxy https://10.0.0.1:8080

注意事项 / 常见坑：

• ceph telemetry on 必须带 --license sharing-1-0，否则无法开启（CDLA-Sharing-1.0 许可要求）。
• 通道级开关只有在 telemetry 开启时才有效；telemetry 关闭时改通道没有任何效果。
• telemetry 开启但某通道被关闭时，ceph telemetry show <channel> 仍会输出样本数据，但这部分数据不会上报——不要误判为"已在上报"。
• 大集群（数百 OSD 以上）生成样本报告可能需要一些时间。
• 设备报告依赖 smartmontools ≥ 7.0；且设备数据发往独立 endpoint、与集群不关联。
• ident 通道若启用，其详情不会显示在排行榜上。

引自：ceph

---

1.2 ceph-conf

用途：从 Ceph 配置文件（而非 monitor）中读取配置信息的工具。

语法（synopsis，保留原文格式）：

ceph-conf -c conffile --list-all-sections
ceph-conf -c conffile -L
ceph-conf -c conffile -l prefix
ceph-conf key -s section1 ...
ceph-conf [-s section ] [-r] --lookup key
ceph-conf [-s section ] key

常用选项表

选项	参数	默认值	说明
-L, --list-all-sections	—	无	列出配置文件中所有 section
-l, --list-sections *prefix*	prefix	无	列出以 prefix 开头的 section（如 --list-sections mon）
--lookup *key*	key	默认动作	查找并打印指定配置项；若命令行未给其他动作则默认执行 lookup
-h, --help	—	无	打印用法摘要
-c *conffile*	文件路径	无	指定 Ceph 配置文件
--filter-key *key*	key	无	过滤 section 列表，只保留定义了该 key 的 section
--filter-key-value *key*=*value*	key=value	无	只保留具有指定 key/value 对的 section
--name *type.id*	type.id	client.admin	指定搜索用的 Ceph 名；如 --name osd.0 会依次搜索 [osd.0]、[osd]、[global]
--pid *pid*	pid	本进程 PID	展开 $pid 时覆盖 PID
-r, --resolve-search	—	无	在逗号分隔的搜索列表中，找出第一个存在且可打开的文件
-s, --section	section	无	额外搜索的 section，优先于常规搜索；返回首个匹配项

典型示例

# 查 osd 0 使用的 "osd data" 值
ceph-conf -c foo.conf --name osd.0 --lookup "osd data"

# 同上，省略 --lookup（默认动作）
ceph-conf -c foo.conf --name mds.a "log file"

# 列出所有以 osd 开头的 section
ceph-conf -c foo.conf -l osd

# 列出所有 section
ceph-conf -c foo.conf -L

# 打印 client.0 使用的 keyring 路径
ceph-conf --name client.0 -r -l keyring

注意事项 / 常见坑

• 与其他 Ceph 工具不同：ceph-conf 只读配置文件（或返回编译内置默认值），不会从 monitor 集群取配置。官方建议只在严格基于配置文件的遗留环境使用。
• 新部署/新工具应改用 ceph config get <daemon> <option>，或让守护进程自己取生效值，例如 ceph-osd -i 123 --show-config-value osd_data——后者能同时覆盖编译默认值、配置文件和 monitor 配置库，得到该守护进程真正使用的值。
• 相关文件：/etc/ceph/$cluster.conf、~/.ceph/$cluster.conf、$cluster.conf（未指定 -c 时使用）。

引自：ceph-conf

---

1.3 ceph-run

用途：一个简单的包装器，当被包装的守护进程因崩溃（可能 core dump）退出时自动重启它。

语法（synopsis，保留原文格式）：

ceph-run command ...

常用选项表

选项	参数	默认值	说明
（无）	—	—	Options: None（文档原文明确写 None）

典型示例

# 用 ceph-run 包住前台运行的 OSD（注意守护进程需 -f 前台运行）
ceph-run ceph-osd -i 0 -f

# 包住 mon / mds
ceph-run ceph-mon -i mon.a -f
ceph-run ceph-mds -i mds.a -f

注意事项 / 常见坑

• 只有在进程以信号 3、4、5、6、8 或 11 退出时才会重启（即崩溃/可能 core dump 的信号）。
• 被包装的命令必须让守护进程在前台运行；对 Ceph 守护进程来说就是加 -f 选项。
• 它不自带任何日志/重启次数限制，生产环境通常仍由 systemd 管理。

引自：ceph-run

---

1.4 ceph-syn

用途：Ceph 分布式文件系统的合成负载生成器，通过用户态客户端库对正在运行的文件系统产生简单负载。

语法（synopsis，保留原文格式）：

ceph-syn [ -m monaddr:port ] --syn command ...

常用选项表

选项	参数	默认值	说明
-d	—	无	启动后脱离控制台并 daemonize
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件来确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor（跳过 ceph.conf 查找）
--num_client num	数量	无	运行 num 个不同客户端，各占一个线程
--syn workloadspec	负载规格	无	运行给定负载，可重复指定多次；负载通常顺序执行

工作负载（Workloads，每个都要前置 --syn）

负载	语法	说明
mknap	mknap *path* *snapname*	在 path 上创建名为 snapname 的快照
rmsnap	rmsnap *path* *snapname*	删除 path 上名为 snapname 的快照
rmfile	rmfile *path*	删除 / unlink path
writefile	writefile *sizeinmb* *blocksize*	创建以客户端 id 命名的文件，按 blocksize 块写入，共 sizeinmb MB
readfile	readfile *sizeinmb* *blocksize*	按 blocksize 读取以客户端 id 命名的文件
rw	rw *sizeinmb* *blocksize*	先写后读回
makedirs	makedirs *numsubdirs* *numfiles* *depth*	创建 depth 层深的目录树，每层每目录 numsubdirs 个子目录 + numfiles 个文件
walk	walk	递归遍历文件系统（类似 find）

文档注明"这不是完整列表"。

典型示例

# 单客户端：建目录树 + 遍历
ceph-syn -m 192.168.0.1:6789 --syn makedirs 5 10 3 --syn walk

# 写 100MB 文件、再读回
ceph-syn --syn writefile 100 1048576 --syn readfile 100 1048576

# 5 个并发客户端跑读写
ceph-syn --num_client 5 --syn rw 50 65536

# 建快照后删除
ceph-syn --syn mknap / snap1 --syn rmsnap / snap1

注意事项 / 常见坑

• 文件系统无需通过 ceph-fuse 或内核客户端挂载即可产生负载。
• 多个 --syn 负载通常顺序执行，不是并发；并发靠 --num_client。

引自：ceph-syn

---

1.5 ceph-post-file

用途：把文件或目录上传到 ceph.com，供 Ceph 开发者后续分析。

语法（synopsis，保留原文格式）：

ceph-post-file [-d description] [-u user] file or dir ...

常用选项表

选项	参数	默认值	说明
-d *description*, --description *description*	描述文本	无默认值	为本次上传添加简短描述；适合引用 bug 号
-u *user*	用户标识	whoami@hostname -f	设置上传的用户元数据

典型示例

# 上传单个日志
ceph-post-file /var/log/ceph/ceph-mon.`hostname`.log

# 上传多个目录，并附描述
ceph-post-file -d 'mon data directories' /var/log/ceph/mon/*

注意事项 / 常见坑

• 安全警告：官方仅采取基本措施保证数据只对有权访问 ceph.com 基础设施的开发者可见。上传日志、含 Ceph 密钥的数据目录等敏感数据前请三思或先做脱敏。
• 每次调用会上传到带唯一 tag 的独立目录；该 tag 可交给开发者或引用在 bug 报告（http://tracker.ceph.com/）里。
• 上传完成后，目录会被标记为不可读、不可写，防止他人访问或修改。

引自：ceph-post-file

---

1.6 librados-config

用途：显示已安装的 librados 信息的工具。

语法（synopsis，保留原文格式）：

librados-config [ --version ] [ --vernum ]

常用选项表

选项	参数	默认值	说明
--version	—	无	显示 librados 版本
--vernum	—	无	显示 librados 版本代码（version code）

典型示例

librados-config --version
librados-config --vernum

注意事项 / 常见坑

• 无。文档未列出其他选项或限制。

引自：librados-config

---

二、密钥与认证

2.1 ceph-authtool

用途：创建、查看和修改 Ceph keyring 文件的工具（keyring 保存一个或多个 Ceph 认证密钥及可选的能力声明）。

语法（synopsis，保留原文格式）：

ceph-authtool keyringfile
  [ -l | --list ]
  [ -p | --print-key ]
  [ -C | --create-keyring ]
  [ -g | --gen-key ]
  [ --gen-print-key ]
  [ --import-keyring otherkeyringfile ]
  [ -n | --name entityname ]
  [ -a | --add-key base64_key ]
  [ -t | --key-type KEY_TYPE ]
  [ --cap subsystem capability ]
  [ --caps capfile ]
  [ --mode mode ]

常用选项表

选项	参数	默认值	说明
-l, --list	—	无	列出 keyring 中所有 key 与 capabilities
-p, --print-key	—	无	打印指定 entityname 的编码后 key，适合用于 mount -o secret=
-C, --create-keyring	—	无	创建新 keyring，覆盖已存在的 keyringfile
-g, --gen-key	—	无	为指定 entityname 生成新的 secret key
--gen-print-key	—	无	生成新 secret key 但不修改 keyringfile，直接打到 stdout
--import-keyring *secondkeyringfile*	文件路径	无	把另一个 keyring 的内容导入到当前 keyringfile
-n, --name *name*	entityname（形如 {client,mon,mds,osd}.name）	无	指定要操作的实体名
-a, --add-key *base64_key*	base64 key	无	向 keyring 添加一个编码后的 key
--cap *subsystem* *capability*	子系统 + 能力串	无	设置指定子系统的 capability
--caps *capsfile*	文件路径	无	一次性设置某 key 在所有子系统上的 capabilities
--mode *mode*	如 0644	0600	设置 keyring 文件的权限模式
--key-type *KEY_TYPE*	aes / aes256k / preferred	preferred	设置生成 key 的类型（preferred = 由 Ceph operator 选定的默认）

Capabilities 速查

• subsystem（子系统）：mon、mds、osd。
• capability：逗号分隔的 allow 子句 + 权限说明符（r/w/x）；allow * 表示对该子系统的完全超级用户权限。

场景	示例 caps
可读写执行对象	osd = "allow rwx"
可访问 mds	mds = "allow"
可修改集群状态（守护进程）	mon = "allow rwx"
限定单个池的 librados 用户	mon = "allow r" + osd = "allow rw pool foo"
rbd 客户端（一池只读、一池读写）	mon = "allow r" + osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
挂载文件系统最小权限	mds = "allow" + osd = "allow rw pool data" + mon = "allow r"

OSD capability 语法：

osdcap  := grant[,grant...]
grant   := allow (match capspec | capspec match)
match   := [ pool[=]<poolname> | object_prefix <prefix>
            | namespace[=]<rados-namespace>
            | tag <application-name> <key>=<value> ]
capspec := * | [r][w][x] [class-read] [class-write]

capspec	含义
r	对象读权限
w	对象写权限
x	可调用任意 class 方法（等价于 class-read class-write）
class-read	可调用只读 class 方法
class-write	可调用写 class 方法
* 或 all	等价 rwx，另加执行 osd 管理命令的能力（如 ceph osd tell ...）

授权是叠加的：只要客户端满足某个 grant 的 match 条件，就获得该 grant 的权限。

caps 文件格式：每行一个 key/value，用 = 分隔；值若含空白必须用 ' 或 " 引起来；key 是子系统名（osd/mds/mon），value 是能力串。

典型示例

# 新建 keyring，含 client.foo 的 key，文件权限 0644
ceph-authtool -C -n client.foo --gen-key keyring --mode 0644

# 给该 key 关联能力（可挂载 CephFS）
ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring

# 查看 keyring 内容
ceph-authtool -l keyring

# 挂载时直接取用编码后的 secret
mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`

# 只生成并打印一个 key，不改动 keyring
ceph-authtool --gen-print-key -n client.bar

# 从 caps 文件批量设置
printf 'mon = "allow r"\nosd = "allow rw pool=data"\n' > caps.txt
ceph-authtool -n client.foo --caps caps.txt keyring

注意事项 / 常见坑

• 安全警告：Ceph 提供认证和中间人攻击防护，但线路上的数据不加密（包括配置密钥的消息）。该系统主要面向可信环境使用。
• -C 会覆盖已有 keyring 文件。
• 默认 --mode 为 0600，若需要其他进程读取（如某些 Web 服务）才放宽。
• --key-type 默认 preferred，即由 Ceph operator 选定的默认算法。

引自：ceph-authtool

---

2.2 ceph-clsinfo

用途：显示某个 class object（RADOS class 对象文件）的名称、版本与架构信息。

语法（synopsis，保留原文格式）：

ceph-clsinfo [ options ] ... filename

常用选项表

选项	参数	默认值	说明
-n, --name	—	无	显示 class 名称
-v, --version	—	无	显示 class 版本
-a, --arch	—	无	显示 class 架构

典型示例

ceph-clsinfo -n /usr/lib64/rados-classes/libcls_rbd.so
ceph-clsinfo -v /usr/lib64/rados-classes/libcls_rbd.so
ceph-clsinfo -a /usr/lib64/rados-classes/libcls_rbd.so

注意事项 / 常见坑

• 文档未说明多个选项能否同时给出，也未给出输出格式示例；实际行为请以 --help 或命令输出为准。

引自：ceph-clsinfo

---

三、MON / OSD 工具

3.1 ceph-mon

用途：Ceph 集群的 monitor 守护进程；一个或多个 ceph-mon 组成 Paxos part-time parliament 集群，提供集群成员、配置与状态的高可靠持久存储。

语法（synopsis，保留原文格式）：

ceph-mon -i monid [ --mon-data mondatapath ]

常用选项表

选项	参数	默认值	说明
-i *monid*	mon id	无（必填）	指定 monitor 的 id
--mon-data *mondatapath*	目录路径	配置文件中的 mon data	存放 monitor 数据的本地目录
-f, --foreground	—	无	前台运行，不 daemonize，不生成 pid 文件；配合 ceph-run 使用
-d	—	无	调试模式：同 -f，但把所有日志输出到 stderr
--setuser userorgid	用户名或 uid	无	启动后设置 uid；给用户名时会查用户记录得到 uid 与 gid（除非同时给了 --setgroup）
--setgroup grouporgid	组名或 gid	无	启动后设置 gid
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
--mkfs	—	无	用 seed 信息初始化 mon data 目录（见下方"三要素"）
--keyring	路径	无	指定 --mkfs 时使用的 keyring
--use-mon-keyring	—	无	以 mon 的 keyring 文件作为 mon. secret 的权威来源（通常用的是 mons' auth database 中的 key）
--no-config-file	—	无	声明不依赖任何 ceph.conf（无论用户提供的还是默认的），所有必要选项都必须通过命令行参数提供

--mkfs 必须提供的三要素

1. cluster fsid：来自 monmap（--monmap <path>）或通过 --fsid <uuid> 显式给出。
2. monitor 列表及地址：来自 monmap、mon host 配置值（ceph.conf 或 -m host1,host2,...），或（向后兼容）ceph.conf 中已废弃的 mon addr 行。若该 monitor 要成为新集群初始 quorum 的一员，则它必须出现在初始列表中（按名字或地址匹配）；按地址匹配时可用 public addr 或 public subnet。
3. monitor secret key mon.：必须通过 --keyring <path> 提供的 keyring 包含它。

典型示例

# 前台运行（便于 ceph-run 包装或排障）
ceph-mon -i mon.a -f

# 调试模式
ceph-mon -i mon.a -d

# 初始化 mon 数据目录（新建集群）
ceph-mon -i mon.a --mkfs --monmap /tmp/monmap --keyring /tmp/ceph.mon.keyring

# 初始化时显式给 fsid
ceph-mon -i mon.a --mkfs --fsid $(uuidgen) --keyring /var/lib/ceph/mon/ceph-a/keyring

# 以 mon 自己的 keyring 为权威
ceph-mon -i mon.a --mkfs --use-mon-keyring --keyring /var/lib/ceph/mon/ceph-a/keyring

# 不使用任何配置文件，全部参数走命令行
ceph-mon -i mon.a --no-config-file --mon-data /var/lib/ceph/mon/ceph-a

注意事项 / 常见坑

• --mkfs 三要素缺一不可，尤其是 keyring 中必须有 mon. secret。
• mon addr 配置方式已废弃，未来版本会移除支持，请使用 mon host。
• --no-config-file 意味着所有必要选项都得在命令行给全，漏一个就起不来。
• 用 ceph-run 包装时必须加 -f（前台），否则 ceph-run 无法判断崩溃。

引自：ceph-mon

---

3.2 ceph-osd

用途：Ceph 的对象存储守护进程，管理本地存储上的数据并提供网络访问。

语法（synopsis，保留原文格式）：

ceph-osd -i osdnum [ --osd-data datapath ] [ --osd-journal journal ] [ --mkfs ] [ --mkjournal ] [--flush-journal] [--check-allows-journal] [--check-wants-journal] [--check-needs-journal] [ --mkkey ] [ --osdspec-affinity ]

常用选项表

选项	参数	默认值	说明
-i *osdnum*	OSD 编号	无（必填）	指定 OSD 编号
-f, --foreground	—	无	前台运行，不 daemonize，不生成 pid 文件；配合 ceph-run 使用
-d	—	无	调试模式：同 -f，但所有日志输出到 stderr
--setuser userorgid	用户名或 uid	无	启动后设置 uid（给用户名时同时设 gid，除非另有 --setgroup）
--setgroup grouporgid	组名或 gid	无	启动后设置 gid
--osd-data osddata	目录路径	无	使用该路径下的 object store（Filestore 时代应为 XFS 文件系统上的目录）
--osd-journal journal	路径	无	journal 更新写入该 journal
--check-wants-journal	—	无	检查是否需要 journal
--check-allows-journal	—	无	检查是否允许 journal
--check-needs-journal	—	无	检查是否必须有 journal
--mkfs	—	无	创建空的 object repository（若定义了 journal 也会一并初始化）
--mkkey	—	无	生成新 secret key；通常与 --mkfs 合用（比手工用 ceph-authtool 方便）
--mkjournal	—	无	为已有的 object repository 创建新的 journal 文件（journal 设备/文件被清空后重建用）
--flush-journal	—	无	把 journal 刷到持久存储；前台运行以便知道何时完成。在调整 journal 大小或销毁 journal 前使用可保证不丢数据
--get-cluster-fsid	—	无	打印集群 fsid（uuid）并退出
--get-osd-fsid	—	无	打印该 OSD 的 fsid（在 --mkfs 时生成，唯一标识该次实例化）
--get-journal-fsid	—	无	打印 journal 的 uuid（--mkfs 时被设为与 OSD fsid 相同）
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	运行时配置使用指定文件
-m monaddress[:port]	地址	无	直连指定 monitor
--osdspec-affinity	—	无	设置对某个 OSDSpec 的亲和性；只能与 --mkfs 同时使用

典型示例

# 前台运行 OSD 0（配合 ceph-run）
ceph-run ceph-osd -i 0 -f

# 初始化一个 OSD 数据目录并生成 key
ceph-osd -i 0 --mkfs --mkkey --osd-data /var/lib/ceph/osd/ceph-0

# 重建 journal
ceph-osd -i 0 --mkjournal --osd-data /var/lib/ceph/osd/ceph-0

# 调整/销毁 journal 前先刷盘
ceph-osd -i 0 --flush-journal --osd-data /var/lib/ceph/osd/ceph-0

# 查询各类 fsid
ceph-osd -i 0 --get-cluster-fsid
ceph-osd -i 0 --get-osd-fsid --osd-data /var/lib/ceph/osd/ceph-0
ceph-osd -i 0 --get-journal-fsid --osd-data /var/lib/ceph/osd/ceph-0

# 检查 journal 需求情况
ceph-osd -i 0 --check-needs-journal --osd-data /var/lib/ceph/osd/ceph-0

# 随 OSDSpec 亲和性初始化
ceph-osd -i 0 --mkfs --osdspec-affinity --osd-data /var/lib/ceph/osd/ceph-0

注意事项 / 常见坑

• --osdspec-affinity 只能和 --mkfs 一起用，单独使用无效。
• --flush-journal 是前台执行的，正是为了让你确认它何时完成——销毁 journal 前务必先执行。
• 文档关于 journal 的说明是面向 Filestore 的：journal 只有在与 datapath 不同盘时才提升性能，且应放在低延迟介质（理想是 SSD）上。
• --mkkey 通常配合 --mkfs，避免手工用 ceph-authtool 生成 key。

引自：ceph-osd

---

3.3 ceph-mds

用途：Ceph 分布式文件系统的元数据服务器守护进程；多个实例协同管理文件系统命名空间，协调对共享 OSD 集群的访问。

语法（synopsis，保留原文格式）：

ceph-mds -i <ID> [flags]

常用选项表

选项	参数	默认值	说明
-f, --foreground	—	无	前台运行，不 daemonize，不生成 pid 文件；配合 ceph-run 使用
-d	—	无	调试模式：同 -f，但所有日志输出到 stderr
--setuser userorgid	用户名或 uid	无	启动后设置 uid（给用户名时同时设 gid，除非另有 --setgroup）
--setgroup grouporgid	组名或 gid	无	启动后设置 gid
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor
--id / -i ID	ID	无	设置 MDS 名称中的 ID 部分；ID 不应以数字开头
--name / -n TYPE.ID	TYPE.ID（TYPE 显然为 mds）	无	设置完整 MDS 名；ID 不应以数字开头

典型示例

# 前台启动一个 MDS
ceph-run ceph-mds -i mds.a -f

# 指定 monitor 与配置文件
ceph-mds -i mds.a -m 192.168.0.1:6789 -c /etc/ceph/ceph.conf

# 用完整名字启动
ceph-mds -n mds.b -f

# 以指定用户/组运行
ceph-mds -i mds.a --setuser ceph --setgroup ceph -f

注意事项 / 常见坑

• 每个 ceph-mds 实例应有唯一名称，该名称用于在 ceph.conf 中标识实例。
• ID 不应以数字开头。
• 守护进程启动后，monitor 集群通常会为其分配一个逻辑 rank，或放入 standby 池以接管崩溃的守护进程；某些指定选项会导致不同行为。

引自：ceph-mds

---

3.4 monmaptool

用途：创建、查看和修改 Ceph monitor 集群映射（monmap）的工具；monmap 指定了 Ceph 分布式系统中唯一固定的地址。

语法（synopsis，保留原文格式）：

monmaptool <action> [options] mapfilename

常用选项表

选项	参数	默认值	说明
--print	—	无	在完成所有修改后，打印 map 的纯文本 dump
--feature-list [plain|parseable]	格式	人类可读（plain）	列出已启用及可用的特性
--create	—	无	创建带新 UUID 的新 monmap（随之是一个新的空 Ceph 集群）
--clobber	—	无	允许用新 map 覆盖已存在的 mapfilename；仅在 --create 时有用
--generate	—	无	基于命令行或 ceph 配置生成新 monmap，优先顺序：① --monmap filename ② --mon-host 'host1,ip2' ③ 配置中 [mon.foo] 段的 mon addr（不推荐，未来版本将移除）
--filter-initial-members	—	无	按 mon initial members 过滤初始 monmap：不在列表中的 monitor 会被移除，列表中但不在 map 里的会用 dummy 地址加入
--add name ip[:port]	name + ip[:port]	无	添加一个 monitor。若启用了 nautilus 特性且未指定 port，会同时为两种 messenger 协议添加
--addv name [protocol:ip:port[,...]]	name + 版本化地址	无	按 protocol:ip:port 添加 monitor
--rm name	name	无	移除指定名称的 monitor
--fsid uuid	uuid	随机生成	设置 fsid；若 --create 时未指定则随机生成
--feature-set value [--optional|--persistent]	value	无	启用某个特性
--feature-unset value [--optional|--persistent]	value	无	关闭某个特性
--enable-all-features	—	无	启用所有受支持的特性
--set-min-mon-release release	release	无	设置 min_mon_release
--auth-service-cipher=<cipher>	cipher	aes256k	设置 rotating service keys 的加密类型
--auth-allowed-ciphers=<cipher1,cipher2,...>	列表	aes256k	设置守护进程（含 Monitor）与客户端认证时允许的加密类型
--auth-preferred-cipher=<cipher>	cipher	aes256k	设置新凭据或 key 轮换时的首选加密类型

典型示例

# 为全新集群创建含三个 monitor 的 monmap
monmaptool --create --add nodeA 192.168.0.10 --add nodeB 192.168.0.11 \
  --add nodeC 192.168.0.12 --enable-all-features --clobber monmap

# 显示 map 内容
monmaptool --print monmap

# 替换一个 monitor（先删后加）
monmaptool --rm nodeA monmap
monmaptool --add nodeA 192.168.0.9 monmap

# 指定 fsid 与 min_mon_release
monmaptool --create --fsid $(uuidgen) --set-min-mon-release tentacle --add nodeA 10.0.0.1 monmap

# 按 v2 协议显式指定地址
monmaptool --addv nodeA v2:10.0.0.1:3300,v1:10.0.0.1:6789 monmap

注意事项 / 常见坑

• 默认 Ceph monitor 端口：messenger v1 为 6789，v2 为 3300。
• 一次调用可执行多个 action。
• --clobber 只在配合 --create 时才有意义。
• 通过配置中 [mon.foo] 段的 mon addr 生成 monmap 的方式不推荐，未来版本会移除支持。
• 除 monitor 外，其他所有守护进程都绑定任意地址并向 monitor 注册——monmap 是唯一固定地址所在。

引自：monmaptool

---

3.5 osdmaptool

用途：创建、查看和操作 OSD 集群映射（osdmap）的工具；可抽取/导入 CRUSH map，并可模拟 upmap 均衡器以评估 PG 均衡所需操作。

语法（synopsis，保留原文格式）：

osdmaptool mapfilename [--print] [--createsimple numosd [--pgbits bitsperosd ] ] [--clobber]
osdmaptool mapfilename [--import-crush crushmap]
osdmaptool mapfilename [--export-crush crushmap]
osdmaptool mapfilename [--upmap file] [--upmap-max max-optimizations] [--upmap-deviation max-deviation] [--upmap-pool poolname] [--save] [--upmap-active]
osdmaptool mapfilename [--upmap-cleanup] [--upmap file]

常用选项表

选项	参数	默认值	说明
--print	—	无	在完成所有修改后打印 map 的纯文本 dump
--dump <format>	plain 或 json	无	以纯文本（plain）或 json 显示 map；是 --print 的替代
--clobber	—	无	允许在有修改时覆盖 mapfilename
--import-crush mapfile	文件路径	无	从文件加载 CRUSH map 并嵌入 osdmap
--export-crush mapfile	文件路径	无	从 osdmap 抽取 CRUSH map 写到文件
--createsimple numosd [--pg-bits bitsperosd] [--pgp-bits bits]	数量/位数	无	创建通用 osdmap；pg_num = numosd << bitsperosd，pgp_num = numosd << bits
--create-from-conf	—	无	用默认配置创建 osdmap
--test-map-pgs [--pool poolid] [--range-first <first> --range-last <last>]	—	无	打印 PG→OSD 映射
--test-map-pgs-dump [--pool poolid] [--range-first ... --range-last ...]	—	无	打印全部 PG 摘要及其到已映射 OSD 的映射
--test-map-pgs-dump-all [--pool poolid] [--range-first ... --range-last ...]	—	无	打印全部 PG 摘要及其到全部 OSD 的映射
--test-random	—	无	随机映射 PG 到 OSD
--test-map-pg <pgid>	pgid	无	映射某个 PG 到 OSD
--test-map-object <objectname> [--pool <poolid>]	对象名	无	映射某个对象到 PG/OSD
--test-crush [--range-first ... --range-last ...]	—	无	把 PG 映射到 acting OSD
--mark-up-in	—	无	标记 osd 为 up 且 in（不持久化）
--mark-out	—	无	标记某 osd 为 out（不持久化）
--mark-up <osdid>	osd id	无	标记某 osd 为 up（不持久化）
--mark-in <osdid>	osd id	无	标记某 osd 为 in（不持久化）
--tree	—	无	以层次树展示 map
--clear-temp	—	无	清除 pg_temp 与 primary_temp 变量
--clean-temps	—	无	清理 pg_temps
--health	—	无	导出健康检查
--with-default-pool	—	无	创建 map 时包含默认池
--upmap-cleanup <file>	文件路径	-（stdout）	清理 pg_upmap[_items] 条目，把命令写入 file
--upmap <file>	文件路径	-（stdout）	计算用于均衡 PG 布局的 upmap 条目，写入 file
--upmap-max <max-optimizations>	数量	10	最多计算多少条 upmap 条目
--upmap-deviation <max-deviation>	数值	5	允许的最大偏差
--upmap-pool <poolname>	池名	无	把 upmap 均衡限制在某池；可重复指定多个池
--upmap-active	—	无	像 active balancer 一样持续应用变更直到均衡
--adjust-crush-weight <osdid:weight>[,<osdid:weight>,...]	列表	无	修改指定 OSD 的 CRUSH 权重
--save	—	无	把含 upmap 或 crush-adjust 变更的 osdmap 写回
--read <file>	文件路径	无	计算用于均衡 PG primary 的 upmap 条目（read 模式）
--read-pool <poolname>	池名	无	指定 read balancer 调整的池
--vstart	—	无	给 upmap / read 输出加 ./bin/ 前缀

典型示例

# 创建一个含 16 个设备的简单 map
osdmaptool --createsimple 16 osdmap --clobber

# 查看结果
osdmaptool --print osdmap

# 查看 pool 1 的 PG 映射分布
osdmaptool osdmap --test-map-pgs-dump --pool 1

# 导出 / 导入 CRUSH map
osdmaptool osdmap --export-crush cm.txt
osdmaptool osdmap --import-crush cm.txt --clobber

# 模拟 active balancer（upmap 模式）
osdmaptool --upmap upmaps.out --upmap-active --upmap-deviation 6 --upmap-max 11 osdmap

# 只清理 upmap 条目
osdmaptool osdmap --upmap-cleanup cleanup.out

# 修改 CRUSH 权重并保存
osdmaptool osdmap --adjust-crush-weight 3:0.8 --save

# 模拟 read 均衡（先确保容量已用 upmap 均衡过）
osdmaptool osdmap --read read.out --read-pool <pool name>

输出解读（--test-map-pgs-dump）

pool 1 pg_num 8
1.0     [0,2,1] 0
...
#osd    count   first   primary c wt    wt
osd.0   8       5       5       1       1
 in 3
 avg 8 stddev 0 (0x) (expected 2.3094 0.288675x))
 min osd.0 8
 max osd.0 8

• PG 表三列：PG id / acting set / primary OSD。
• OSD 表五列：映射到该 OSD 的 PG 数 / acting set 中排第一的次数 / 作为 primary 的次数 / CRUSH 权重 / 权重。
• 统计段：PG 数量的平均值、标准差、标准差/均值、期望标准差、期望标准差/均值，以及 min/max。
• 最后是"映射到 n 个 OSD 的 PG 数量"分布。

注意事项 / 常见坑

• --mark-*、--clear-temp 等标记类操作不会持久化，除非配合 --save。
• --upmap-max 默认 10、--upmap-deviation 默认 5；--upmap / --upmap-cleanup 的默认输出文件是 -（stdout）。
• read 模式（read balancer）必须在先用 upmap 模式把容量均衡好之后再跑。
• 文档提示：--test-map-pgs-dump 等带 --range-first/--range-last 时会遍历 osdmap 目录下名为 first..last 的文件。
• --clobber 在有修改时才需要。

引自：osdmaptool

---

3.6 crushtool

用途：创建、编译、反编译和测试 CRUSH map 文件的工具。

语法（synopsis，保留原文格式）：

crushtool ( -d map | -c map.txt | --build --num_osds numosds layer1 ... | --test ) [ -o outfile ]

四种模式与常用选项

选项	参数	默认值	说明
--compile / -c map.txt	纯文本 map	无	把明文 map.txt 编译为二进制 map 文件
--decompile / -d map	二进制 map	无	把已编译 map 反编译为适合编辑的明文源文件
--build --num_osds {num-osds} layer1 ...	层数与每层定义	无	按给定层结构创建 map（见"构建"段）
--test	—	无	对输入范围 [--min-x,--max-x]（默认 [0,1023]）做 CRUSH 映射干跑
-o outfile	文件路径	无	输出文件

--test 模式下的报告选项：

选项	参数	默认值	说明
--show-statistics	—	无	显示分布摘要，如 rule 1 (metadata) num_rep 5 result size == 5: 1024/1024
--show-mappings	—	无	显示 [--min-x,--max-x] 内每个值的映射，如 CRUSH rule 1 x 24 [11,6]。必须配合 --num-rep，或同时给 --min-rep + --max-rep
--show-bad-mappings	—	无	显示映射失败（未达到要求副本数）的值
--show-utilization	—	无	显示每个设备在每个副本数下的期望与实际利用率（隐含 --show-statistics）
--show-utilization-all	—	无	同上，但不抑制权重为 0 的设备输出（隐含 --show-statistics）
--show-choose-tries	—	无	显示找到映射所需的尝试次数分布；行数等于 --set-choose-total-tries
--output-csv	—	无	在当前目录生成 CSV 文件（文件名取自规则名，如 metadata-absolute_weights.csv）
--output-name NAME	前缀	无	给 --output-csv 生成的文件名加前缀，如 FOO-metadata-...csv
--num-rep / --min-rep + --max-rep	副本数	无	指定精确副本数或副本数范围
--min-x / --max-x	数值	0 / 1023	模拟输入值范围（可视为模拟的 PG）
--set-...（tunables）	如 --set-choose-total-tries 500	无	在内存中修改输入 crush map 的 tunables
--simulate	—	无	随机放置（random placement）模拟

更多 --test 相关选项与 --set-... tunables 的完整清单见官方 man 页。

构建 map（--build）

每层语法：

bucket ( uniform | list | tree | straw | straw2 ) size

• bucket：该层 bucket 的类型（如 rack）；每个 bucket 名 = bucket 字符串 + 唯一数字（rack0、rack1...）。
• 类型：多数情况下应使用 straw。
• size：bucket 的最大容量；0 表示无限容量。

典型示例

# 反编译 → 编辑 → 重新编译
crushtool -d crushmap -o map.txt
$EDITOR map.txt
crushtool -c map.txt -o crushmap

# 构建一个 320 OSD 的层级 map（2 row × 2 rack × 20 node × 4 osd）
crushtool -o crushmap --build --num_osds 320 \
       node straw 4 \
       rack straw 20 \
       row straw 2 \
       root straw 0

# 测试并查看统计 / 坏映射
crushtool -i mymap --test --show-statistics
crushtool -i mymap --test --show-bad-mappings
crushtool -i mymap --test --show-mappings --num-rep 3
crushtool -i mymap --test --show-mappings --min-rep 1 --max-rep 10
crushtool -i mymap --test --show-utilization

# 通过增大 choose-total-tries 修复坏映射
crushtool -i mymap --test --show-bad-mappings --set-choose-total-tries 500

# 导出 CSV 报告
crushtool -i mymap --test --output-csv --output-name FOO

注意事项 / 常见坑

• 与其他 Ceph 工具不同：crushtool 不接受 --debug-crush 之类的通用命令行选项；它们只能通过 CEPH_ARGS 环境变量传入，例如 CEPH_ARGS="--debug-crush 0" crushtool ...。
• crushtool 不了解 PG 或 pool，它只是对 [--min-x,--max-x] 范围内的值做映射模拟。PG 的整数 ID 可从 ceph pg dump 获得（如 PG 2.2f = pool id 2、PG id 32），pool 与 PG ID 经组合函数得到一个值再交给 CRUSH。
• --show-mappings 必须配 --num-rep 或同时配 --min-rep+--max-rep。
• --build 生成的 CRUSH rule 与新建 Ceph 集群时的默认规则相同，可再编辑。
• Reclassify：可把旧式并行层级（按 OSD 类型分多个层级）迁移到使用 device class 特性的现代 CRUSH map（详见官方 CRUSH map 编辑文档）。

引自：crushtool

---

3.7 crushdiff

用途：测试 CRUSH map 变更影响的工具——会移动多少 PG、多少对象、多少字节。它是 osdmaptool --test-map-pgs-dump 的封装，并结合 pg stats 计算对象与字节迁移量。

语法（synopsis，保留原文格式）：

crushdiff [ --osdmap osdmap ] [ --pg-dump pg-dump ] [ --compiled ] [ --verbose ] command crushmap

常用选项表

选项	参数	默认值	说明
--compiled	—	无	输入/输出 crushmap 是已编译格式；不指定则为 txt（反编译）格式
--pg-dump <pg-dump>	JSON 文件	自行执行 ceph pg dump 获取	ceph pg dump 的 JSON 输出
--osdmap <osdmap>	文件	自行执行 ceph osd getmap 获取	集群 osdmap
--verbose	—	无	输出诊断信息（含受影响的 PG 明细）

命令（Commands）

命令	语法	说明
compare	compare *crushmap*	把文件中的 crushmap 与集群 osdmap 中的 crushmap 比较，输出安装新 map 后会移动的 PG/对象/字节数
export	export *crushmap*	从集群 osdmap 导出 crushmap 到文件
import	import *crushmap*	把文件中的 crushmap 导入到集群 osdmap

典型示例

# 1) 取当前 crushmap
crushdiff export cm.txt

# 2) 编辑
$EDITOR cm.txt

# 3) 看影响
crushdiff compare cm.txt

# 4) 满意后安装
crushdiff import cm.txt

# 带诊断信息
crushdiff compare cm.txt --verbose

# 使用已保存的离线数据（不需要连集群）
crushdiff --osdmap /tmp/osdmap --pg-dump /tmp/pgdump.json compare cm.txt

# 处理已编译的 crushmap
crushdiff --compiled compare cm.bin

输出示例

79/416 (18.99%) pgs affected
281/1392 (20.19%) objects affected
80/1248 (6.41%) pg shards to move
281/4176 (6.73%) pg object shards to move
730.52Mi/10.55Gi (6.76%) bytes to move

加 --verbose 还会列出受影响的 PG 明细（PG 号 + 旧/新 OSD active set）：

4.3	[0, 2, 1] -> [1, 4, 2]
4.b	[0, 1, 3] -> [2, 1, 3]
4.c	[4, 0, 1] -> [4, 1, 2]

注意事项 / 常见坑

• 默认需要访问集群（会用集群当前 osdmap 与 pg stats）；离线评估请用 --osdmap + --pg-dump。
• 输出的"对象数/字节数"依赖 pg stats，因此与真实迁移量是估算关系。
• --compiled 决定输入/输出格式，与 crushtool 的 -c/-d 对应关系要理清，避免格式不匹配。

引自：crushdiff

---

3.8 ceph-kvstore-tool

用途：kvstore（键值存储）操作工具，允许离线操作 RocksDB 中的数据（如 OSD 的 omap）。

语法（synopsis，保留原文格式）：

ceph-kvstore-tool <rocksdb|bluestore-kv> <store path> command [args...]

命令表

命令	语法	说明
list	list [prefix]	打印带该 URL 编码 prefix 的所有 KV 对的 key
list-crc	list-crc [prefix]	打印带该 prefix 的所有 KV 对的 CRC
dump	dump [prefix]	打印带该 prefix 的所有 KV 对的 key 与 value
exists	exists <prefix> [key]	检查是否存在该 prefix 的 KV 对；给了 key 则检查该 key
get	get <prefix> <key> [out <file>]	取指定 prefix+key 的 value；给了 file 则写入文件
crc	crc <prefix> <key>	取指定 KV 对的 CRC
get-size	get-size [<prefix> <key>]	取预估的 store 大小，或指定 prefix+key 的 value 大小
set	set <prefix> <key> [ver <N>|in <file>]	设置 value；value 可以是 version_t 或文本
rm	rm <prefix> <key>	删除指定 KV 对
rm-prefix	rm-prefix <prefix>	删除该 prefix 下的所有 KV 对
store-copy	store-copy <path> [num-keys-per-tx]	把所有 KV 对复制到 path 指定目录；num-keys-per-tx = 每事务复制的 KV 对数
store-crc	store-crc <path>	把所有 KV 对的 CRC 存到 path 指定文件
compact	compact	打开数据库并触发 compaction；之后可能释放部分磁盘空间
compact-prefix	compact-prefix <prefix>	只 compact 该 prefix 下的条目
compact-range	compact-range <prefix> <start> <end>	只 compact 该 prefix 下指定范围的条目
destructive-repair	destructive-repair	尽力（可能具破坏性）恢复损坏的数据库
stats	stats	打印底层 KV 数据库的统计信息（仅供参考，格式与内容可能随版本变化）
histogram	histogram	展示底层 KV 数据库中 key/value 大小的分布统计

典型示例

# 列出某 OSD 的 RocksDB 中所有 key
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 list

# 查看某 prefix 下的全部键值
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 dump O_

# 取某个 key 的值并写入文件
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 get O_ mykey out /tmp/val.bin

# 估算大小 / 看统计
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 get-size
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 stats
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 histogram

# 触发 compaction 释放空间
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 compact

# bluestore-kv 类型
ceph-kvstore-tool bluestore-kv /var/lib/ceph/osd/ceph-0 list

# 复制整个 store（每事务 1000 个 key）
ceph-kvstore-tool rocksdb /var/lib/ceph/osd/ceph-0 store-copy /tmp/kvbackup 1000

注意事项 / 常见坑

• destructive-repair 是最后手段：对 rocksdb 而言，它可能损坏一个本来没坏的数据库。
• 离线工具：操作前必须先停止对应 OSD，否则会与运行中的进程争抢数据库。
• stats 仅供信息参考，其格式与内容可能随版本变化。
• prefix 是URL 编码的。
• 该工具直接改动底层数据，任何 set/rm/rm-prefix 都应先备份（可用 store-copy）。

引自：ceph-kvstore-tool

---

3.9 ceph-dencoder

用途：Ceph 数据结构的编码/解码/转储工具，用于调试和测试跨版本兼容性；接收一个简单命令列表并按顺序执行。

语法（synopsis，保留原文格式）：

ceph-dencoder [commands...]

命令表

命令	参数	说明
version	—	打印 ceph-dencoder 二进制的版本字符串
import <file>	文件路径	从文件读入一段编码后的二进制数据到内存 buffer
export <file>	文件路径	把当前内存 buffer 的内容写到文件
list_types	—	列出本构建所知的全部数据类型
type <name>	类型名	为后续 encode/decode 选择类型
skip <bytes>	字节数	在导入的文件中先跳过 bytes 再读数据结构（用于对象前有 preamble/header 的情况）
decode	—	把内存 buffer 解码为先前选定类型的实例；出错会报告
encode	—	把内存中该类型的实例编码到内存 buffer
dump_json	—	打印内存中对象的 JSON 描述
count_tests	—	打印本工具可为选定类型生成的内置测试实例数量
select_test <n>	序号	选择第 n 个内置测试实例作为内存中的实例
get_features	—	打印本版本支持的 feature set 的十进制值（每个 bit 一个 feature，对应 src/include/ceph_features.h 中的 CEPH_FEATURE_*）
set_features <f>	数值	设置 encode 时使用的 feature bits，以便编码出旧版本软件能理解的对象（仅对支持该能力的类型有效）

典型示例

# 查看 ceph-osd 存储的某个对象的属性
cd /mnt/osd.12/current/2.b_head
attr -l foo_bar_head_EFE6384B
# Attribute "ceph.snapset" has a 31 byte value for foo_bar_head_EFE6384B
# Attribute "ceph._" has a 195 byte value for foo_bar_head_EFE6384B
attr foo_bar_head_EFE6384B -g ceph._ -q > /tmp/a
ceph-dencoder type object_info_t import /tmp/a decode dump_json

# 转储 CephFS 内部元数据对象（跳过 8 字节 preamble）
rados -p metadata get mds_snaptable mds_snaptable.bin
ceph-dencoder type SnapServer skip 8 import mds_snaptable.bin decode dump_json

# 列出所有已知类型
ceph-dencoder list_types

# 用内置测试实例编码，并设定 feature bits 以兼容旧版本
ceph-dencoder type osdmap_t count_tests
ceph-dencoder type osdmap_t select_test 0 set_features 12345 encode export /tmp/om.bin

注意事项 / 常见坑

• 命令是顺序执行的，type 必须先于 encode/decode 指定。
• 对象前有 header 时要先用 skip <bytes> 跳过（CephFS 元数据对象常见 8 字节 preamble）。
• set_features 只对支持该能力的类型有效。

引自：ceph-dencoder

---

3.10 ceph-debugpack

用途：打包一个含崩溃调试所需材料的 tarball，便于与 Ceph 开发者共享来定位问题。

语法（synopsis，保留原文格式）：

ceph-debugpack [ options ] filename.tar.gz

常用选项表

选项	参数	默认值	说明
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址

打包内容

tarball 会包含：ceph-mds、ceph-osd、ceph-mon、radosgw 的二进制，所有日志文件，ceph.conf 配置文件，能找到的 core 文件，以及（若系统在运行）由 ceph report 输出的当前集群状态 dump。

典型示例

# 生成调试包
ceph-debugpack /tmp/debug.tar.gz

# 指定配置文件
ceph-debugpack -c /etc/ceph/foo.conf /tmp/debug.tar.gz

# 生成后用 ceph-post-file 上传
ceph-post-file -d 'osd crash debugpack' /tmp/debug.tar.gz

注意事项 / 常见坑

• 包内可能包含日志与 core 文件，上传前注意脱敏（见 ceph-post-file 的安全警告）。
• 若集群在运行，会执行 ceph report，需要能连上集群。

引自：ceph-debugpack

---

四、RADOS

4.1 rados

用途：与 Ceph 对象存储集群（RADOS）交互的工具——对象增删改查、池快照、omap/xattr 操作、性能压测等。

语法（synopsis，保留原文格式）：

rados [ options ] [ command ]

全局选项表

选项	参数	默认值	说明
--object-locator object_locator	locator	无	为操作设置 object_locator
-p pool, --pool pool	池名	无（多数命令必需）	指定操作的池
--target-pool pool	池名	无	按名字选择目标池
--pgid	PG id	无	替代 --pool，把命令定向到指定 PG；例如 ls 只列该 PG 内的对象
-N namespace, --namespace namespace	namespace	无	指定 rados namespace
--all	—	无	配合 ls 列出所有 namespace 的对象；放进 CEPH_ARGS 可设为默认
--default	—	无	配合 ls 只列默认 namespace；优先于 --all（即使 --all 在环境变量里）
-s snap, --snap snap	快照名	无	从指定池快照读取；对所有池相关的读操作有效
--create	—	无	创建指定的池或目录
-i infile	文件路径	无	指定输入文件作为 payload 随命令发给 monitor；仅用于特定 monitor 命令
-m monaddress[:port]	地址	无	直连指定 monitor
-b block_size	字节数	无	设置 put/get/append 以及写压测使用的块大小
--striper	—	无	使用 rados 的 striping API（而非默认）；适用于 stat、stat2、get、put、append、truncate、rm、ls 及所有 xattr 相关操作
-O object_size, --object-size object_size	字节数	无	设置 put/get 与写压测的对象大小
--max-objects	数量	无	写压测的最大对象数
--lock-cookie locker-cookie	cookie	无	设置获取 advisory lock 的 cookie（lock get）；cookie 非空时，lock break 必须带上它才能找到并释放正确的锁
--target-locator	locator	无	配合 cp 指定新对象的 locator
--target-nspace	namespace	无	配合 cp 指定新对象的 namespace
--with-clones	—	无	Cache pool 选项：flush/evict 时包含克隆
--omap-key-file file	文件路径	无	从文件读取 omap key

Bench 选项：

选项	参数	说明
-t N, --concurrent-ios=N	数量	并发 I/O 数
--show-time	—	输出前加日期/时间前缀
--no-verify	—	不校验读取到的对象内容
--write-object	—	向对象中写内容
--write-omap	—	向 omap 写内容
--write-xattr	—	向扩展属性写内容

Load gen 选项：

选项	参数	说明
--num-objects	数量	对象总数
--min-object-size / --max-object-size	字节	最小/最大对象大小
--min-op-len / --max-op-len	字节	最小/最大 I/O 操作大小
--max-ops	数量	最大操作数
--max-backlog	大小	最大 backlog
--read-percent	百分比	读操作占比
--target-throughput	字节	目标吞吐
--run-length	秒	总运行时长
--offset-align	边界	随机操作偏移对齐边界

通用选项（Generic）：

选项	参数	默认值	说明
-c FILE, --conf FILE	文件路径	无	从指定配置文件读取配置
--id ID	id	无	设置 client entity 的 ID 部分（如 admin → client.admin）
-n TYPE.ID, --name TYPE.ID	TYPE.ID	无	设置完整实体名（如 client.admin）
--cluster NAME	集群名	ceph	设置集群名
--setuser USER	用户/uid	无	设置 uid（及用户的 gid）
--setgroup GROUP	组/gid	无	设置 gid
--version	—	无	显示版本并退出

命令表

全局命令：

命令	语法	说明
lspools	lspools	列出对象池
df	df	显示利用率统计（磁盘字节数 + 对象数），含全系统与按池拆分
list-inconsistent-pg	list-inconsistent-pg *pool*	列出指定池中的不一致 PG
list-inconsistent-obj	list-inconsistent-obj *pgid*	列出指定 PG 中的不一致对象
list-inconsistent-snapset	list-inconsistent-snapset *pgid*	列出指定 PG 中不一致的 snapset

池相关命令：

命令	语法	说明
get	get *name* *outfile*	读取对象并写到 outfile
put	put *name* *infile* [--offset offset]	写入对象，起始 offset 默认 0
append	append *name* *infile*	追加内容到对象
rm	rm [--force-full] *name* ...	删除对象；--force-full 允许在集群标记 full 时删除
listwatchers	listwatchers *name*	列出对象的 watcher
ls	ls *outfile*	列出池中对象并写入 outfile；配合 --pgid 只列该 PG 内对象
lssnap	lssnap	列出该池的快照
mksnap	mksnap *foo*	创建名为 foo 的池快照
rmsnap	rmsnap *foo*	删除池快照
bench	bench *seconds* *mode* [ -b *objsize* ] [ -t *threads* ]	压测；mode = write/seq/rand
cleanup	cleanup [ --run-name *run_name* ] [ --prefix *prefix* ]	清理上一次压测残留
listxattr / getxattr / setxattr / rmxattr	... *name* [*attr*] [*value*]	列出/取/设/删扩展属性
stat	stat *name*	取对象状态（mtime、size）
stat2	stat2 *name*	同 stat，但时间精度更高
listomapkeys	listomapkeys *name*	列出对象 omap 中所有 key
listomapvals	listomapvals *name*	列出对象 omap 中所有 key/value；value 以十六进制输出
getomapval	getomapval [ --omap-key-file *file* ] *name* *key* [ *out-file* ]	取 omap 中 key 的十六进制 value；不给出 out-file 则写到 stdout
setomapval	setomapval [ --omap-key-file *file* ] *name* *key* [ *value* ]	设置 omap 键值；不给出 value 则从 stdin 读
rmomapkey	rmomapkey [ --omap-key-file *file* ] *name* *key*	删除 omap 中的 key
getomapheader	getomapheader *name*	取 omap header 的十六进制值
setomapheader	setomapheader *name* *value*	设置 omap header
export	export *filename*	把池内容序列化到文件或 stdout
import	import [--dry-run] [--no-overwrite] < filename | -	从文件或 stdin 载入池内容

典型示例

# 集群与池利用率
rados df
rados lspools

# 列出对象
rados -p foo ls -
rados --pgid 0.6 ls
rados -p foo --all ls -

# 对象读写
rados -p foo put myobject blah.txt
rados -p foo get myobject /tmp/out.txt
rados -p foo stat myobject
rados -p foo rm myobject

# 池快照
rados -p foo mksnap mysnap
rados -p foo lssnap
rados -p foo -s mysnap get myobject blah.txt.old
rados -p foo rmsnap mysnap

# xattr / omap
rados -p foo setxattr myobject mykey myvalue
rados -p foo getxattr myobject mykey
rados -p foo listxattr myobject
rados -p foo setomapval myobject key1 val1
rados -p foo getomapval myobject key1
rados -p foo listomapvals myobject

# 压测：先写（不清数据），再顺序/随机读
rados -p foo bench 60 write --no-cleanup
rados -p foo bench 60 seq
rados -p foo bench 60 rand -t 32
rados -p foo cleanup

# 不一致对象排查
rados list-inconsistent-obj 0.6 --format=json-pretty

# 池导入导出
rados -p foo export /tmp/pool.export
rados -p foo import --dry-run /tmp/pool.export

注意事项 / 常见坑

• put 的警告（文档原文重点）：put 会创建单个 RADOS 对象，大小就等于你的输入文件。除非你的对象大小合理且一致，否则这可能不是你想要的——请考虑使用 RGW/S3、CephFS 或 RBD。
• bench 默认对象大小 4 MB，默认模拟线程数（并发写）16；-b objsize 只在 write 模式有效。
• write 和 seq 必须在同一台主机上运行，否则 write 创建的对象名会导致 seq 失败。
• 跑读压测（seq/rand）前，必须先跑带 --no-cleanup 的写压测。
• cleanup 的默认 --run-name 是 benchmark_last_metadata；bench 的 --run-name <label> 也是该默认值，多客户端压测同一负载时用它可以区分。
• --default 优先于 --all，即使 --all 在 CEPH_ARGS 里。
• listomapvals 的 value 以十六进制输出。
• --lock-cookie：cookie 非空时，lock break 必须带上同样的 cookie。

引自：rados

---

五、RBD

5.1 rbd

用途：管理 RADOS 块设备（RBD）镜像的工具，被 Linux rbd 驱动与 QEMU/KVM 的 rbd 存储驱动使用。

语法（synopsis，保留原文格式）：

rbd [ -c ceph.conf ] [ -m monaddr ] [--cluster cluster-name] [ -p | --pool pool ] [ command ... ]

常用选项表（全局 / 参数）

选项	参数	默认值	说明
-c ceph.conf, --conf ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor
--cluster cluster-name	集群名	ceph	使用非默认集群名
-p pool-name, --pool pool-name	池名	无（多数命令必需）	指定操作的池
--namespace namespace-name	namespace	无	使用池中预定义的 image namespace
--no-progress	—	无	不输出进度信息（默认某些命令输出到 stderr）
--image-format format-id	1 或 2	2	指定对象布局。format 1 已废弃（不支持克隆）；format 2 支持克隆，自 Bobtail 起 librbd 支持、内核 3.10 起内核 rbd 支持（"fancy" striping 需 4.17+）
-s size-in-M/G/T, --size size-in-M/G/T	大小	无	新建镜像的大小或已有镜像的新大小；不带后缀时默认单位 M
--object-size size-in-B/K/M	大小	4M（最小 4K，最大 32M）	对象大小，会向上取整到最接近的 2 的幂；不带后缀默认单位 B。可用配置项 rbd_default_order 改默认（默认对象大小 = 2^rbd_default_order）
--stripe-unit size-in-B/K/M	大小	等于 object size	条带单元大小；不带后缀默认单位 B
--stripe-count num	数量	1	回绕到第一个对象之前条带化的对象数
--snap snap	快照名	无	指定操作针对的快照
--id username	用户名（不含 client. 前缀）	无	用于 map 命令的用户名
--keyring filename	文件路径	默认 keyring 路径	含指定用户 secret 的 keyring 文件
--keyfile filename	文件路径	无	含 --id user secret key 的文件；若同时给了 --keyring，则被 --keyring 覆盖
--shared lock-tag	tag 字符串	无	用于 lock add：允许多个客户端用相同 tag 同时锁定同一镜像（如 VM 热迁移、集群文件系统场景）
--format format	plain / json / xml	plain	输出格式
--pretty-format	—	无	让 json/xml 输出更易读
-o krbd-options, --options krbd-options	逗号分隔选项串	无	通过 rbd 内核驱动映射/解映射时使用的选项（类似 mount(8) 的挂载选项）
--read-only	—	无	只读映射，等价于 -o ro
--image-feature feature-name	特性名（可重复）	无	创建时启用的 RBD format 2 特性
--image-shared	—	无	声明镜像将被多客户端并发使用，会禁用依赖独占所有权的功能
--whole-object	—	无	把 diff 限制在完整对象的范围内（开启 object-map 时可大幅提升 diff 性能）
--limit	数量	无	允许的快照数量上限

支持的 --image-feature：layering、striping、exclusive-lock、object-map（依赖 exclusive-lock）、fast-diff（依赖 object-map）、deep-flatten、journaling（依赖 exclusive-lock）、data-pool。

Spec 写法

image-spec      is [pool-name/[namespace-name/]]image-name
snap-spec       is [pool-name/[namespace-name/]]image-name@snap-name
group-spec      is [pool-name/[namespace-name/]]group-name
group-snap-spec is [pool-name/[namespace-name/]]group-name@snap-name
journal-spec    is [pool-name/[namespace-name/]]journal-name

• pool-name 默认 rbd，namespace-name 默认为空串。
• 若镜像名包含 / 字符，则 pool-name 是必需的。
• journal-name 就是 image-id。
• 也可以用 --pool、--namespace、--image、--snap 分别指定，但不推荐，优先用上面的 spec 语法。

命令表（按主题分组）

① 镜像基础：创建 / 列表 / 信息 / 删除 / 改名 / 扩容

命令	语法/要点	说明
create	create (-s|--size *size-in-M/G/T*) [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit ... --stripe-count ...] [--thick-provision] [--no-progress] [--image-feature *feature-name*]... [--image-shared] *image-spec*	创建新镜像，必须指定 --size；--stripe-unit 与 --stripe-count 可选但必须成对；--thick-provision 会在创建时全量预分配（耗时很长，需把整个镜像清零）
ls	ls [-l|--long] [*pool-name*]	列出 rbd_directory 对象中的镜像；-l 显示快照及更长格式（size、parent（若是克隆）、format 等）
info	info *image-spec* | *snap-spec*	显示镜像信息；克隆会显示父信息；指定快照时显示是否受保护
rm	rm *image-spec*	删除镜像（含所有数据块）；若存在快照则失败，且什么都不会删
mv	mv *src-image-spec* *dest-image-spec*	重命名镜像；不支持跨池
resize	resize (-s|--size *size-in-M/G/T*) [--allow-shrink] [--encryption-format ... --encryption-passphrase-file ...]... *image-spec*	调整大小；--allow-shrink 允许缩小
du	du [-p|--pool *pool-name*] [*image-spec*|*snap-spec*] [--merge-snapshots]	计算预分配与实际磁盘占用；--merge-snapshots 把快照占用并入父镜像
status	status *image-spec*	显示镜像状态，包括哪些客户端打开了它
sparsify	sparsify [--sparse-size *sparse-size*] *image-spec*	回收全零区域的空间；默认 sparse size 4096 字节，必须是 2 的幂、不小于 4096、不大于镜像 object size
bench	bench --io-type <read|write|readwrite|rw> [--io-size *size-in-B/K/M/G/T*] [--io-threads *num-ios-in-flight*] [--io-total *size-in-B/K/M/G/T*] [--io-pattern seq|rand] [--rw-mix-read *read proportion in readwrite*] *image-spec*	生成 I/O 并测量吞吐与延迟。默认：--io-size 4096、--io-threads 16、--io-total 1G、--io-pattern seq、--rw-mix-read 50；--io-size/--io-total 不带后缀默认单位 B
watch	watch *image-spec*	观察镜像上的事件

du 性能提示：若镜像未启用 fast-diff 特性，该操作需要向 OSD 查询镜像内每一个潜在对象。

② 快照 / 克隆

命令	语法	说明
snap create	snap create *snap-spec*	创建快照（必须指定快照名）
snap ls	snap ls *image-spec*	列出镜像快照
snap rename	snap rename *src-snap-spec* *dest-snap-spec*	重命名；不支持跨池、跨镜像
snap rm	snap rm [--force] *snap-spec*	删除快照
snap purge	snap purge *image-spec*	删除镜像上所有未受保护的快照
snap protect / unprotect	snap protect|unprotect *snap-spec*	保护/取消保护快照（克隆前必须 protect；若仍有克隆子镜像，unprotect 会失败）。需要 format 2
snap rollback	snap rollback *snap-spec*	把镜像内容回滚到快照
snap limit set / clear	snap limit set [--limit] *limit* *image-spec* / snap limit clear *image-spec*	设置/清除快照数量上限
clone	clone [--object-size ...] [--stripe-unit ... --stripe-count ...] [--image-feature ...] [--image-shared] *parent-snap-spec* *child-image-spec*	创建 COW 克隆；父快照必须受保护；对象大小默认与父一致，大小与父快照相同。需要 format 2
children	children *snap-spec*	列出该快照的克隆（会检查每个池，输出 poolname/imagename）。需要 format 2
flatten	flatten [--encryption-format ... --encryption-passphrase-file ...]... *image-spec*	把克隆从父快照复制所有共享块并独立；之后父快照可 unprotect 并删除（若无其他依赖克隆）。需要 format 2

③ 导入 / 导出 / 增量差异

命令	语法	说明
cp	cp (*src-image-spec*|*src-snap-spec*) *dest-image-spec*	复制内容到新镜像（大小、对象大小、format 相同）；不复制快照，需快照请用 deep cp
deep cp	deep cp (*src-image-spec*|*src-snap-spec*) *dest-image-spec*	深度复制，同 size/object-size/format 并包含快照
export	export [--export-format *format (1 or 2)*] (*image-spec*|*snap-spec*) [*dest-path*]	导出到路径（- 表示 stdout）；format 2 还会导出快照及 image_order、features 等属性
import	import [--export-format *format (1 or 2)*] [--image-format *format-id*] [--object-size ...] [--stripe-unit ... --stripe-count ...] [--image-feature ...]... [--image-shared] *src-path* [*image-spec*]	从路径导入（- 表示 stdin）；尽可能创建 sparse 镜像；从 stdin 导入时稀疏化单位为目标镜像的 data block size（object size）
diff	diff [--from-snap *snap-name*] [--whole-object] *image-spec*|*snap-spec*	输出自起始快照（或创建以来）发生变化的字节区间；每行含起始偏移、长度、以及 zero/data
export-diff	export-diff [--from-snap *snap-name*] [--whole-object] (*image-spec*|*snap-spec*) *dest-path*	导出增量差异（- 表示 stdout）；结束快照用 --snap 或 @snap 指定
import-diff	import-diff *src-path* *image-spec*	应用增量差异；若差异基于某个起始快照会先校验其存在，若有结束快照则校验其不存在并在完成后创建
merge-diff	merge-diff *first-diff-path* *second-diff-path* *merged-diff-path*	合并两段连续增量差异；首段结束快照必须等于次段起始快照；first/merged 可用 -；当前仅支持 stripe-count == 1 的源增量差异

④ 设备映射（device）

命令	语法	说明
device list	device list [-t|--device-type *device-type*] [--format plain|json|xml] --pretty-format	显示已映射的镜像（默认 rbd 内核模块，或 nbd/ubbd（Linux）、ggate（FreeBSD））
device map	device map [-t|--device-type *device-type*] [--cookie *device-cookie*] [--show-cookie] [--snap-id *snap-id*] [--read-only] [--exclusive] [-o|--options *device-options*] *image-spec*|*snap-spec*	映射为块设备
device unmap	device unmap [-t|--device-type *device-type*] [-o|--options *device-options*] [--snap-id *snap-id*] *image-spec*|*snap-spec*|*device-path*	解映射
device attach	device attach [-t|--device-type *device-type*] --device *device-path* [--cookie ...] [--show-cookie] [--snap-id ...] [--read-only] [--exclusive] [--force] [-o|--options ...] *image-spec*|*snap-spec*	把镜像挂到指定块设备（目前仅 Linux 的 nbd）。不安全，通常不应使用：指定错镜像或错设备可能导致数据损坏，因为 nbd 内核驱动不做校验
device detach	device detach [-t|--device-type *device-type*] [-o|--options ...] [--snap-id ...] *image-spec*|*snap-spec*|*device-path*	分离已映射/挂接的设备（目前仅 Linux 的 nbd）。不安全，通常不应使用

--options 是逗号分隔的设备类型专有选项串（opt1,opt2=val,...）。

⑤ group（一致性组）

命令	语法	说明
group create	group create *group-spec*	创建组
group ls	group ls [-p|--pool *pool-name*]	列出组
group rename	group rename *src-group-spec* *dest-group-spec*	重命名（不支持跨池）
group rm	group rm *group-spec*	删除组
group image add / list / remove	group image add|list|remove *group-spec* [*image-spec*]	组中增删/列出镜像
group snap create / list / info / rm / rename / rollback	group snap ... *group-snap-spec* 等	组快照的创建/列出/信息/删除/改名/回滚

⑥ mirror（镜像复制 / 灾备）

命令	语法	说明
mirror pool enable	mirror pool enable *pool-name* *mode* [--remote-namespace *remote-namespace-name*]	在池/namespace 上启用镜像；mode = pool 或 image；--remote-namespace 可镜像到远端池的不同 namespace
mirror pool disable	mirror pool disable [*pool-name*]	关闭；同时会关闭该池/namespace 内所有镜像（默认或显式启用的）
mirror pool info	mirror pool info [*pool-name*]	显示镜像配置（mode、mirror UUID、remote namespace；池还含 site name、peer UUID、远端集群名与客户端名）
mirror pool status	mirror pool status [--verbose] [*pool-name*]	显示池/namespace 内所有镜像的状态
mirror pool promote / demote	mirror pool promote|demote [--force] [*pool-name*]	把所有镜像提升/降级为 primary/non-primary
mirror pool peer add	mirror pool peer add [*pool-name*] *remote-cluster-spec*	添加 peer；remote-cluster-spec = [*remote client name*@]*remote cluster name*，远端客户端名默认 client.admin`。要求池已启用镜像
mirror pool peer remove	mirror pool peer remove [*pool-name*] *uuid*	移除 peer（UUID 见 mirror pool info）
mirror pool peer set	mirror pool peer set [*pool-name*] *uuid* *key* *value*	修改 peer 设置；key 可为 client 或 cluster
mirror image enable	mirror image enable *image-spec* *mode*	为镜像启用镜像；mode 可为 journal（默认，需 journaling 特性）或 snapshot
mirror image disable	mirror image disable [--force] *image-spec*	关闭镜像的镜像功能
mirror image promote / demote	mirror image promote|demote [--force] *image-spec*	提升/降级
mirror image resync	mirror image resync *image-spec*	强制重新同步到 primary
mirror image status	mirror image status *image-spec*	显示镜像状态
mirror snapshot schedule add	mirror snapshot schedule add [-p|--pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]	添加快照调度；interval 可用 d/h/m 后缀；start-time 为 ISO 8601 时间串；都不指定则为全局调度
mirror snapshot schedule list	... list [-R|--recursive] [--format *format*] [--pretty-format] [-p|--pool ...] [--namespace ...] [--image ...]	列出调度
mirror snapshot schedule remove	... remove [-p|--pool ...] [--namespace ...] [--image ...] *interval* [*start-time*]	删除调度
mirror snapshot schedule status	... status [-p|--pool ...] [--format ...] [--pretty-format] [--namespace ...] [--image ...]	显示调度状态

⑦ trash（回收站 / 延迟删除）

命令	语法	说明
trash ls	trash ls [*pool-name*]	列出回收站条目
trash mv	trash mv [--expires-at <expires-at>] *image-spec*	移入回收站（即使正被克隆使用也可以）；--expires-at 设置何时起允许被删除
trash restore	trash restore *image-id*	恢复
trash rm	trash rm [--force] *image-id*	删除；延迟时间未过可用 --force。正被克隆使用或含有快照的镜像不能被删除
trash purge	trash purge [*pool-name*]	清除所有已过期的镜像
trash purge schedule add/list/remove/status	trash purge schedule ... [-p|--pool *pool*] [--namespace *namespace*] *interval* [*start-time*]	定时清理调度（list 支持 -R|--recursive、--format、--pretty-format）

⑧ 其他：namespace / config / meta / 特性 / 加密 / 迁移 / journal / lock / object-map / pool init

命令	语法	说明
namespace create / list / remove	namespace create *pool-name*/*namespace-name*、namespace list *pool-name*、namespace remove *pool-name*/*namespace-name*	创建/列出/删除 namespace（remove 只删空 namespace）
pool init	pool init [*pool-name*] [--force]	初始化池以供 RBD 使用；新建的池使用前必须先初始化
config global get/list/set/remove	config global ... *config-entity* *key* [*value*]	global 级配置覆盖（list 支持 --format plain|json|xml 与 --pretty-format）
config pool get/list/set/remove	config pool ... *pool-name* *key* [*value*]	pool 级配置覆盖
config image get/list/set/remove	config image ... *image-spec* *key* [*value*]	image 级配置覆盖
image-meta get/list/remove/set	image-meta ... *image-spec* [*key*] [*value*]	镜像元数据；list 第一列 key、第二列 value
feature enable / disable	feature enable|disable *image-spec* *feature-name*...	启用/禁用特性（可指定多个）
encryption format	encryption format *image-spec* *format* *passphrase-file* [--cipher-alg *alg*]	把镜像格式化为加密格式；此前写入的所有数据将不可读。支持格式 luks1、luks2；算法 aes-128、aes-256（默认）
object-map check / rebuild	object-map check|rebuild *image-spec*|*snap-spec*	校验/重建 object map
journal client disconnect	journal client disconnect *journal-spec*	把镜像 journal 客户端标记为断开
journal export / import	journal export [--verbose] [--no-error] *src-journal-spec* *path-name* / journal import ... *path-name* *dest-journal-spec*	导出/导入 journal（- 表示 stdout/stdin）；适合在危险操作前备份
journal info / inspect / reset / status	journal info|inspect|reset|status *journal-spec*	信息 / 结构错误检查 / 重置 / 状态
lock add / ls / rm	lock add [--shared *lock-tag*] *image-spec* *lock-id / lock ls *image-spec* / lock rm *image-spec* *lock-id* *locker*	加/列/解镜像锁。默认排他锁（已锁定则失败）；--shared 用相同 tag 可多客户端共享。加锁不影响任何其他操作，也不保护镜像不被删除
migration prepare	migration prepare [--order *order*] [--object-size ...] [--image-feature ...] [--image-shared] [--stripe-unit ...] [--stripe-count ...] [--data-pool *data-pool*] [--import-only] [--source-spec *json*] [--source-spec-path *path*] *src-image-spec* [*dest-image-spec*]	迁移第一步（改变位置/format 等不能动态改的参数）；目标可与源相同（此时可省略 dest）；完成后源成为目标的父，目标以 COW 方式可访问。--import-only + --source-spec/--source-spec-path 可从只读导入源迁移
migration execute	migration execute *image-spec*	第二步：拷贝数据到目标
migration commit	migration commit *image-spec*	第三步：删除源镜像数据
migration abort	migration abort *image-spec*	取消迁移，回到初始状态；对目标镜像的所有修改都会丢失

Kernel rbd（krbd）选项

Per client instance（rbd device map 时）：

选项	说明
fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee	客户端应采用的 FSID
ip=a.b.c.d[:p]	客户端使用的 IP（及可选端口）
share / noshare	启用（默认）/禁用 与其他映射共享客户端实例
crc / nocrc	对 msgr1 启用（默认）/禁用 CRC32C 校验。msgr2.1 会忽略：'crc' 模式始终全校验，'secure' 模式始终不校验；nocrc 只关闭 payload 校验，header 校验始终开
cephx_require_signatures / nocephx_require_signatures	要求/不要求 msgr1 消息签名（自 3.19，默认要求；已废弃，将来会移除）
tcp_nodelay / notcp_nodelay	关闭（自 4.0，默认）/启用 Nagle 算法
cephx_sign_messages / nocephx_sign_messages	对 msgr1 启用（自 4.4，默认）/禁用 消息签名；msgr2.1 会忽略
mount_timeout=x	map/unmap 各步骤的超时（默认 60 秒）；自 4.2 起可保证断网时 unmap 最终超时退出
osdkeepalive=x	OSD keepalive 超时（默认 5 秒）
osd_idle_ttl=x	OSD idle TTL（默认 60 秒）

Per mapping（块设备级）：

选项	说明
rw / ro	读写（默认，被 --read-only 覆盖）/只读（等价 --read-only）
queue_depth=x	队列深度（自 4.2，默认 128）
lock_on_read	读时也获取排他锁（自 4.9）
exclusive	禁用自动排他锁切换（自 4.12），等价 --exclusive
lock_timeout=x	等待获取排他锁的超时（自 4.17，默认 0 秒=不超时）
notrim	关闭 discard 与 write zeroes 卸载（自 4.17）；discard 将返回 -EOPNOTSUPP，write zeroes 回退为手工清零
abort_on_full	集群满或数据池达配额时以 -ENOSPC 让写失败（自 5.0）；默认是阻塞直到 full 解除
alloc_size	底层 OSD 对象存储的最小分配单元（自 5.1，默认 64K），用于取整并丢弃过小的 discard。bluestore 推荐设为 bluestore_min_alloc_size（当前所有类型设备均为 4K）；filestore 且 filestore_punch_hole = false 时推荐设为镜像 object size（通常 4M）
crush_location=x	客户端在 CRUSH 层级中的位置（自 5.8）；| 分隔键值对、: 分隔键值，如 crush_location=rack:myrack|datacenter:mydc|region:myregion；支持"多路径"
read_from_replica=no|balance|localize	不使用副本读（自 5.8，默认）/随机挑 acting set 中的 OSD/挑最"本地"的 OSD
compression_hint=none|compressible|incompressible	压缩提示（自 5.8，默认 none）
ms_mode=legacy|crc|secure|prefer-crc|prefer-secure	传输协议与模式（自 5.11；默认 prefer-crc）。secure 提供完整传输中加密；*-crc/*-secure 被拒时会退让
rxbounce	接收数据时使用 bounce buffer（自 5.17）；目标是避免非稳定目标缓冲区带来的 crc/完整性错误
udev / noudev	等待（默认）/不等待 udev 执行完匹配规则。该选项不会传给内核

rbd device unmap 选项：force（自 4.9，强制解映射已打开的设备）、udev / noudev（同上，默认 udev）。

典型示例

# 创建与查看
rbd create mypool/myimage --size 102400
rbd create mypool/myimage --size 102400 --object-size 8M
rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
rbd ls -l mypool
rbd info mypool/myimage
rbd du mypool/myimage
rbd status mypool/myimage
rbd rm mypool/myimage

# 快照与克隆
rbd snap create mypool/myimage@mysnap
rbd snap ls mypool/myimage
rbd snap protect mypool/myimage@mysnap
rbd clone mypool/myimage@mysnap otherpool/cloneimage
rbd children mypool/myimage@mysnap
rbd flatten otherpool/cloneimage
rbd snap unprotect mypool/myimage@mysnap
rbd snap rm mypool/myimage@mysnap
rbd snap rollback mypool/myimage@mysnap

# 导入导出与增量
rbd export mypool/myimage@snap /tmp/img
rbd import --image-format 2 /tmp/img mypool/myimage2
rbd export-diff mypool/myimage@snap1 --from-snap snap0 /tmp/diff1
rbd import-diff /tmp/diff1 mypool/otherimage
rbd merge-diff /tmp/diff1 /tmp/diff2 /tmp/diff_merged

# 映射与卸载
rbd device map mypool/myimage --id admin --keyfile secretfile
rbd device map mypool/myimage --cluster cluster-name
rbd device map mypool/myimage --read-only
rbd device map mypool/myimage -o queue_depth=1024,lock_on_read
rbd device list
rbd device unmap /dev/rbd0
rbd device unmap mypool/myimage -o force

# namespace / pool init / feature
rbd pool init mypool
rbd namespace create mypool/ns1
rbd namespace list mypool
rbd feature enable mypool/myimage exclusive-lock object-map fast-diff
rbd feature disable mypool/myimage journaling

# 加密
rbd encryption format mypool/myimage luks2 /etc/luks/passphrase --cipher-alg aes-256

# 镜像复制（mirroring）
rbd mirror pool enable mypool pool
rbd mirror pool peer add mypool client.admin@remote-cluster
rbd mirror pool status mypool --verbose
rbd mirror image enable mypool/myimage snapshot
rbd mirror snapshot schedule add --pool mypool --image myimage 12h 14:00:00-05:00

# 回收站
rbd trash mv mypool/myimage --expires-at "tomorrow"
rbd trash ls mypool
rbd trash restore mypool/myimage-id
rbd trash restore mypool/myimage-id --image mynewimage
rbd trash rm mypool/myimage-id --force
rbd trash purge mypool

# 迁移
rbd migration prepare mypool/src mypool/dst
rbd migration execute mypool/dst
rbd migration commit mypool/dst
# 出问题可回滚
rbd migration abort mypool/dst

# 锁
rbd lock add mypool/myimage mylockid
rbd lock ls mypool/myimage
rbd lock remove mypool/myimage mylockid client.2485

# I/O 压测
rbd bench --io-type write --io-total 1G --io-threads 16 mypool/myimage
rbd bench --io-type rand --io-pattern rand --io-size 4K mypool/myimage

注意事项 / 常见坑

• 镜像名含 / 时必须显式写 pool-name。
• rbd rm 在镜像存在快照时会失败且什么都不删——先清快照或先 trash mv。
• 克隆相关（clone/children/flatten/snap protect）都要求 image format 2；clone 前父快照必须 snap protect。
• snap unprotect 在仍有克隆子镜像时失败，且克隆可能在别的池里。
• --stripe-unit 与 --stripe-count 必须成对使用。
• --thick-provision 需要把整个镜像清零，创建会很慢。
• 跨池 rename（mv、group rename）不支持；快照 rename 不支持跨池跨镜像。
• du 在未启用 fast-diff 时要遍历所有潜在对象，代价很高。
• merge-diff 当前只支持 stripe-count == 1 的源增量差异。
• device attach / device detach 文档明确标注不安全、通常不应使用（nbd 内核驱动不做校验，选错镜像/设备会损坏数据）。
• lock add 只是加个标记：不影响任何其他操作，也不能保护镜像不被删除。
• read_from_replica=balance|localize 只有 Octopus 之后（即执行过 ceph osd require-osd-release octopus）才对通用场景安全，否则仅限只读负载（如到处只读映射的镜像或快照）。
• migration abort 会丢失对目标镜像的所有修改。
• 新建的池在使用 RBD 前必须先 rbd pool init。
• trash rm 不能删除正被克隆使用或含快照的镜像；--force 也只能越过"延迟时间未过"这一限制。
• encryption format 会让此前写入的数据不可读。

引自：rbd

---

5.2 rbd-fuse

用途：RBD 镜像的 FUSE 客户端——把一个含 rbd 镜像的池挂载为用户态文件系统，让镜像在挂载点下像普通文件一样可访问。

语法（synopsis，保留原文格式）：

rbd-fuse [ -p pool ] [-c conffile] mountpoint [ fuse options ]

常用选项表

选项	参数	默认值	说明
-c ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-p pool	池名	rbd	指定搜索 rbd 镜像的池

任何 rbd-fuse 不认识的选项都会被转交给 libfuse。

典型示例

# 挂载默认 rbd 池
rbd-fuse /mnt/rbd

# 指定池与配置文件
rbd-fuse -p mypool -c /etc/ceph/foo.conf /mnt/rbd

# 卸载
fusermount -u /mnt/rbd
# 或向 rbd-fuse 进程发 SIGINT

注意事项 / 常见坑

• 不推荐用于任何生产或高性能负载（文档原文明确）。
• 卸载方式：fusermount -u mountpoint，或向 rbd-fuse 进程发送 SIGINT。

引自：rbd-fuse

---

5.3 rbd-nbd

用途：把 RBD 镜像映射到 nbd（Network Block Device） 设备，从而像本地块设备一样访问。

语法（synopsis，保留原文格式）：

rbd-nbd [-c conf] [--read-only] [--device nbd device] [--snap-id snap-id] [--nbds_max limit] [--max_part limit] [--exclusive] [--notrim] [--encryption-format format] [--encryption-passphrase-file passphrase-file] [--io-timeout seconds] [--reattach-timeout seconds] map image-spec | snap-spec
rbd-nbd unmap nbd device | image-spec | snap-spec
rbd-nbd list-mapped
rbd-nbd attach --device nbd device image-spec | snap-spec
rbd-nbd detach nbd device | image-spec | snap-spec

常用选项表

选项	参数	默认值	说明
-c ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
--read-only	—	无	只读映射
--device *nbd device*	设备路径	无	指定 nbd 设备
--snap-id *snapid*	快照 ID	无	用 ID（而非名字）指定要 map/unmap/attach/detach 的快照
--nbds_max *limit*	数量	无	覆盖 nbd 内核模块的 nbds_max 参数（modprobe 时），限制 nbd 设备数量
--max_part *limit*	数量	无	覆盖模块参数 max_part
--exclusive	—	无	禁止其他客户端写入
--notrim	—	无	关闭 trim/discard
--encryption-format	luks / luks1 / luks2	无	镜像加密格式
--encryption-passphrase-file	文件路径	无	含解锁镜像加密口令的文件路径
--io-timeout *seconds*	秒	Linux 内核默认 30 秒 请求超时	覆盖设备超时
--reattach-timeout *seconds*	秒	30 秒	旧进程 detach 后内核等待新 rbd-nbd 进程 attach 的超时

Image / snap spec

image-spec is [pool-name]/image-name
snap-spec  is [pool-name]/image-name@snap-name

• pool-name 默认 rbd；镜像名含 / 时必须显式给出 pool-name。

典型示例

# 映射
rbd-nbd map mypool/myimage
rbd-nbd map mypool/myimage --read-only
rbd-nbd map mypool/myimage --device /dev/nbd0
rbd-nbd map mypool/myimage --exclusive --notrim

# 映射加密镜像
rbd-nbd map mypool/myimage --encryption-format luks2 \
  --encryption-passphrase-file /etc/luks/passphrase

# 查看 / 卸载
rbd-nbd list-mapped
rbd-nbd unmap /dev/nbd0
rbd-nbd unmap mypool/myimage

# 热插拔式 attach/detach
rbd-nbd attach --device /dev/nbd0 mypool/myimage
rbd-nbd detach /dev/nbd0

注意事项 / 常见坑

• --io-timeout 不设时，Linux 内核默认请求超时为 30 秒。
• --reattach-timeout 默认 30 秒，用于旧进程退出后内核等待新进程接管的窗口。

引自：rbd-nbd

---

5.4 rbd-ggate

用途：把 RBD 镜像映射到 ggate（FreeBSD GEOM Gate class） 设备，供 FreeBSD 上像本地块设备一样访问。

语法（synopsis，保留原文格式）：

rbd-ggate [--read-only] [--exclusive] [--device ggate device] map image-spec | snap-spec
rbd-ggate unmap ggate device
rbd-ggate list

命令表

命令	说明
map	派生一个进程，负责创建 ggate 设备并在 GEOM Gate 内核子系统与 RADOS 之间转发 I/O 请求
unmap	销毁 ggate 设备并终止负责它的进程
list	列出已映射的 ggate 设备

常用选项表

选项	参数	默认值	说明
--device *ggate device*	设备路径	无	指定 ggate 设备路径
--read-only	—	无	只读映射
--exclusive	—	无	禁止其他客户端写入

Image / snap spec

image-spec is [pool-name]/image-name
snap-spec  is [pool-name]/image-name@snap-name

• pool-name 默认 rbd；镜像名含 / 时必须显式给出 pool-name。

典型示例

# 映射
rbd-ggate map mypool/myimage
rbd-ggate map mypool/myimage --read-only
rbd-ggate map mypool/myimage --device /dev/ggate0 --exclusive

# 查看 / 卸载
rbd-ggate list
rbd-ggate unmap /dev/ggate0

注意事项 / 常见坑

• 仅适用于 FreeBSD（GEOM Gate）。
• unmap 只接受 ggate device 参数（不像 rbd-nbd 还接受 image-spec）。

引自：rbd-ggate

---

5.5 rbdmap

用途：一个 shell 脚本，自动对一个或多個 RBD 镜像执行 rbd map / rbd unmap；主要用途是开机自动映射并挂载（关机时反向执行），由 init 系统（systemd 单元 rbdmap.service，随 ceph-common 包提供）触发。

语法（synopsis，保留原文格式）：

rbdmap map
rbdmap unmap

常用选项表

选项	参数	默认值	说明
（无）	—	—	Options: None（文档原文明确写 None）
环境变量 RBDMAPFILE	文件路径	/etc/ceph/rbdmap	覆盖默认配置文件路径

配置文件格式：

IMAGESPEC RBDOPTS

• IMAGESPEC：POOLNAME/IMAGENAME，或只写 IMAGENAME（此时 POOLNAME 默认为 rbd）。
• RBDOPTS：可选，逗号分隔的 PARAM1=VAL1,PARAM2=VAL2,...，会传给底层 rbd map。
• 参数或值中含逗号或等号时，可用单引号避免被替换。

典型示例

# /etc/ceph/rbdmap 内容示例（三个镜像，位于 foopool）
cat > /etc/ceph/rbdmap <<'EOF'
foopool/bar1    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
foopool/bar2    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
foopool/bar3    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring,options='lock_on_read,queue_depth=1024'
EOF

# 上面内容会被转换为：
# rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
# rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
# rbd map foopool/bar3 --id admin --keyring /etc/ceph/ceph.client.admin.keyring --options lock_on_read,queue_depth=1024

# 对应的 /etc/fstab（XFS 示例）
cat >> /etc/fstab <<'EOF'
/dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0
/dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0
/dev/rbd/foopool/bar3 /mnt/bar3 xfs noauto 0 0
EOF

# 手动执行
rbdmap map
rbdmap unmap

# 开机自启
systemctl enable rbdmap.service

注意事项 / 常见坑

• 挂载/卸载要成功，友好设备名必须有对应的 /etc/fstab 条目。
• 写 /etc/fstab 条目时建议加 noauto（或 nofail），避免 init 系统在设备还不存在时就尝试挂载（rbdmap.service 执行的是 shell 脚本，通常在启动序列中触发得很晚）。
• rbd map 成功后镜像映射为 /dev/rbdX，随后 udev 规则创建友好符号链接 /dev/rbd/POOLNAME/IMAGENAME 指向真实设备。
• rbdmap unmap-all（文档在 Description 中提到）会卸载并解映射当前所有已映射的 RBD 镜像，无论是否在配置文件中列出。

引自：rbdmap

---

5.6 rbd-replay

用途：重放 RBD 工作负载的工具。

语法（synopsis，保留原文格式）：

rbd-replay [ options ] replay_file

常用选项表

选项	参数	默认值	说明
-c ceph.conf, --conf ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-p pool, --pool pool	池名	rbd	操作的池
--latency-multiplier	倍数	1	请求间隔延迟的倍率
--read-only	—	无	只重放非破坏性请求
--map-image rule	image1@snap1=image2@snap2 形式的规则	无	把 trace 中的镜像名映射到重放集群中的镜像名（可把 image1 的 snap1 映射到 image2 的 snap2）
--dump-perf-counters	—	无	实验性：在镜像关闭前把性能计数器输出到 stdout；多个镜像关闭或同一镜像多次开关会输出多次；计数器的含义可能随版本变化

典型示例

# 尽可能快地重放（间隔归零）
rbd-replay --latency-multiplier=0 workload1

# 把 prod_image 换成 test_image 来重放
rbd-replay --map-image=prod_image=test_image workload1

# 只重放非破坏性请求，指定池
rbd-replay -p mypool --read-only workload1

# 导出性能计数器（实验性）
rbd-replay --dump-perf-counters workload1

注意事项 / 常见坑

• --dump-perf-counters 标记为 Experimental，计数器含义可能随版本变化。
• 重放前通常要先用 rbd-replay-prep 处理原始 trace。

引自：rbd-replay

---

5.7 rbd-replay-prep

用途：把原始 RBD trace 处理成可供 rbd-replay 重放的格式。

语法（synopsis，保留原文格式）：

rbd-replay-prep [ --window seconds ] [ --anonymize ] trace_dir replay_file

常用选项表

选项	参数	默认值	说明
--window seconds	秒	无	相隔超过 seconds 秒的请求被视为相互独立
--anonymize	—	无	对镜像名与快照名做匿名化
--verbose	—	无	把所有处理过的事件打印到控制台

典型示例

# 准备 workload1-trace 用于重放
rbd-replay-prep workload1-trace/ust/uid/1000/64-bit workload1

# 匿名化 + 详细输出
rbd-replay-prep --anonymize --verbose --window 5 workload1-trace/ust/uid/1000/64-bit workload1

注意事项 / 常见坑

• 无。文档未列出其他限制。

引自：rbd-replay-prep

---

5.8 rbd-replay-many

用途：在多个客户端上重放同一个 RBD 工作负载的工具；所有客户端使用相同负载，但各自针对不同的镜像重放（符合 librbd 的典型用法：每个原始客户端是一个有自己镜像的 VM）。

语法（synopsis，保留原文格式）：

rbd-replay-many [ options ] --original-image name host1 [ host2 [ ... ] ] -- rbd_replay_args

常用选项表

选项	参数	默认值	说明
--original-image name	镜像名（可含 snap）	无（必需）	原始被 trace 的镜像名与 snap，用于正确做名字映射
--image-prefix prefix	前缀	原始镜像名	重放目标镜像名的前缀；--image-prefix=foo 会让客户端分别重放到 foo-0、foo-1 等
--exec program	路径	无	rbd-replay 可执行文件的路径
--delay seconds	秒	0	启动每个客户端之间的间隔

典型示例

# 在两台主机上重放
rbd-replay-many host-0 host-1 --original-image=image -- -c ceph.conf replay.bin

# 上面这行实际会执行：
# ssh host-0 'rbd-replay' --map-image 'image=image-0' -c ceph.conf replay.bin
# ssh host-1 'rbd-replay' --map-image 'image=image-1' -c ceph.conf replay.bin

# 指定镜像前缀、错开启动
rbd-replay-many --image-prefix=vmimg --delay 5 host-0 host-1 host-2 \
  --original-image=image -- -c ceph.conf replay.bin

注意事项 / 常见坑

• 配置文件与重放文件不会自动复制到客户端，需自行分发。
• 重放用的镜像必须已经存在，该工具不会创建。

引自：rbd-replay-many

---

5.9 rbdnamer

用途：udev 辅助工具——针对给定的 RBD 设备，把 pool、namespace、image 与 snapshot 名字打到 stdout，供 udev 设备管理器创建 RBD 设备符号链接使用（相应 udev 规则由 50-rbd.rules 提供）。

语法（synopsis，保留原文格式）：

ceph-rbdnamer num

💡 补充：源文件名是 ceph-rbdnamer.rst，但文档标题与程序名均为 rbdnamer（.. program:: ceph-rbdnamer 的声明与正文一致指向该 udev helper；实际安装的二进制名在不同发行版/版本上可能带或不带 ceph- 前缀，文档未明确）。

常用选项表

选项	参数	默认值	说明
（无）	num（RBD 设备号）	—	文档未列出任何命令行选项；只接受设备编号参数

典型示例

# udev 内部调用（示例）
ceph-rbdnamer 0

# udev 规则文件
cat /usr/lib/udev/rules.d/50-rbd.rules

注意事项 / 常见坑

• 这是给 udev 调用的辅助程序，通常不由人手直接执行。
• 它输出 pool/namespace/image/snapshot 名，用于生成 /dev/rbd/<pool>/<image> 之类的友好符号链接（参见 rbdmap 章节）。

引自：rbdnamer

---

六、CephFS

6.1 ceph-fuse

用途：Ceph 分布式文件系统的 FUSE（用户态文件系统）客户端，把 -m 指定或 ceph.conf 描述的 Ceph 文件系统挂载到指定挂载点。

语法（synopsis，保留原文格式）：

ceph-fuse [-n client.username] [ -m monaddr:port ] mountpoint [ fuse options ]

常用选项表

选项	参数	默认值	说明
-o opt,[opt...]	逗号分隔挂载选项串	无	挂载选项
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor
-n client.{cephx-username}	完整用户名	无	指定挂载用 secret key 所属的 CephX 用户
--id <client-id>	id	无	同上，但只给 ID 部分（如 --id 0 → client.0）
-k <path-to-keyring>	文件路径	标准位置	keyring 不在标准位置时指定路径
--client_mountpoint / -r root_directory	目录	无	把 root_directory 作为挂载根，而非整个 Ceph 树
-f	—	无	前台运行，不 daemonize，不生成 pid 文件
-d	—	无	前台运行，日志全输出到 stderr 并启用 FUSE 调试（等价 -o debug）
-s	—	无	禁用多线程操作
--client_fs	FS 名	集群上的默认 CephFS	指定要挂载的 Ceph FS 名

任何 ceph-fuse 不认识的选项都会被转交给 libfuse。

典型示例

# 挂载默认文件系统
ceph-fuse /mnt/mycephfs

# 指定 monitor 与用户
ceph-fuse -m 192.168.0.1:6789 /mnt/mycephfs
ceph-fuse -n client.foo /mnt/mycephfs
ceph-fuse --id 0 /mnt/mycephfs

# 指定文件系统与子目录作为根
ceph-fuse --client_fs myfs2 -r /some/dir /mnt/mycephfs

# 使用非标准位置的 keyring
ceph-fuse -k /etc/ceph/client.foo.keyring --id foo /mnt/mycephfs

# 前台 + 调试
ceph-fuse -d /mnt/mycephfs

# 卸载
fusermount -u /mnt/mycephfs
# 或向 ceph-fuse 进程发 SIGINT

注意事项 / 常见坑

• 卸载用 fusermount -u mountpoint，或向进程发 SIGINT。
• 不指定 --client_fs 时挂载集群上的默认 CephFS。

引自：ceph-fuse

---

6.2 mount.ceph

用途：在 Linux 主机上挂载 Ceph 文件系统的挂载助手——负责把 monitor 主机名解析为 IP、从磁盘读取认证密钥；真正的工作由 Linux 内核客户端完成。

语法（synopsis，保留原文格式）：

mount.ceph name@fsid.fs_name=/[subdir] dir [-o options ]

基本选项表

选项	参数	默认值	说明
conf	文件路径	ceph.conf 的标准搜索路径	指定 ceph.conf 路径，用于初始化 Ceph 上下文以自动发现 monitor 地址与认证 secret
mount_timeout	int（秒）	60	挂载超时
ms_mode=<legacy|crc|secure|prefer-crc|prefer-secure>	模式	无	客户端传输连接模式：legacy=messenger v1；crc=v2 不加密；secure=v2 加密；prefer-crc=crc 被拒则同意 secure；prefer-secure=secure 被拒则同意 crc
mon_addr	ip_address[:port]，多个用 / 分隔	端口默认 6789	monitor 地址；只需一个可用即可挂载（客户端会从任一响应者学到全部 monitor），但建议多写几个
fsid	集群 FSID	无	可用 ceph fsid 查到
secret	secret key	无	CephX secret。不安全（会暴露在命令行/历史里），请改用 secretfile
secretfile	文件路径	无	含 secret key 的文件路径（推荐）
recover_session=<no|clean>	no / clean	no	客户端被 blocklist 后的自动重连模式。no=永不尝试重连，被 blocklist 的客户端操作会失败；clean=自动重连，重连时丢弃脏数据/元数据、失效 page cache 与可写文件句柄，重连后文件锁变为 stale（inode 上有 stale 锁时禁止读写，直到应用释放）
fs=<fs-name>	FS 名	无	使用旧语法时指定要挂载的非默认文件系统
mds_namespace=<fs-name>	FS 名	无	fs= 的同义词（已废弃）

高级选项表

选项	参数	默认值	说明
cap_release_safety	int	calculated	—
caps_wanted_delay_max	int（cap 释放延迟）	60	—
caps_wanted_delay_min	int（cap 释放延迟）	5	—
dirstat / nodirstat	—	off	启用/禁用用 cat dirname 查看目录统计（统计是惰性更新的，变更后可能有一段时间是旧的）
ip	IP	无	my ip
noasyncreaddir	—	无	不使用 dcache readdir
nocrc	—	无	写时不做数据 crc
noshare	—	无	创建新的客户端实例，而不是共享挂载同一集群的既有实例
osdkeepalive	int	5	—
osd_idle_ttl	int（秒）	60	—
rasize	int（字节）	8388608（8192*1024）	最大 readahead
rbytes / norbytes	—	off	报告/不报告目录内容的递归大小作为 st_size
readdir_max_bytes	int	524288（512*1024）	—
readdir_max_entries	int	1024	—
rsize	int（字节）	16777216（16M）	最大读大小
snapdirname	string	.snap	隐藏 snapdir 的名字
write_congestion_kb	int（KB）	由可用内存推算	最大在途 writeback
wsize	int（字节）	16777216（16M）	最大写大小（writeback 取 wsize 与 stripe unit 的较小者）
wsync / nowsync	—	自内核 5.16 起默认 nowsync	wsync=所有命名空间操作同步执行（等 MDS 回复才完成）；nowsync=允许异步（有足够 capability 时可在 MDS 回复前完成）
crush_location=x	key:value 对，| 分隔	无（自 5.8）	客户端在 CRUSH 层级中的位置，如 crush_location=rack:myrack|datacenter:mydc|region:myregion；支持"多路径"
read_from_replica=<no|balance|localize>	模式	no（自 5.8）	no=禁用副本读，总是选 primary；balance=从 PG acting set 随机挑 OSD；localize=挑最"本地"的 OSD（按 crush_location 计算，最低层级 bucket 类型匹配者胜）

典型示例

# 挂载整个文件系统（推荐通过 mount(8) 调用，FSID 由 helper 从 ceph.conf 补全）
mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs

# 只挂载命名空间的一部分
mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs

# 指定 monitor（可带端口）
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000

# 多个 monitor 用 / 分隔
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1/192.168.0.2/192.168.0.3

# 传 secret（不推荐，会留在 shell 历史里）
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==

# 推荐：用 secretfile
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secretfile=/etc/ceph/fs_username.secret

# 集群未启用认证时省略凭据相关选项
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs

# 旧语法
mount -t ceph 192.168.0.1:/ /mnt/mycephfs

# 带 FSID 的完整形式
mount.ceph name@07fe3187-00d9-42a3-814b-72a4d5e7d5be.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4

# 副本读优化 + 客户端位置声明
mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs \
  -o mon_addr=192.168.0.1,crush_location=rack:myrack|datacenter:mydc,read_from_replica=localize

注意事项 / 常见坑

• 设备串里的点 . 不能省：推荐写法 mount -t ceph name@.fs_name=/ /mnt/...，FSID 会被 mount helper 从 ceph 配置文件补齐。
• 挂载助手约定：前两个参数固定是 device 与 mountpoint，选项必须放在这两个固定参数之后。
• 未指定 mon_addr 时，mount.ceph 会尝试用本地配置文件和/或 DNS SRV 记录确定 monitor 地址；未指定 secret/secretfile 且集群启用了 CephX 时，会派生子进程用标准 Ceph 库例程查找 keyring 并取出 secret（同时也会补 monitor 地址与 FSID）。
• secret 会暴露在命令行，不安全，请始终用 secretfile。
• mds_namespace= 是 fs= 的同义词，已废弃。
• 特性可用性与内核版本相关：recover_session= 在 v5.4 进入主线内核；wsync/nowsync 在 v5.7；crush_location、read_from_replica、rasize 等自 5.8 起。
• read_from_replica=balance|localize 只对 Octopus 之后（执行过 ceph osd require-osd-release octopus）通用场景安全，否则仅限只读负载（如快照）。
• recover_session=clean 重连后文件锁变 stale，inode 上有 stale 锁时禁止读写，直到应用释放。

引自：mount.ceph

---

6.3 mount.fuse.ceph

用途：从 /etc/fstab 挂载 ceph-fuse 的辅助程序。

语法（synopsis，保留原文格式）：

mount.fuse.ceph [-h] [-o OPTIONS [OPTIONS ...]]
                 device [device ...]
                 mountpoint [mount point ...]

常用选项表

选项	参数	默认值	说明
-h	—	无	帮助
-o OPTIONS	选项串	无	挂载选项
ceph.id=<username>	用户名	无	指定 ceph-fuse 认证所用的用户
ceph.name=client.admin	完整实体名	无	指定 ceph-fuse 以 client.admin 认证
ceph.conf=/etc/ceph/foo.conf	文件路径	无	通过 ceph-fuse 命令行设置 conf 选项

规则：ceph-fuse 的选项必须写在 OPTIONS 列且以 ceph. 开头；带该前缀的会传给 ceph-fuse，其余的被 ceph-fuse 忽略。任何合法的 ceph-fuse 选项都可以这样传。

典型示例

# /etc/fstab 写法（新格式）
cat >> /etc/fstab <<'EOF'
# DEVICE    PATH        TYPE        OPTIONS
none      /mnt/ceph   fuse.ceph   ceph.id=admin,_netdev,defaults  0 0
none      /mnt/ceph   fuse.ceph   ceph.name=client.admin,_netdev,defaults  0 0
none      /mnt/ceph   fuse.ceph   ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults  0 0
EOF

# 旧格式也仍然支持
cat >> /etc/fstab <<'EOF'
# DEVICE                              PATH        TYPE        OPTIONS
id=admin                            /mnt/ceph   fuse.ceph   defaults   0 0
id=myuser,conf=/etc/ceph/foo.conf   /mnt/ceph   fuse.ceph   defaults   0 0
EOF

# 使 fstab 生效
mount /mnt/ceph

注意事项 / 常见坑

• 挂载类型列要写 fuse.ceph。
• 旧格式（device 列写 id=admin、id=myuser,conf=...）仍然支持。
• 建议同时加 _netdev（示例中给出），避免网络未就绪时挂载。

引自：mount.fuse.ceph

---

6.4 cephfs-shell

用途：提供类 shell 命令直接与 Ceph 文件系统交互的工具，支持交互式与非交互式两种模式。

语法（synopsis，保留原文格式）：

cephfs-shell [options] [command]
cephfs-shell [options] -- [command, command,...]

常用选项表

选项	参数	默认值	说明
-b, --batch FILE	文件路径	无	批处理文件路径
-c, --config FILE	文件路径	见"配置文件"段	cephfs-shell.conf 的路径
-f, --fs FS	FS 名	无	要挂载的文件系统名
-t, --test FILE	文件路径	无	用于测试的记录（transcript）文件路径

运行前提：需要最新版 cmd2 模块。若 Ceph 是源码安装，请在 build 目录执行；也可用 virtualenv：

[build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2 colorama
[build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/shell/cephfs-shell

交互式命令全表

命令	语法	说明
mkdir	mkdir [-option] <directory>...	创建目录。-m MODE 设置访问模式；-p, --parent 必要时创建父目录且目录已存在时不报错
put	put [options] <source_path> <target_path>	本地 → CephFS 复制文件/目录。source_path 为 . 复制本地工作目录下所有文件/目录，- 从 stdin 读；target_path 为 . 表示复制到远程工作目录。-f, --force 覆盖已存在的目标
get	get [options] <source_path> <target_path>	CephFS → 本地复制。target_path 为 - 输出到 stdout。-f, --force 覆盖
ls	ls [option] [directory]...	列出目录内容。默认当前工作目录。-l, --long 长格式（显示权限）；-r, --reverse 反向排序；-H 人类可读；-a, -all 忽略以 . 开头的条目；-S 按文件大小排序
cat	cat <file>....	拼接文件并输出到标准输出
ln	ln [options] <target> [link_name]	创建硬链接或符号链接。-s, --symbolic 符号链接；-v, --verbose 打印每个链接文件名；-f, --force 强制创建
cd	cd [directory]	切换当前工作目录；不指定目录则切到根目录；. 移到父目录
cwd	cwd	显示当前工作目录
chmod	chmod <mode> <file/directory>	修改权限
mv	mv <source_path> <destination_path>	移动文件/目录
rmdir	rmdir <directory_name>.....	删除目录
rm	rm <file_name/pattern>...	删除文件
write	write <file_name> → 输入数据 → Ctrl+D 结束	创建并写入文件
quit / Ctrl + D	—	关闭 shell
lls	lls <path>.....	列出本地指定目录内容（不指定则为本地当前目录）
lcd	lcd <path>	切换到本地目录
lpwd	lpwd	打印本地当前目录的绝对路径
umask	umask [mode]	设置/获取文件模式创建掩码
alias	alias [name] | [<name> <value>]	定义或显示别名；value 可含空格且无需引号
unalias	unalias [-a] name [name ...]	取消别名；-a 移除所有别名定义
shortcuts	shortcuts	列出可用的快捷方式（别名）
history	history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]	查看/运行/编辑/保存历史命令。-r 运行选中项；-e 编辑后运行；-s 脚本格式（无分隔行）；-o FILE 输出到脚本文件；-t TRANSCRIPT 输出命令与结果到记录文件
run_pyscript	run_pyscript <script_path> [script_arguments]	在控制台内运行 Python 脚本；脚本内可用 cmd("your command") 执行控制台命令，但不能嵌套运行 py/pyscript；含空格的路径/参数必须加引号。cmd2 ≤ 0.9.13 时该命令名为 pyscript
py	py <command> / py	执行一条 Python 命令 / 进入交互式 Python 模式
set	set [-h] [-a] [-l] [settable [settable ...]]	设置或显示可设置参数；不带参数列出全部可设置参数及值。-a 同时显示只读设置；-l 描述参数作用
edit	edit [file_path]	在文本编辑器中编辑文件
run_script	run_script <file_path>	运行脚本文件中的命令（ASCII 或 UTF-8，命令以换行分隔）。cmd2 ≤ 0.9.13 时名为 load
shell	shell <command> [arguments]	像在操作系统提示符下一样执行命令
locate	locate [options] <name>	在文件系统中查找。-c 统计找到的数量；-i 忽略大小写
stat	stat [-h] <file_name> [file_name ...]	显示文件状态；-h 显示帮助
snap	snap {create|delete} <snap_name> <dir_name>	在 dir_name 下创建/删除名为 snap_name 的快照
setxattr	setxattr [-h] <path> <name> <value>	设置扩展属性；-h, --help 显示帮助
getxattr	getxattr [-h] <path> <name>	获取扩展属性值
listxattr	listxattr [-h] <path>	列出与路径关联的扩展属性名
df	df [-h] [file [file ...]]	显示可用磁盘空间
du	du [-h] [-r] [paths [paths ...]]	显示目录磁盘占用；-r 递归显示所有目录
quota	quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]] {get,set} path	目录配额管理；--max_bytes 该目录下数据累计最大大小；--max_files 该目录树下的文件总数上限

本地文件系统交互：在命令前加 !（感叹号）即可让该命令作用于本地文件系统。

CephFS:~/>>> !ls # 列出本地文件系统目录内容
CephFS:~/>>> ls  # 列出 CephFS 目录内容

配置文件

默认查找顺序：① 环境变量 CEPHFS_SHELL_CONF 指定的路径；② 用户家目录下 ~/.cephfs-shell.conf。

目前 cephfs-shell 的选项全部继承自依赖 cmd2，因此会随系统安装的 cmd2 版本而不同（详见 cmd2 文档）。示例：

[cephfs-shell]
prompt = CephFS:~/>>>
continuation_prompt = >

quiet = False
timing = False
colors = True
debug = False

abbrev = False
autorun_on_edit = False
echo = False
editor = vim
feedback_to_output = False
locals_in_py = True

退出码

错误类型	退出码
Miscellaneous	1
Keyboard Interrupt	2
Operation not permitted	3
Permission denied	4
No such file or directory	5
I/O error	6
No space left on device	7
File exists	8
No data available	9
Invalid argument	10
Operation not supported on transport endpoint	11
Range error	12
Operation would block	13
Directory not empty	14
Not a directory	15
Disk quota exceeded	16
Broken pipe	17
Cannot send after transport endpoint shutdown	18
Connection aborted	19
Connection refused	20
Connection reset	21
Interrupted function call	22

典型示例

# 交互模式
cephfs-shell
cephfs-shell -c ~/.cephfs-shell.conf
cephfs-shell -f myfs2

# 非交互：单条命令
cephfs-shell -- ls
cephfs-shell -- "ls /; df -h"

# 批处理 / 测试记录
cephfs-shell -b /tmp/batch.txt
cephfs-shell -t /tmp/transcript.txt

交互式会话片段：

CephFS:~/>>> ls -l
CephFS:~/>>> mkdir -p /data/backup
CephFS:~/>>> put ./localfile.txt /data/backup/
CephFS:~/>>> get /data/backup/localfile.txt /tmp/
CephFS:~/>>> quota set --max_bytes 10737418240 --max_files 10000 /data
CephFS:~/>>> quota get /data
CephFS:~/>>> snap create snap1 /data
CephFS:~/>>> du -r /data
CephFS:~/>>> !ls          # 作用于本地文件系统
CephFS:~/>>> quit

注意事项 / 常见坑

• 交互式模式下：命令执行完打印提示符并无限等待；会话结束时以最后一条命令的返回值退出。非交互式模式下：执行完命令立即以该命令的返回值退出。
• 需要最新版 cmd2；源码安装请在 build 目录运行，或用 virtualenv 装 cmd2 + colorama。
• 命令名前加 ! 表示作用于本地文件系统，容易与 CephFS 操作混淆，删除/覆盖类操作要特别小心。
• run_pyscript 内不能嵌套 py/pyscript；cmd2 ≤ 0.9.13 时命令名为 pyscript、load。
• 配置项全部继承自 cmd2，不同版本间可能不同。

引自：cephfs-shell

---

七、RGW（对象网关）

7.1 radosgw

用途：RADOS 对象存储的 HTTP REST 网关，以 libfcgi 实现为 FastCGI 模块，可与任何支持 FastCGI 的 Web 服务器配合使用。

语法（synopsis，保留原文格式）：

radosgw

常用选项表

选项	参数	默认值	说明
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor
-i ID, --id ID	ID	无	设置 radosgw 名字中的 ID 部分
-n TYPE.ID, --name TYPE.ID	TYPE.ID	无	设置网关的 rados 用户名（如 client.radosgw.gateway）
--cluster NAME	集群名	ceph	设置集群名
-d	—	无	前台运行，日志输出到 stderr
-f	—	无	前台运行，日志输出到通常位置
--rgw-region=region	region	无	radosgw 运行的 region
--rgw-zone=zone	zone	无	radosgw 运行的 zone

配置要点（Apache + mod_proxy_fcgi）

早期 RGW 用 Apache + mod_fastcgi 配置，现在改用 mod_proxy_fcgi。它与传统 FastCGI 模块工作方式不同：需要 mod_proxy 提供 FastCGI 协议支持，两者都必须存在；且 mod_proxy_fcgi 不能启动应用进程（某些平台用 fcgistarter）。Apache 必须配置成让 mod_proxy_fcgi 走 localhost tcp。

ceph.conf 片段：

[client.radosgw.gateway]
host = {hostname}
keyring = /etc/ceph/ceph.client.radosgw.keyring
log_file = /var/log/ceph/client.radosgw.gateway.log
rgw_frontends = fastcgi socket_port=9000 socket_host=0.0.0.0
rgw_print_continue = false

网关配置文件（Debian/Ubuntu：/etc/apache2/conf-available/rgw.conf；CentOS/RHEL：/etc/httpd/conf.d/rgw.conf）：

<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html

ErrorLog /var/log/apache2/rgw_error.log
CustomLog /var/log/apache2/rgw_access.log combined

# LogLevel debug

RewriteEngine On

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

SetEnv proxy-nokeepalive 1

ProxyPass / fcgi://localhost:9000/

</VirtualHost>

文档另给出一种走 unix socket 的 ProxyPass 写法（CentOS/RHEL）： ProxyPass / unix:///var/run/ceph/ceph.radosgw.gateway.fastcgi.sock|fcgi://localhost:9000/

典型示例

# 生成网关认证 key 并加入 auth 条目
ceph-authtool -C -n client.radosgw.gateway --gen-key /etc/ceph/keyring.radosgw.gateway
ceph-authtool -n client.radosgw.gateway --cap mon 'allow rw' --cap osd 'allow rwx' /etc/ceph/keyring.radosgw.gateway
ceph auth add client.radosgw.gateway --in-file=keyring.radosgw.gateway

# 启动（Debian/Ubuntu）
sudo /etc/init.d/apache2 start
sudo /etc/init.d/radosgw start

# 启动（CentOS/RHEL）
sudo apachectl start
sudo /etc/init.d/ceph-radosgw start

# 前台调试
radosgw -d -n client.radosgw.gateway
radosgw -f --rgw-zone=zone1

Usage Logging（用量日志）

radosgw 维护一份异步用量日志：累计用户操作统计并周期性刷出，可通过 radosgw-admin 访问与管理。记录内容包括总数据传输量、总操作数、总成功操作数；数据按小时粒度记在 bucket owner 名下，除非操作发生在 service 上（例如列举 bucket），此时记在操作用户名下。

示例配置：

[client.radosgw.gateway]
    rgw_enable_usage_log = true
    rgw_usage_log_tick_interval = 30
    rgw_usage_log_flush_threshold = 1024
    rgw_usage_max_shards = 32
    rgw_usage_max_user_shards = 1

• rgw_usage_max_shards：保存用量日志信息的对象总数。
• rgw_usage_max_user_shards：单个用户的用量信息占用的对象数。
• rgw_usage_log_tick_interval：两次日志刷出之间的秒数。
• rgw_usage_log_flush_threshold：在退化为同步刷出前可缓存的条目数。

注意事项 / 常见坑

• mod_proxy_fcgi 不能启动应用进程，需要外部启动/进程管理（或用 fcgistarter）。
• 必须同时加载 mod_proxy 与 mod_proxy_fcgi。
• 本 man 页主要是 Apache+FastCGI 部署路径；现代部署（如 cephadm 的 beast 前端）不在本文档范围内。

引自：radosgw

---

7.2 radosgw-admin

用途：Ceph 对象网关的用户管理工具，用于创建和修改用户，并覆盖 bucket、配额、多站点（realm/zonegroup/zone/period）、同步、角色、通知等全部管理面操作。

语法（synopsis，保留原文格式）：

radosgw-admin command [ options ... ]

子命令总表（按主题分组）

① user / subuser / caps / key

命令	说明
user create	创建新用户
user modify	修改用户
user info	显示用户信息（含 subuser 与 keys）
user rename	重命名用户
user rm	删除用户
user suspend	暂停用户
user enable	暂停后重新启用
user check	检查用户信息
user stats	显示配额子系统统计的用户用量
user list	列出所有用户
caps add / caps rm	添加 / 移除用户 capabilities
subuser create	创建 subuser（主要用于 Swift API 客户端）
subuser modify	修改 subuser
subuser rm	删除 subuser
key create	创建 access key
key rm	删除 access key

② bucket / bi / object

命令	说明
bucket list	列出 bucket；用 --bucket=<bucket> 指定时列出其对象。--allow-unordered 去掉排序要求，对对象很多的 bucket 可能更快
bucket limit check	显示 bucket 分片统计
bucket link	把 bucket 关联到指定用户
bucket unlink	取消关联
bucket chown	把 bucket 所有权改为指定用户并更新对象 ACL；中断后用 --marker 续跑
bucket stats	列出 bucket 统计及其他内部信息
bucket rm	删除 bucket
bucket check	检查 bucket index
bucket rewrite	重写指定 bucket 中的所有对象
bucket radoslist	列出包含该 bucket 数据的 RADOS 对象；不指定 --bucket 则列出所有 bucket 的
bucket reshard	对 bucket 的 index 做 reshard
bucket sync disable / enable	禁用 / 启用 bucket 同步
bi get / bi put / bi list / bi purge	获取 / 存储 / 列出原始 bucket index 条目 / 清除条目
object rm	删除 S3/Swift 对象；加 --yes-i-really-mean-it 才会把对象条目从 bucket index 移除（例如条目已损坏时）
object stat	查看对象元数据
object manifest	显示对象 manifest，产出包含其数据的 RADOS 对象列表
object unlink	把对象从 bucket index 中摘除
object rewrite	重写指定对象
object reindex	把对象加回其 bucket 的 index（很少用，仅用于紧急修复）
objects expire	执行过期对象清理

③ quota / global quota

命令	说明
quota set	设置配额参数
quota enable / quota disable	启用 / 停用配额
global quota get / set	查看 / 设置全局配额参数
global quota enable / disable	启用 / 停用全局配额

④ realm / zonegroup / zone / period（多站点）

命令	说明
realm create / rm / get / list / rename / set	创建 / 删除 / 显示 / 列出 / 重命名 / 设置 realm（set 需要 infile）
realm get-default / default	获取默认 realm 名 / 设为默认
realm list-periods	列出 realm 的所有 period
realm pull	拉取 realm 及其当前 period
zonegroup create / rm / get / modify / set / rename / list	创建 / 删除 / 显示 / 修改 / 设置（需 infile）/ 重命名 / 列出 zonegroup
zonegroup default	设置默认 zonegroup
zonegroup add / remove	向 zonegroup 添加 / 移除 zone
zonegroup placement list / add / modify / rm / default	列出 / 添加 / 修改 / 删除 / 设置默认 placement target
zone create / rm / get / set / modify / list / rename	创建 / 删除 / 显示 / 设置（需 infile）/ 修改 / 列出 / 重命名 zone
zone placement list / add / modify / rm	zone 级 placement target 管理
period rm / get / get-current / pull / push / list / update / commit	period 管理：update 更新 staging period，commit 提交 staging period
pool add / pool rm	添加 / 移除用于数据放置的既有池
pools list	列出 placement active set

⑤ sync / 日志（多站点同步）

命令	说明
metadata sync status / init / run	获取 / 初始化 / 运行 metadata 同步
data sync status / init / run	获取 / 初始化 / 运行指定源 zone 的 data 同步
sync error list / trim	列出 / 清理同步错误
mdlog list / trim / status	列出 / 手工清理 / 查看 metadata log 状态（多站点部署需要）
bilog list / trim	列出 / 手工清理 bucket index log（用 start-marker、end-marker）
datalog list / trim / status	列出 / 手工清理 / 查看 data log 状态

⑥ 运维类：policy / log / usage / gc / lc / metadata / orphans

命令	说明
policy	显示 bucket/object 策略（权限/ACL 等）
log list / show / rm	列出日志对象 / 导出指定日志（按对象或 bucket+date+bucket-id；日期格式必须为 YYYY-MM-DD-hh）/ 删除日志对象
usage show / trim	显示 / 清理用量信息（可带用户与日期范围）
gc list / process	列出已过期的垃圾回收对象（--include-all 连未过期的也列出）/ 手工处理垃圾
lc get / list / process	获取 bucket 生命周期配置 / 列出所有 bucket 生命周期进度 / 手工处理生命周期转换（指定 bucket 则只处理该 bucket）
metadata get / put / rm / list	获取 / 写入 / 删除 / 列出 metadata 信息
orphans find / finish / list-jobs	初始化并运行泄漏 RADOS 对象搜索 / 清理搜索 / 列出当前搜索 job ID。均已 DEPRECATED，请改用 "rgw-orphan-list" 工具

⑦ role / role-policy（STS）

命令	说明
role create	创建用于 STS（Security Token Service）的新角色
role rm / get / list / modify	删除 / 获取 / 按路径前缀列出 / 修改已有角色的 assume role policy
role-policy put / list / get / rm	添加或更新角色权限策略 / 列出角色绑定的策略 / 获取角色内嵌的 inline 策略文档 / 删除策略

⑧ reshard / topic（通知）

命令	说明
reshard add / list / process / status / cancel	计划 reshard / 列出所有正在或计划 reshard 的 bucket / 处理计划任务 / 查看某 bucket 的 reshard 状态 / 取消
topic list / get / rm / stats / dump	列出 bucket 通知 topic / 获取 / 删除 / 查看持久 topic 统计（reservations、entries、size）/ 以 JSON 转储某持久 topic 的所有待发通知

常用选项表（通用）

选项	参数	默认值	说明
-c ceph.conf, --conf=ceph.conf	文件路径	/etc/ceph/ceph.conf	使用指定配置文件确定 monitor 地址
-m monaddress[:port]	地址	无	直连指定 monitor
--tenant=<tenant>	tenant 名	无	租户名
--uid=uid	uid	无	操作的用户
--new-uid=uid	uid	无	用户的新 ID，用于 user rename
--subuser=<name>	subuser 名	无	subuser 名
--access-key=<key>	key	无	S3 access key
--email=email	邮箱	无	用户邮箱
--secret / --secret-key=<key>	key	无	secret key
--gen-access-key	—	无	生成随机 access key（S3）
--gen-secret	—	无	生成随机 secret key
--generate-key	true/false	true	创建用户时是否同时生成凭据。为 false 时不能设置 --gen-access-key/--gen-secret/--secret-key/--access-key；为 true 时不能设置 --secret-key/--access-key，并绕过 --gen-secret/--gen-access-key
--key-type=<type>	swift / s3	无	key 类型
--temp-url-key[-2]=<key>	key	无	临时 URL key
--max-buckets	数量	1000（0=无限制，负值=禁止创建 bucket）	用户的最大 bucket 数
--access=<access>	read/write/readwrite/full	无	设置 subuser 的访问权限
--display-name=<name>	名字	无	用户显示名
--admin	—	无	设置用户 admin 标志
--system	—	无	设置用户 system 标志
--bucket=[tenant-id/]bucket	bucket 名	无	指定 bucket；不指定 tenant-id 则用 --uid 用户的 tenant-id
--pool=<pool>	池名	无	指定池；也用于 orphans find 指定扫描泄漏对象的 data pool
--object=object	对象名	无	指定对象
--date=yyyy-mm-dd	日期	无	日期
--start-date=yyyy-mm-dd / --end-date=yyyy-mm-dd	日期	无	起止日期
--bucket-id=<bucket-id>	id	无	指定 bucket id
--bucket-new-name=[tenant-id/]<bucket>	新名	无	bucket link 可选，用于重命名 bucket；通常无需指定 tenant-id
--shard-id=<shard-id>	id	无	mdlog list、bi list、data sync status 可选；mdlog trim 必需
--max-entries=<entries>	数量	无	列举操作的最大条目数
--purge-data	—	无	删除用户时同时清除其数据
--purge-keys	—	无	删除 subuser 时同时清除其 keys
--purge-objects	—	无	删除 bucket 时同时清除其中所有对象
--metadata-key=<key>	key	无	配合 metadata get 使用的 key
--remote=<remote>	zone/zonegroup id	无	远端网关的 zone 或 zonegroup id
--period=<id>	period id	无	Period ID
--url=<url>	URL	无	推送/拉取 period 或 realm 的 URL
--epoch=<number>	数字	无	Period epoch
--commit	—	无	在 period update 期间提交 period
--staging	—	无	获取 staging period 信息
--master	—	无	设为 master
--master-zone=<id>	zone id	无	Master zone ID
--rgw-realm=<name> / --realm-id=<id> / --realm-new-name=<name>	—	无	realm 名 / ID / 新名
--rgw-zonegroup=<name> / --zonegroup-id=<id> / --zonegroup-new-name=<name>	—	无	zonegroup 名 / ID / 新名
--rgw-zone=<zone> / --zone-id=<id> / --zone-new-name=<name>	—	无	zone 名 / ID / 新名
--source-zone	zone	无	data sync 的源 zone
--default	—	无	把实体（realm、zonegroup、zone）设为默认
--read-only	—	无	加入 zonegroup 时把 zone 设为只读
--placement-id	id	无	zonegroup placement 命令的 Placement ID
--tags=<list> / --tags-add=<list> / --tags-rm=<list>	列表	无	zonegroup placement add/modify 的标签；后两者用于 modify 的增删
--endpoints=<list>	列表	无	zone endpoints
--index-pool=<pool> / --data-pool=<pool> / --data-extra-pool=<pool>	池名	无	placement target 的 index pool / data pool / data extra（非 EC）pool
--placement-index-type=<type>	normal/indexless/#id	无	placement target 的 index 类型
--placement-inline-data=<true>	true	无	placement target 是否把数据块内联存放在 head 对象中
--tier-type=<type>	类型	无	zone tier 类型
--tier-config=<k>=<v>[,...] / --tier-config-rm=<k>[,...]	键值	无	设置 / 取消 zone tier 配置键
--sync-from-all[=false]	布尔	无	设置/重置 zone 是否从 zonegroup 所有 peer 同步
--sync-from=[zone-name][,...] / --sync-from-rm=[zone-name][,...]	列表	无	设置 / 移除同步来源 zone 列表
--bucket-index-max-shards	数量	无	覆盖 zone/zonegroup 默认 bucket index 分片数；zone create、zone modify、zonegroup add、zonegroup modify 接受该选项，且只对这些变更生效之后创建的 bucket 起作用
--fix	—	无	检查 bucket index 的同时修复它
--check-objects	—	无	bucket check 时按对象实际状态重建 bucket index
--format=<format>	xml / json	无	指定某些操作的输出格式
--sync-stats	—	无	user stats 的选项：用用户 bucket index 报告的当前统计刷新用户统计
--show-config	—	无	显示配置
--show-log-entries=<flag> / --show-log-sum=<flag>	flag	无	启用/禁用 log show 时输出日志条目 / 日志汇总
--skip-zero-entries	—	无	log show 只输出数值字段非全零的条目
--infile	文件路径	无	设置数据时指定读取的文件
--categories=<list>	逗号分隔列表	无	usage show 使用的类别列表
--caps=<caps>	caps 串	无	capabilities 列表，如 "usage=read, write; user=read"
--compression=<compression-algorithm>	lz4/snappy/zlib/zstd	无	placement target 压缩算法
--yes-i-really-mean-it	—	无	某些破坏性操作的必需护栏参数
--min-rewrite-size	大小	4M	bucket rewrite 的最小对象大小
--max-rewrite-size	大小	ULLONG_MAX	bucket rewrite 的最大对象大小
--min-rewrite-stripe-size	大小	0	object rewrite 的最小条带大小；为 0 时 restriping 总是重写该对象
--warnings-only	—	无	配合 bucket limit check，只列出接近或超过当前 max objects per shard 的 bucket
--bypass-gc	—	无	删除 bucket 时绕过 GC 直接删除对象
--inconsistent-index	—	无	删除 bucket 且 --bypass-gc 为 true 时，忽略 bucket index 一致性
--max-concurrent-ios	数量	32	bucket 操作的最大并发数；影响列举、删除以及所有扫描/搜索类操作（如查找 orphans、检查 bucket index）

Quota 选项：

选项	参数	默认值	说明
--max-objects	数量	无	最大对象数（负值表示禁用）
--max-size	大小（B/K/M/G/T）	无	最大对象大小（负值表示禁用）
--quota-scope	bucket / user	无	配额作用域

Orphans 搜索选项：

选项	参数	默认值	说明
--num-shards	数量	无	临时扫描信息使用的分片数
--orphan-stale-secs	秒	86400（24 小时）	判定对象为 orphan 前等待的秒数
--job-id	id	无	设置 job id（用于 orphans find）
--extra-info	—	无	orphans list-jobs 时提供额外信息

Role 选项：

选项	参数	默认值	说明
--role-name	名字	无	要创建的角色名
--path	路径	无	角色路径
--assume-role-policy-doc	策略文档	无	授予实体担任该角色权限的信任关系策略文档
--policy-name	名字	无	策略文档名
--policy-doc	策略文档	无	权限策略文档
--path-prefix	前缀	无	过滤角色的路径前缀

Bucket Notifications/PubSub 选项：

选项	参数	默认值	说明
--topic	topic 名	无	bucket 通知/pubsub 的 topic 名
--subscription	订阅名	无	pubsub 订阅名
--event-id	事件 id	无	pubsub 订阅中的事件 id

典型示例

# 用户管理
radosgw-admin user create --display-name="johnny rotten" --uid=johnny
radosgw-admin user create --uid=johnny --display-name="johnny rotten" --email=a@b.com \
  --gen-access-key --gen-secret
radosgw-admin user info --uid=johnny
radosgw-admin user list
radosgw-admin user rename --uid=johnny --new-uid=joe
radosgw-admin user rm --uid=johnny
radosgw-admin user rm --uid=johnny --purge-data          # 连带删除用户所有 bucket 及其内容
radosgw-admin user suspend --uid=johnny
radosgw-admin user enable --uid=johnny
radosgw-admin user stats --uid=johnny --sync-stats

# 密钥与能力
radosgw-admin key create --uid=johnny --key-type=s3 --gen-access-key --gen-secret
radosgw-admin key rm --uid=johnny --access-key=TCICW53D9BQ2VGC46I44
radosgw-admin caps add --uid=johnny --caps="usage=read, write; user=read"
radosgw-admin subuser create --uid=johnny --subuser=johnny:swift --access=full
radosgw-admin subuser rm --uid=johnny --subuser=johnny:swift --purge-keys

# bucket
radosgw-admin bucket list
radosgw-admin bucket list --bucket=foo --allow-unordered
radosgw-admin bucket stats --bucket=foo
radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny
radosgw-admin bucket unlink --bucket=foo --uid=johnny
radosgw-admin bucket link --bucket=foo --bucket-new-name=bar --uid=johnny   # 重命名
radosgw-admin bucket chown --bucket=foo --uid='12345678$12345678'
radosgw-admin bucket rm --bucket=foo
radosgw-admin bucket rm --bucket=foo --purge-objects
radosgw-admin bucket rm --bucket=foo --bypass-gc --inconsistent-index
radosgw-admin bucket check --bucket=foo --fix --check-objects
radosgw-admin bucket reshard --bucket=foo --num-shards=...   # bucket-index-max-shards 类调整
radosgw-admin bucket limit check --warnings-only
radosgw-admin bucket radoslist --bucket=foo
radosgw-admin bucket rewrite --bucket=foo --min-rewrite-size 4M

# 对象
radosgw-admin object stat --bucket=foo --object=bar
radosgw-admin object manifest --bucket=foo --object=bar
radosgw-admin object rm --bucket=foo --object=bar --yes-i-really-mean-it
radosgw-admin object reindex --bucket=foo --object=bar
radosgw-admin objects expire

# 配额
radosgw-admin quota set --uid=johnny --quota-scope=user --max-objects=1024 --max-size=1024M
radosgw-admin quota enable --uid=johnny --quota-scope=user
radosgw-admin quota set --bucket=foo --quota-scope=bucket --max-size=10G
radosgw-admin global quota set --quota-scope=bucket --max-objects=1000000
radosgw-admin global quota enable --quota-scope=bucket

# 多站点：realm / zonegroup / zone / period
radosgw-admin realm create --rgw-realm=gold --default
radosgw-admin realm list
radosgw-admin realm get --rgw-realm=gold
radosgw-admin realm pull --rgw-realm=gold --url=http://remote:80 --access-key=... --secret=...
radosgw-admin zonegroup create --rgw-zonegroup=us --rgw-realm=gold --master --default
radosgw-admin zonegroup add --rgw-zonegroup=us --rgw-zone=us-east
radosgw-admin zonegroup placement add --rgw-zonegroup=us --placement-id=default-placement \
  --index-pool=default.rgw.buckets.index --data-pool=default.rgw.buckets.data
radosgw-admin zone create --rgw-zonegroup=us --rgw-zone=us-east --endpoints=http://rgw1:80 \
  --access-key=... --secret=... --default --master
radosgw-admin zone modify --rgw-zone=us-east --sync-from=us-west
radosgw-admin period update --commit
radosgw-admin period get
radosgw-admin period push --url=http://remote:80 --period=<id> --access-key=... --secret=...

# 同步与日志
radosgw-admin metadata sync status
radosgw-admin metadata sync init
radosgw-admin data sync status --source-zone=us-west
radosgw-admin sync error list
radosgw-admin sync error trim
radosgw-admin mdlog list --shard-id=0
radosgw-admin mdlog trim --shard-id=0
radosgw-admin mdlog status
radosgw-admin bilog list --bucket=foo
radosgw-admin bilog trim --bucket=foo --start-marker=... --end-marker=...
radosgw-admin datalog list
radosgw-admin datalog status

# 用量 / 日志 / GC / 生命周期
radosgw-admin usage show --uid=johnny --start-date=2012-03-01 --end-date=2012-04-01
radosgw-admin usage show --show-log-entries=false
radosgw-admin usage trim --uid=johnny --end-date=2012-04-01
radosgw-admin log list
radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
radosgw-admin log rm --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
radosgw-admin gc list --include-all
radosgw-admin gc process
radosgw-admin lc list
radosgw-admin lc process --bucket=foo
radosgw-admin lc get --bucket=foo

# 角色（STS）
radosgw-admin role create --role-name=myrole --path=/application/ \
  --assume-role-policy-doc=file://trust.json
radosgw-admin role list --path-prefix=/application/
radosgw-admin role-policy put --role-name=myrole --policy-name=mypolicy --policy-doc=file://p.json
radosgw-admin role-policy list --role-name=myrole

# reshard / topic
radosgw-admin reshard add --bucket=foo --num-shards=8
radosgw-admin reshard list
radosgw-admin reshard process
radosgw-admin reshard status --bucket=foo
radosgw-admin reshard cancel --bucket=foo
radosgw-admin topic list
radosgw-admin topic stats --topic=mytopic
radosgw-admin topic dump --topic=mytopic

# 输出格式
radosgw-admin user list --format=json

注意事项 / 常见坑

• log show 的日期格式必须为 YYYY-MM-DD-hh（文档特别 NOTE）。
• mdlog trim 必须给 --shard-id；mdlog list、bi list、data sync status 中它是可选的。
• 手工 trim（mdlog/bilog/datalog）前，先比对 listing、确认上次同步已完成，否则可能触发重新发起一次同步。
• orphans find/finish/list-jobs 已废弃，请改用 rgw-orphan-list 工具。
• --generate-key 默认 true：此时不能指定 --secret-key/--access-key；设为 false 时则不能指定 --gen-access-key/--gen-secret/--secret-key/--access-key。
• --max-buckets 默认 1000，0 表示无限制，负值表示禁止创建 bucket。
• --bucket-index-max-shards 只对变更生效之后创建的 bucket 起作用。
• 删除 bucket 时：--purge-objects 清除所有对象；--bypass-gc 绕过 GC 直接删对象；--inconsistent-index 仅在 --bypass-gc=true 时用于忽略 index 不一致。
• --max-concurrent-ios 默认 32，影响所有扫描类操作，bucket 很大时可调高。
• 数据迁移/修复类命令（object rm --yes-i-really-mean-it、object reindex）属于破坏性或应急操作，务必先确认。
• bucket chown 中断后可用 --marker 续跑。

引自：radosgw-admin

---

八、ceph-volume

8.1 ceph-volume

用途：部署逻辑卷作为 OSD 的专用命令行工具，在为 OSD 做 prepare、activate、create 时尽量保持与 ceph-disk 相似的 API；不依赖 Ceph 安装的 udev 规则来发现设备。

语法（synopsis，保留原文格式）：

ceph-volume [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL] [--log-path LOG_PATH]
ceph-volume inventory
ceph-volume lvm [ trigger | create | activate | prepare | zap | list | batch | new-wal | new-db | migrate ]
ceph-volume simple [ trigger | scan | activate ]

全局选项

选项	参数	默认值	说明
-h, --help	—	无	帮助
--cluster CLUSTER	集群名	无	集群名
--log-level LOG_LEVEL	日志级别	无	日志级别
--log-path LOG_PATH	路径	无	日志路径

---

8.1.1 inventory

提供主机物理磁盘清单信息及元数据（型号、大小、rotational/solid state 等磁盘自身信息，以及是否可供 ceph 使用、是否存在逻辑卷等 ceph 相关项）。

选项	参数	默认值	说明
-h, --help	—	无	帮助
--format	plain（默认）/ json / json-pretty	plain	报告格式

ceph-volume inventory
ceph-volume inventory /dev/sda
ceph-volume inventory --format json-pretty

---

8.1.2 lvm batch

用一组设备创建 OSD，默认使用 bluestore；会创建所有必需的 VG 与 LV。

选项	参数	默认值	说明
--bluestore	—	默认	使用 bluestore objectstore
--yes	—	无	跳过报告和确认提示，直接开始配置
--prepare	—	无	只 prepare，不 activate
--dmcrypt	—	无	为底层 OSD 设备启用加密
--crush-device-class	类别名	无	指定 OSD 归属的 CRUSH device class
--no-systemd	—	无	不启用也不创建任何 systemd 单元
--osds-per-device	数量	1	每块设备配置多于 1 个 OSD
--report	—	无	报告当前输入的潜在结果（需要传入设备）
--format	pretty（默认）/ json	pretty	与 --report 一起使用的输出格式
--block-db-size	字节	无	设置（或覆盖）bluestore_block_db_size
--journal-size	MB	无	覆盖 osd_journal_size
<DEVICE>	裸设备全路径，如 /dev/sda	—	必需的位置参数，可传多个

ceph-volume lvm batch --bluestore /dev/sda /dev/sdb /dev/sdc
ceph-volume lvm batch /dev/sda --osds-per-device 2 --crush-device-class ssd
ceph-volume lvm batch --report --format json /dev/sda /dev/sdb
ceph-volume lvm batch --yes --dmcrypt /dev/sda

---

8.1.3 lvm activate

启用一个 systemd 单元，持久化 OSD ID 与其 UUID（Ceph CLI 中称 fsid），以便开机时知道哪个 OSD 被启用并需要挂载。

选项	参数	默认值	说明
--auto-detect-objectstore	—	无	通过检查 OSD 自动识别 objectstore
--bluestore	—	默认	bluestore objectstore
--all	—	无	激活系统中发现的所有 OSD（幂等）
--no-systemd	—	无	跳过创建/启用 systemd 单元与启动 OSD 服务

ceph-volume lvm activate --bluestore 0 8715BEB4-15C5-49DE-BA6F-401086EC7B41
ceph-volume lvm activate --all
ceph-volume lvm activate --all --no-systemd

---

8.1.4 lvm prepare

把一个逻辑卷准备为 OSD 与 journal，默认 bluestore；不会创建或修改逻辑卷（除了添加额外元数据）。

选项	参数	默认值	说明
--data	逻辑卷组名或 LV 路径	—	必需
--journal JOURNAL	LV 组名 / LV 路径 / 设备路径	无	journal
--bluestore	—	默认	使用 bluestore
--block.wal	路径	无	bluestore block.wal 的 LV 或分区路径
--block.db	路径	无	bluestore block.db 的 LV 或分区路径
--dmcrypt	—	无	为底层 OSD 设备启用加密（也支持在 create 中使用）
--osd-id OSD_ID	id	无	复用已有 OSD id
--osd-fsid OSD_FSID	fsid	无	复用已有 OSD fsid
--crush-device-class	类别名	无	指定 CRUSH device class

ceph-volume lvm prepare --bluestore --data ceph-vg/ceph-lv
ceph-volume lvm prepare --bluestore --data ceph-vg/ceph-lv --block.db ceph-db-vg/ceph-db-lv
ceph-volume lvm prepare --data /dev/sdc --osd-id 5 --dmcrypt

---

8.1.5 lvm create

把两步流程（prepare 然后 activate）合成为一步。之所以优先分开做，是为了逐步把新 OSD 引入集群，避免大量数据重平衡。单次调用的行为与 flags 用法等价于 prepare + activate。

ceph-volume lvm create --bluestore --data /dev/sda
ceph-volume lvm create --data ceph-vg/ceph-lv --block.wal ceph-wal-vg/ceph-wal-lv

---

8.1.6 lvm trigger

不应直接使用——由 systemd 使用，它解析 systemd 传来的输入（识别 OSD 的 UUID 与 ID）并代理给 ceph-volume lvm activate。systemd "data" 格式应为 <OSD ID>-<OSD UUID>，且关联的 LV 必须事先已 prepare（必需的 tag 与元数据都存在）。

ceph-volume lvm trigger 0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

---

8.1.7 lvm list

列出与 Ceph 关联的设备或逻辑卷（通过查询 LVM 元数据并与设备关联来判定）。LV 必须事先由 ceph-volume prepare 过。

位置参数	形式
<DEVICE>	LV 用 vg/lv；普通设备用 /path/to/sda1 或 /path/to/sda

ceph-volume lvm list
ceph-volume lvm list /dev/sda1
ceph-volume lvm list ceph-vg/ceph-lv

---

8.1.8 lvm zap

擦除给定的逻辑卷或分区。若给的是 LV 路径，必须是 vg/lv 形式。该 LV 或分区上的所有文件系统都会被移除、所有数据会被清除，但 LV/分区本身会保留。

选项/位置参数	说明
--destroy	彻底移除设备（所有设备类型均可用）
--osd-id	按 OSD ID 移除多个设备
--osd-fsid	配合 --osd-id 精确定位
<DEVICE>	LV 用 vg/lv；普通设备用 /path/to/sda1 或 /path/to/sda

ceph-volume lvm zap ceph-vg/ceph-lv
ceph-volume lvm zap /dev/sdc1
ceph-volume lvm zap --destroy /dev/sdc1
ceph-volume lvm zap --destroy --osd-id 1
ceph-volume lvm zap --destroy --osd-id 1 --osd-fsid C9605912-8395-4D76-AFC0-7DFDAC315D59

---

8.1.9 lvm new-wal / lvm new-db

把给定逻辑卷作为 WAL / DB 挂到 OSD 上（LV 名格式 vg/lv）。若 OSD 已挂有 WAL/DB 则失败。

选项	参数	默认值	说明
--target	LV 名	—	必需，要挂接的 LV
--osd-id / --osd-fsid	id / fsid	无	定位目标 OSD
--no-systemd	—	无	跳过检查 OSD systemd 单元
-h, --help	—	无	帮助

ceph-volume lvm new-wal --osd-id 0 --osd-fsid 8715BEB4-... --target ceph-wal-vg/ceph-wal-lv
ceph-volume lvm new-db  --osd-id 0 --osd-fsid 8715BEB4-... --target ceph-db-vg/ceph-db-lv

---

8.1.10 lvm migrate

把 BlueFS 数据从源卷迁移到目标卷；除主（data/block）卷外的源卷在成功后会被移除。目标只允许 LVM 卷，可以是已挂接的也可以是新的（后者会挂到 OSD 并替换某个源设备）。替换规则按优先级（命中即停）：

1. 源列表含 DB 卷 → 目标设备替换它
2. 源列表含 WAL 卷 → 目标设备替换它
3. 源列表只有 slow 卷 → 不允许，需显式用 new-db/new-wal 分配

选项	参数	默认值	说明
--from	data/db/wal 列表	—	必需，源设备类型名列表
--target	LV 名	—	必需，迁移目标 LV
--osd-id / --osd-fsid	id / fsid	无	定位目标 OSD
--no-systemd	—	无	跳过检查 OSD systemd 单元

ceph-volume lvm migrate --osd-id 0 --osd-fsid 8715BEB4-... \
  --target ceph-db-vg/new-db-lv --from db

---

8.1.11 simple 子命令（遗留 ceph-disk 迁移）

子命令	说明与选项
simple activate	启用 systemd 单元以持久化 OSD ID 与 UUID，读取先前在 /etc/ceph/osd/ 下以 JSON 格式持久化的信息。选项：--bluestore（默认）。需要匹配的 JSON 文件：/etc/ceph/osd/<osd id>-<osd fsid>.json
simple scan	扫描运行中的 OSD 或数据设备，生成可后续用于 activate 与管理的 JSON（含 OSD 目录下发现的所有信息）。可选：--stdout（JSON 打到 stdout）、--force（目标已存在 JSON 则覆盖）；可选位置参数：<DATA DEVICE or OSD DIR>
simple trigger	不应直接使用；由 systemd 代理输入给 simple activate，数据格式 <OSD ID>-<OSD UUID>

ceph-volume simple scan
ceph-volume simple scan /dev/sda1
ceph-volume simple scan /var/lib/ceph/osd/ceph-0
ceph-volume simple scan --stdout --force
ceph-volume simple activate --bluestore 0 8715BEB4-15C5-49DE-BA6F-401086EC7B41
ceph-volume simple trigger 0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

注意事项 / 常见坑

• ceph-volume 不依赖 udev 规则发现设备，这与 ceph-disk 不同。
• lvm zap 只清数据、保留 LV/分区本身；要彻底删除请加 --destroy。
• 加密 OSD：--dmcrypt 必须在 prepare（或 create）阶段就加上。
• 优先用 prepare + activate 分两步，以便逐步引入新 OSD、避免大规模重平衡。
• lvm trigger / simple trigger 不应手工执行，由 systemd 调用。
• lvm list / lvm trigger 都要求相关 LV 事先已被 ceph-volume prepare（tag 与元数据齐全）。
• simple activate 需要 /etc/ceph/osd/<osd id>-<osd fsid>.json 存在（由 scan 或手工生成）。
• lvm migrate 在源列表只有 slow 卷时不允许执行。

引自：ceph-volume

---

8.2 ceph-volume-systemd

用途：systemd 辅助工具，接收（动态创建的）systemd 单元传入的参数，将其转换为对 ceph-volume 的一次系统调用，仅用于激活（activation） OSD。

语法（synopsis，保留原文格式）：

ceph-volume-systemd systemd instance name

常用选项表

选项	参数	默认值	说明
（无）	systemd instance name	—	文档未列出任何命令行选项

输入格式

输入是 systemd instance name（在 systemd 单元中以 %i 表示），格式应为：

<ceph-volume subcommand>-<extra metadata>

以 lvm 为例：

/usr/bin/ceph-volume-systemd lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

它进而会调用：

ceph-volume lvm trigger  0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

任何其他子命令若要被这样调用，都必须自己实现一个能消费该格式 extra metadata 的 trigger 命令。

典型示例

# systemd 单元内部调用（%i 展开）
/usr/bin/ceph-volume-systemd lvm-%i

# 等价的手工调用
ceph-volume-systemd lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

注意事项 / 常见坑

• 这是给 systemd 单元用的辅助程序，通常不由人手工直接执行。
• 只做 activation，不做创建/准备。
• 自定义子命令要接入该机制，必须实现对应的 trigger 命令。

引自：ceph-volume-systemd

---

附录

A. 环境变量

环境变量	作用	出处
CEPH_ARGS	为不接受命令行通用选项的工具传递通用 Ceph 参数。文档明确用例：CEPH_ARGS="--debug-crush 0" crushtool ...；rados 也可把 --all 放进 CEPH_ARGS 使其成为默认	crushtool、rados
CEPH_CONF	文档未明确（本册源文未出现该变量名的说明）	—
CEPHFS_SHELL_CONF	cephfs-shell.conf 的查找路径（优先于家目录下的 ~/.cephfs-shell.conf）	cephfs-shell
RBDMAPFILE	覆盖 rbdmap 默认配置文件路径（默认 /etc/ceph/rbdmap）	rbdmap

💡 补充：CEPH_CONF 是 Ceph 工具链常见的配置文件覆盖变量，但本册所覆盖的 36 个 man 页中未出现该变量名的说明，因此不在本册断言其具体行为。

B. 配置文件 / 关键路径

路径	说明	出处
/etc/ceph/ceph.conf	默认 Ceph 配置文件（几乎所有 -c/--conf 选项的默认值）	多个命令
/etc/ceph/$cluster.conf、~/.ceph/$cluster.conf、$cluster.conf	未指定 -c 时 ceph-conf 使用的配置文件（按此顺序）	ceph-conf
/etc/ceph/rbdmap	rbdmap 默认配置文件	rbdmap
/etc/fstab	rbdmap（需含友好设备名条目）与 mount.fuse.ceph 使用	rbdmap、mount.fuse.ceph
/etc/ceph/osd/<osd id>-<osd fsid>.json	ceph-volume simple activate 必需的 JSON 文件	ceph-volume
/var/run/ceph	ceph --admin-daemon 查找 admin socket 的目录	ceph
/var/lib/ceph/osd/ceph-N	OSD 数据目录（示例路径，用于 ceph-kvstore-tool 等）	💡 补充（示例）
~/.cephfs-shell.conf	cephfs-shell 配置文件（家目录）	cephfs-shell
cephfs-shell.conf	CephFS Shell 配置文件名	cephfs-shell
/etc/apache2/conf-available/rgw.conf（Debian/Ubuntu） /etc/httpd/conf.d/rgw.conf（CentOS/RHEL）	radosgw 的 Apache/FastCGI 网关配置	radosgw
/var/log/ceph/	Ceph 日志目录（示例路径）	ceph-post-file（示例）
50-rbd.rules	udev 规则文件，配合 rbdnamer 创建 RBD 设备符号链接	rbdnamer

C. 退出码

命令	退出码定义
cephfs-shell	见 6.4 节退出码表（1–22，按 errno 语义映射：1=Miscellaneous、2=Keyboard Interrupt、3=Operation not permitted、4=Permission denied、5=No such file or directory、6=I/O error、7=No space left on device、8=File exists、9=No data available、10=Invalid argument、11=Operation not supported on transport endpoint、12=Range error、13=Operation would block、14=Directory not empty、15=Not a directory、16=Disk quota exceeded、17=Broken pipe、18=Cannot send after transport endpoint shutdown、19=Connection aborted、20=Connection refused、21=Connection reset、22=Interrupted function call）
ceph osd ok-to-stop	返回成功码表示可以停；否则返回错误码 + 说明信息（无法判断时也返回错误码）
ceph osd safe-to-destroy	返回成功码表示确定安全；否则返回错误码 + 说明信息
ceph osd ok-to-upgrade	找到安全集合时返回成功码并显示 OSD 列表；否则返回错误码 + 说明信息
其余 33 个命令	文档未明确退出码定义

💡 补充：本册源文只在 cephfs-shell 一节给出完整退出码表；ceph 的若干判定类子命令（ok-to-stop、safe-to-destroy、ok-to-upgrade）只约定了"成功码/错误码"的语义，未给出具体数值。

D. 默认值速查（跨命令）

项	默认值	出处
集群名	ceph	rados、radosgw
rbd 池名	rbd	rbd、rbd-fuse、rbd-nbd、rbd-ggate、rbd-replay、rbdmap
rbd --image-format	2	rbd
rbd --object-size	4M（最小 4K，最大 32M）	rbd
rbd --stripe-count	1	rbd
rbd --format	plain	rbd
rbd sparsify --sparse-size	4096 字节	rbd
rbd bench 默认	--io-size 4096、--io-threads 16、--io-total 1G、--io-pattern seq、--rw-mix-read 50	rbd
rbd-nbd --reattach-timeout	30 秒；--io-timeout 内核默认 30 秒	rbd-nbd
ceph-authtool --mode	0600	ceph-authtool
ceph-authtool --key-type	preferred	ceph-authtool
ceph-conf --name	client.admin	ceph-conf
ceph osd reweight-by-pg 过载判定	120	ceph
ceph osd reweight-by-utilization	过载阈值 120、最大权重变化 0.05、最多调整 OSD 数 4	ceph
ceph config log count	10	ceph
ceph tell ... heap release rate	1.0	ceph
osdmaptool --upmap-max	10	osdmaptool
osdmaptool --upmap-deviation	5	osdmaptool
osdmaptool --upmap <file> / --upmap-cleanup <file>	-（stdout）	osdmaptool
crushtool --min-x/--max-x	0 / 1023	crushtool
monmap 默认端口	v1=6789，v2=3300	monmaptool
monmaptool 三种 auth cipher	aes256k	monmaptool
rados bench 对象大小 / 线程数	4 MB / 16	rados
rados cleanup --run-name	benchmark_last_metadata	rados
radosgw-admin --generate-key	true	radosgw-admin
radosgw-admin --max-buckets	1000	radosgw-admin
radosgw-admin --max-concurrent-ios	32	radosgw-admin
radosgw-admin --min-rewrite-size / --max-rewrite-size / --min-rewrite-stripe-size	4M / ULLONG_MAX / 0	radosgw-admin
radosgw-admin --orphan-stale-secs	86400（24 小时）	radosgw-admin
mount.ceph mount_timeout	60 秒	mount.ceph
mount.ceph mds_namespace/fs	无（旧语法用）	mount.ceph
mount.ceph recover_session	no	mount.ceph
mount.ceph snapdirname	.snap	mount.ceph
mount.ceph rsize/wsize	16777216（16M）	mount.ceph
mount.ceph rasize	8388608	mount.ceph
mount.ceph readdir_max_bytes / readdir_max_entries	524288 / 1024	mount.ceph
mount.ceph caps_wanted_delay_max / _min	60 / 5	mount.ceph
mount.ceph osdkeepalive / osd_idle_ttl	5 / 60	mount.ceph
mount.ceph read_from_replica	no	mount.ceph
ceph-volume lvm batch --osds-per-device	1	ceph-volume
ceph-volume inventory --format	plain	ceph-volume
ceph-volume lvm batch --format	pretty	ceph-volume
rbd-replay --latency-multiplier	1	rbd-replay
rbd-replay -p/--pool	rbd	rbd-replay
rbd-replay-many --delay	0	rbd-replay-many
ceph-syn -c	/etc/ceph/ceph.conf	ceph-syn

---

文档未明确项

以下条目在本次覆盖的 36 个 doc/man/8/ 源文件中未给出明确说明，本册不做断言，需参考其他官方文档或源码：

1. ceph orch 与 ceph telemetry 子命令：ceph 的 man 页 synopsis 未收录这两个子命令族（仅在 -f/--format 选项说明中提及 yaml 仅对 orch 命令有效）。本册已在 1.1 节的 ⑫ orch 与 ⑬ telemetry 中，依据 mgr/orchestrator.rst、mgr/telemetry.rst、cephadm/ 等官方源文档补齐 synopsis、子命令表与示例（synopsis 为归纳所得，非 man 页原文，已用「💡 补充」标注）。剩余未明确项：orch sd dump cert、orch cert-store、orch osd ident-on/off 等命令的完整选项，以及各 orchestrator 后端逐命令的兼容矩阵细节。
2. ceph-conf 的 CEPH_CONF 环境变量：文档只说明 -c conffile 及默认搜索路径（/etc/ceph/$cluster.conf、~/.ceph/$cluster.conf、$cluster.conf），未说明环境变量覆盖方式。
3. 退出码：除 cephfs-shell（1–22 完整表）以及 ceph osd ok-to-stop/safe-to-destroy/ok-to-upgrade（仅约定"成功码/错误码"语义）外，其余 33 个命令均未给出退出码定义。
4. ceph-clsinfo 的输出格式与选项组合：只说明 -n/-v/-a 三个选项的作用，未给出输出样例，也未说明能否同时使用。
5. rbdnamer 的二进制名：源文件名与 .. program:: 声明为 ceph-rbdnamer，文档标题为 ceph-rbdnamer -- udev helper to name RBD devices；本册按手册目录项使用 rbdnamer，实际安装名是否带 ceph- 前缀文档未明确。
6. rbdmap unmap-all：正文 Description 中提到该用法，但 Synopsis 与 Options 未列出其语法与选项（Options 一节明确写 None）。
7. crushtool 的完整 --set-... tunables 清单：文档只举例 --set-choose-total-tries，并说明"更多 --test 相关选项见官方 man 页"，未给出完整列表。
8. ceph-syn 的完整 workload 列表：文档明确注明"This is not a complete list"。
9. osdmaptool --read 的完整参数：文档只给出 --read <file> 与 --read-pool <poolname>，未说明输出文件内容格式与可调参数。
10. radosgw-admin 各子命令的精确必需/可选参数矩阵：man 页只给出命令清单与选项清单，未逐命令标注哪些选项为必需（除文中明确写 Required 的几项，如 mdlog trim 需 --shard-id）。
11. krbd 选项的"当前默认值"：rbd 文档明确说明这些默认值由内核设置，可能取决于运行内核的版本，因此本册给出的默认值以文档标注为准，实际以内核为准。
12. ceph-volume 全局选项 --log-level / --log-path 的取值：文档只列出选项名，未给出合法取值清单。