There is no literal ceph show pools command. To list pools, run ceph osd pool ls for names only, ceph osd lspools for names with IDs, or ceph osd pool ls detail for replica size, PG count, CRUSH rule and application per pool. For usage per pool, run ceph df.
Run these wherever ceph status already works: a host with the admin keyring, or inside cephadm shell on a cephadm-managed cluster. All of them are read-only, so they are safe on a degraded cluster at 2 a.m., which is when most people go looking for them.
Which command shows Ceph pools?
ceph osd pool ls detail is the one worth memorising: it prints every pool on one line with its ID, type, replica count, min_size, CRUSH rule, PG count, autoscale mode and application tag. The other commands are narrower slices of the same pool map, or they add usage and I/O figures the pool map does not carry.
| Command | What it shows | Use it when |
|---|---|---|
ceph osd pool ls | Pool names only | Scripting and loops |
ceph osd lspools | Pool ID and name | Matching a PG ID to its pool |
ceph osd pool ls detail | Full settings per pool | Auditing size, rules, PGs |
ceph df | Stored, objects, used, %used, max avail | Capacity questions |
ceph df detail | Adds quotas, compression, data vs omap | Finding where space went |
rados df | Per-pool usage and object counts | Cross-checking ceph df |
ceph osd pool stats | I/O per pool | Finding the busy pool |
ceph osd pool autoscale-status | PG autoscaler view | PG count warnings |
ceph osd pool get <pool> all | Every parameter for one pool | Deep dive on one pool |
The Ceph pool operations documentation covers the three listing forms and recommends plain ceph osd pool ls for scripting. Its lspools sample looks like this:
$ ceph osd lspools
1 .rgw.root
2 default.rgw.log
3 default.rgw.control
4 default.rgw.metaThe ID matters: every placement group ID starts with its pool ID, so when ceph health detail complains about PG 3.1f, pool 3 is the one in trouble.
How do you read ceph osd pool ls detail?
Read it left to right: pool ID and name, type, size and min_size, CRUSH rule ID, PG counts, autoscale mode, flags and application. Here is one line from the documentation’s sample cluster, wrapped for width:
pool 1 '.rgw.root' replicated size 3 min_size 1 crush_rule 0 object_hash rjenkins
pg_num 32 pgp_num 32 autoscale_mode on last_change 19 flags hashpspool
stripe_width 0 application rgw read_balance_score 4.00replicatedis the type. Erasure-coded pools showerasureplus the profile name, and theirsizeis k+m.size 3 min_size 1means three copies in total, with I/O continuing while at least one is up.crush_rule 0is the rule by numeric ID. Map it to a name withceph osd crush rule dump. The current ceph man page also lists a--show-rule-namesoption forceph osd pool ls; older releases may lack it.pg_num 32 pgp_num 32is the placement group count. If the two differ, a PG change is still being applied.autoscale_mode onmeans the PG autoscaler manages this pool.application rgwis the application tag:rbd,cephfs,rgwor a custom name.
That min_size 1 in the docs’ sample deserves a second look if you find it on your own three-replica pools. It lets the pool keep accepting writes with a single surviving copy, which is the setup that turns one more dead disk into lost data. The conventional pairing is size 3 with min_size 2; the reasoning is in how Ceph places data with pools, PGs and CRUSH.
For scripts, ask for JSON rather than splitting the text on spaces. The --format (or -f) option takes json, json-pretty, xml or xml-pretty:
ceph osd pool ls detail -f json-pretty
ceph osd pool ls detail -f json | jq -r '.[] | [.pool_name, .size, .min_size, .pg_num] | @tsv'What is the .mgr pool in my pool list?
.mgr is Ceph’s own pool, holding state for the manager daemon’s modules, and you should leave it alone. The Quincy 17.2.0 release notes say the old device_health_metrics pool was renamed .mgr, became a common store for all ceph-mgr modules, and is renamed automatically on upgraded clusters.
Pool names starting with a dot are reserved for Ceph’s internal operations, and the pools documentation says not to create or manipulate them. Expect pools you never created: .mgr always, .rgw.root and the default.rgw.* family once an object gateway starts, .nfs if you deploy the NFS service, and a metadata and data pair per CephFS filesystem.
Proxmox users met a sharp edge here. The Proxmox Pacific to Quincy upgrade guide warns that guest images stored in the device_health_metrics pool “will be broken after the upgrade” and says to move them to a new pool first. If a pool listing ever shows VM disks living in a pool Ceph created for itself, move them before the next major upgrade, not after.
How do you see pool usage and free space?
Run ceph df. Its POOLS section lists STORED (data clients wrote), OBJECTS, USED (raw space consumed, including replication and erasure-coding overhead), %USED and MAX AVAIL (an estimate of how much more that pool can take). ceph df detail adds quota, compression and data-versus-omap columns.
A trimmed excerpt from the monitoring documentation:
--- POOLS ---
POOL ID PGS STORED OBJECTS USED %USED MAX AVAIL
.mgr 11 1 558 MiB 141 1.6 GiB 0 5.8 TiB
cephfs_meta 13 1024 166 GiB 14.59M 499 GiB 2.74 5.8 TiB
kubedata 104 256 63 GiB 17.65k 188 GiB 0.03 234 TiBThat sample comes from a multi-petabyte cluster, not a three-node homelab, but the ratios read the same at any size. Each of those pools shows USED at roughly three times STORED, which is what a three-replica pool should look like. Compression pulls the ratio down; snapshots and allocation granularity on small objects push it up.
The docs call MAX AVAIL a function of the replication or erasure coding in use, the CRUSH rule, the utilisation of the devices that rule selects, and mon_osd_full_ratio. That is why the sample shows 5.8 TiB and 234 TiB side by side: those pools map to different devices. On a small cluster, one unevenly filled OSD can drag MAX AVAIL down before the raw totals look alarming, so check ceph osd df when it falls faster than you expect. Nearfull OSDs and pools near quota raise named health checks, covered in clearing Ceph HEALTH_WARN.
Check one pool’s settings with ceph osd pool get
ceph osd pool get <pool> all
ceph osd pool get <pool> size
ceph osd pool get <pool> crush_rule
ceph osd pool get <pool> erasure_code_profile # erasure-coded pools only
ceph osd pool application get <pool>Per the man page, all returns every parameter that applies to the pool’s type, so you skip guessing key names. Single keys suit scripts and monitoring checks. For an erasure-coded pool the profile name is half the story; ceph osd erasure-code-profile get <profile> shows the k, m and failure domain behind it, and erasure coding versus replication explains what those numbers cost.
Confirm an application tag on every pool you created. A pool without one triggers POOL_APP_NOT_ENABLED, which the health checks reference resolves with rbd pool init <pool> for RBD or ceph osd pool application enable for anything else.
Check PG counts and live I/O per pool
ceph osd pool autoscale-status
ceph osd pool stats <pool>autoscale-status is the pool list from the PG autoscaler’s point of view. The placement groups documentation defines its columns: RATE is space amplification (3.0 for three replicas, 1.5 for a k=4, m=2 erasure-coded pool), PG_NUM is the current count, NEW PG_NUM appears only when the recommendation differs enough to matter, and AUTOSCALE reads on, off or warn. An empty NEW PG_NUM column is the good outcome.
ceph osd pool stats reports I/O for one pool, or all pools if you omit the name. During the rebalance after you add an OSD, it is the quickest way to see which pool is moving data.
Showing pools in Proxmox and the dashboard
On Proxmox VE, pveceph pool ls lists all pools and their settings, per the pveceph manual, and the node’s Ceph > Pools panel shows the same in the GUI. On cephadm clusters, the Ceph dashboard Pools page lists applications, autoscaling, placement groups, replication size, erasure-code profiles, CRUSH rules and quotas.
Both are fine for a glance. When asking for help on a forum, paste ceph osd pool ls detail and ceph df output instead; a screenshot cannot be grepped.
What should you check after listing pools?
Check four things: every replicated data pool runs size 3 with min_size above 1, each CRUSH rule’s failure domain matches the hosts you actually own, every pool carries an application tag, and MAX AVAIL leaves room to survive a host failure and recover.
The failure-domain check catches the most homelab mistakes. A host-level rule on a three-replica pool needs three hosts with free space, so a two-node cluster stays undersized until the third arrives; the node counts are in Ceph minimum hardware requirements. With exactly three hosts, losing one leaves nowhere to re-replicate, so the cluster runs degraded until it returns. That is the honest argument for a fourth node.
FAQ
how do i list objects in a ceph pool
Run rados -p <pool> ls to list every object in a pool, or pass --pgid with a PG ID instead of the pool to list only that placement group’s objects. On a pool holding millions of objects this walks the entire pool, so redirect it to a file or pipe it through head rather than flooding the terminal.
why is ceph df max avail lower than free space
MAX AVAIL is an estimate of what the pool can still store, not raw free space. Ceph divides by the pool’s replication or erasure-coding overhead, limits it to devices its CRUSH rule selects, accounts for how full those devices are, and stops at mon_osd_full_ratio. A three-replica pool sees about a third of raw free space.
can i delete the .mgr pool in ceph
No, leave .mgr in place. The manager daemon uses it as a shared store for its modules, including device health data, and Ceph reserves every pool name that starts with a dot for internal use. Deleting any pool also requires setting mon_allow_pool_delete to true first, a deliberate speed bump worth respecting here.
how do i check a ceph pool quota
Run ceph osd pool get-quota <pool> to see a pool’s object and byte quotas; ceph df detail shows the same limits in its QUOTA OBJECTS and QUOTA BYTES columns. Set one with ceph osd pool set-quota <pool> max_bytes <bytes>, and remove it by setting the value to 0. A pool that hits its quota stops accepting writes.
