The monmap and the cluster identity

Why this matters in production

Every daemon and every client reaches the cluster through the monmap, and a monitor whose monmap disagrees with the quorum never joins — however healthy the process looks from the host.

What the monmap records

The monmap is a small versioned document the monitors agree on through Paxos. It is the only authoritative statement of which monitors exist, where they are, and which cluster they belong to.

ceph mon dump

epoch 7
fsid 8f2c1a44-9d31-4c0e-b7a1-2c6d5f0e91b3
last_changed 2026-08-11T09:14:22.113402+0000
created 2025-02-03T11:02:57.881994+0000
min_mon_release 20 (tentacle)
election_strategy: 1
0: [v2:10.0.1.11:3300/0,v1:10.0.1.11:6789/0] mon.ceph-a
1: [v2:10.0.1.12:3300/0,v1:10.0.1.12:6789/0] mon.ceph-b
2: [v2:10.0.1.13:3300/0,v1:10.0.1.13:6789/0] mon.ceph-c
dumped monmap epoch 7

Getting a copy you can work on

ceph mon getmap -o /tmp/monmap
monmaptool --print /tmp/monmap

# the same thing from a monitor host when the cluster will not answer
sudo cephadm enter --name mon.ceph-a -- \
  ceph daemon mon.ceph-a mon_status > /tmp/mon_status.json

ceph quorum_status --format json | python3 -c '
import sys,json
d = json.load(sys.stdin)
print("epoch:  ", d["monmap"]["epoch"])
print("size:   ", len(d["monmap"]["mons"]))
print("quorum: ", ",".join(d["quorum_names"]))
print("leader: ", d["quorum_leader_name"])'

Rank is derived, not assigned

Ranks are not chosen and are not tied to the monitor name. Ceph sorts the monitors by address and numbers them from zero, so the rank of an existing monitor changes whenever one is added or renumbered below it.

# add a monitor on 10.0.1.10 and every existing rank shifts up by one
monmaptool --print /tmp/monmap | grep -E '^[0-9]+:'

When the monmap disagrees with reality

# what each monitor believes, independently of the quorum
for m in ceph-a ceph-b ceph-c; do
  printf '%-10s ' "$m"
  ceph tell mon.$m mon_status 2>/dev/null | python3 -c '
import sys,json
d = json.load(sys.stdin)
print("state=%-14s epoch=%-4s outside=%s" %
      (d["state"], d["monmap"]["epoch"], d.get("outside_quorum")))' \
  || echo "unreachable"
done

Quiz

Production discipline

Export the monmap before you change anything about the monitor set, and keep the export with the incident notes — it is the cheapest artefact in Ceph and the one you will want. Key automation on monitor names, never on rank, because rank is recomputed from the sorted address list every time the set changes.

Cross-course references

• Kubernetes: etcd membership is likewise an ordered set, not a list of hostnames
• Linux: identity mismatches surface as connection errors far more often than as identity errors