> 基于 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，保留原文格式）**：

```text
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）<br>`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** |

#### 典型示例

```bash
# 集群概览
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](https://docs.ceph.com/en/tentacle/man/8/ceph/)

#### ⑫ `orch`（Orchestrator / cephadm 编排）

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

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

**语法（synopsis）**：

```text
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` |

**典型示例**：

```bash
# 查看编排器状态与已部署服务
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](https://docs.ceph.com/en/tentacle/man/8/ceph/)

#### ⑬ `telemetry`（遥测上报）

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

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

**语法（synopsis）**：

```text
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'` |

**典型示例**：

```bash
# 开启 / 关闭 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](https://docs.ceph.com/en/tentacle/man/8/ceph/)

---

### 1.2 `ceph-conf`

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

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

```text
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，优先于常规搜索；返回首个匹配项 |

#### 典型示例

```bash
# 查 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](https://docs.ceph.com/en/tentacle/man/8/ceph-conf/)

---

### 1.3 `ceph-run`

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

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

```text
ceph-run command ...
```

#### 常用选项表

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

#### 典型示例

```bash
# 用 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](https://docs.ceph.com/en/tentacle/man/8/ceph-run/)

---

### 1.4 `ceph-syn`

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

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

```text
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） |

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

#### 典型示例

```bash
# 单客户端：建目录树 + 遍历
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](https://docs.ceph.com/en/tentacle/man/8/ceph-syn/)

---

### 1.5 `ceph-post-file`

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

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

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

#### 常用选项表

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

#### 典型示例

```bash
# 上传单个日志
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](https://docs.ceph.com/en/tentacle/man/8/ceph-post-file/)

---

### 1.6 `librados-config`

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

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

```text
librados-config [ --version ] [ --vernum ]
```

#### 常用选项表

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

#### 典型示例

```bash
librados-config --version
librados-config --vernum
```

#### 注意事项 / 常见坑

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

> 引自：[librados-config](https://docs.ceph.com/en/tentacle/man/8/librados-config/)

---

## 二、密钥与认证

### 2.1 `ceph-authtool`

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

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

```text
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 语法**：

```text
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 是能力串。

#### 典型示例

```bash
# 新建 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](https://docs.ceph.com/en/tentacle/man/8/ceph-authtool/)

---

### 2.2 `ceph-clsinfo`

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

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

```text
ceph-clsinfo [ options ] ... filename
```

#### 常用选项表

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

#### 典型示例

```bash
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](https://docs.ceph.com/en/tentacle/man/8/ceph-clsinfo/)

---

## 三、MON / OSD 工具

### 3.1 `ceph-mon`

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

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

```text
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 包含它。

#### 典型示例

```bash
# 前台运行（便于 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](https://docs.ceph.com/en/tentacle/man/8/ceph-mon/)

---

### 3.2 `ceph-osd`

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

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

```text
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` 同时使用** |

#### 典型示例

```bash
# 前台运行 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](https://docs.ceph.com/en/tentacle/man/8/ceph-osd/)

---

### 3.3 `ceph-mds`

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

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

```text
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 不应以数字开头** |

#### 典型示例

```bash
# 前台启动一个 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](https://docs.ceph.com/en/tentacle/man/8/ceph-mds/)

---

### 3.4 `monmaptool`

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

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

```text
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 轮换时的首选加密类型 |

#### 典型示例

```bash
# 为全新集群创建含三个 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](https://docs.ceph.com/en/tentacle/man/8/monmaptool/)

---

### 3.5 `osdmaptool`

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

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

```text
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/` 前缀 |

#### 典型示例

```bash
# 创建一个含 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`）

```text
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](https://docs.ceph.com/en/tentacle/man/8/osdmaptool/)

---

### 3.6 `crushtool`

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

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

```text
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`）

每层语法：

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

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

#### 典型示例

```bash
# 反编译 → 编辑 → 重新编译
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](https://docs.ceph.com/en/tentacle/man/8/crushtool/)

---

### 3.7 `crushdiff`

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

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

```text
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 |

#### 典型示例

```bash
# 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
```

#### 输出示例

```text
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）：

```text
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](https://docs.ceph.com/en/tentacle/man/8/crushdiff/)

---

### 3.8 `ceph-kvstore-tool`

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

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

```text
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 大小的分布统计 |

#### 典型示例

```bash
# 列出某 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](https://docs.ceph.com/en/tentacle/man/8/ceph-kvstore-tool/)

---

### 3.9 `ceph-dencoder`

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

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

```text
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，以便编码出**旧版本软件能理解**的对象（仅对支持该能力的类型有效） |

#### 典型示例

```bash
# 查看 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](https://docs.ceph.com/en/tentacle/man/8/ceph-dencoder/)

---

### 3.10 `ceph-debugpack`

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

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

```text
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。

#### 典型示例

```bash
# 生成调试包
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](https://docs.ceph.com/en/tentacle/man/8/ceph-debugpack/)

---
## 四、RADOS

### 4.1 `rados`

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

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

```text
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 载入池内容 |

#### 典型示例

```bash
# 集群与池利用率
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](https://docs.ceph.com/en/tentacle/man/8/rados/)

---

## 五、RBD

### 5.1 `rbd`

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

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

```text
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 写法

```text
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`）。

#### 典型示例

```bash
# 创建与查看
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](https://docs.ceph.com/en/tentacle/man/8/rbd/)

---

### 5.2 `rbd-fuse`

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

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

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

#### 常用选项表

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

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

#### 典型示例

```bash
# 挂载默认 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](https://docs.ceph.com/en/tentacle/man/8/rbd-fuse/)

---

### 5.3 `rbd-nbd`

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

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

```text
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

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

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

#### 典型示例

```bash
# 映射
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](https://docs.ceph.com/en/tentacle/man/8/rbd-nbd/)

---

### 5.4 `rbd-ggate`

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

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

```text
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

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

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

#### 典型示例

```bash
# 映射
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](https://docs.ceph.com/en/tentacle/man/8/rbd-ggate/)

---

### 5.5 `rbdmap`

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

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

```text
rbdmap map
rbdmap unmap
```

#### 常用选项表

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

**配置文件格式**：

```text
IMAGESPEC RBDOPTS
```

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

#### 典型示例

```bash
# /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](https://docs.ceph.com/en/tentacle/man/8/rbdmap/)

---

### 5.6 `rbd-replay`

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

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

```text
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；多个镜像关闭或同一镜像多次开关会输出多次；计数器的含义可能随版本变化 |

#### 典型示例

```bash
# 尽可能快地重放（间隔归零）
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](https://docs.ceph.com/en/tentacle/man/8/rbd-replay/)

---

### 5.7 `rbd-replay-prep`

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

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

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

#### 常用选项表

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

#### 典型示例

```bash
# 准备 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](https://docs.ceph.com/en/tentacle/man/8/rbd-replay-prep/)

---

### 5.8 `rbd-replay-many`

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

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

```text
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** | 启动每个客户端之间的间隔 |

#### 典型示例

```bash
# 在两台主机上重放
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](https://docs.ceph.com/en/tentacle/man/8/rbd-replay-many/)

---

### 5.9 `rbdnamer`

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

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

```text
ceph-rbdnamer num
```

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

#### 常用选项表

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

#### 典型示例

```bash
# 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](https://docs.ceph.com/en/tentacle/man/8/rbdnamer/)

---
## 六、CephFS

### 6.1 `ceph-fuse`

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

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

```text
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。

#### 典型示例

```bash
# 挂载默认文件系统
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](https://docs.ceph.com/en/tentacle/man/8/ceph-fuse/)

---

### 6.2 `mount.ceph`

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

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

```text
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 类型匹配者胜） |

#### 典型示例

```bash
# 挂载整个文件系统（推荐通过 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](https://docs.ceph.com/en/tentacle/man/8/mount.ceph/)

---

### 6.3 `mount.fuse.ceph`

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

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

```text
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 选项都可以这样传。

#### 典型示例

```bash
# /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](https://docs.ceph.com/en/tentacle/man/8/mount.fuse.ceph/)

---

### 6.4 `cephfs-shell`

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

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

```text
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：
> ```bash
> [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 文档）。示例：

```ini
[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 |

#### 典型示例

```bash
# 交互模式
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
```

交互式会话片段：

```text
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](https://docs.ceph.com/en/tentacle/man/8/cephfs-shell/)

---

## 七、RGW（对象网关）

### 7.1 `radosgw`

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

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

```text
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` 片段：

```ini
[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`）：

```apache
<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/`

#### 典型示例

```bash
# 生成网关认证 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），此时记在操作用户名下。

示例配置：

```ini
[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](https://docs.ceph.com/en/tentacle/man/8/radosgw/)

---

### 7.2 `radosgw-admin`

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

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

```text
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 |

#### 典型示例

```bash
# 用户管理
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](https://docs.ceph.com/en/tentacle/man/8/radosgw-admin/)

---

## 八、ceph-volume

### 8.1 `ceph-volume`

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

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

```text
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` | 报告格式 |

```bash
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` | — | 必需的位置参数，可传多个 |

```bash
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 服务 |

```bash
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 |

```bash
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`。

```bash
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 与元数据都存在）。

```bash
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` |

```bash
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` |

```bash
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` | — | 无 | 帮助 |

```bash
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 单元 |

```bash
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>` |

```bash
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](https://docs.ceph.com/en/tentacle/man/8/ceph-volume/)

---

### 8.2 `ceph-volume-systemd`

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

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

```text
ceph-volume-systemd systemd instance name
```

#### 常用选项表

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

#### 输入格式

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

```text
<ceph-volume subcommand>-<extra metadata>
```

以 `lvm` 为例：

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

它进而会调用：

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

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

#### 典型示例

```bash
# 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](https://docs.ceph.com/en/tentacle/man/8/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）<br>`/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` 的取值**：文档只列出选项名，未给出合法取值清单。