Methodology
This page documents every formula, constant, rule and assumption behind the Ceph planner (published as planmycluster). It exists so a sceptical Ceph administrator can decide whether to trust a number the tool shows, without reading the source code.
If you find a formula here that does not match the official documentation, please treat the documentation as correct and report the discrepancy — see the feedback link on the tool page.
What the tool computes, and what it deliberately does not
The planner turns a description of Proxmox nodes, OSDs and pools into:
- raw, usable and planning ("planned") capacity, decimal TB and TiB,
- recommended placement group (
pg_num) counts per pool, - redundancy findings (
size/min_size, erasure coding, failure domain, topology, network), - the effect of simulating the loss of one node or one OSD, split into "is data still available" and "can Ceph self-heal",
- a rough recovery time range,
- ready-to-copy
pvecephand nativecephcommands for the exact layout entered.
It deliberately does not:
- predict IOPS, throughput or latency of a running cluster,
- edit or generate a CRUSH map,
- connect to a real cluster, read
ceph -s, or send any data anywhere — every computation happens in your browser, and the result is only ever a plan, - replace judgement for anything the official Ceph or Proxmox documentation does not state as a hard rule (see Assumptions below).
Units
All inputs default to decimal terabytes (TB, 10¹²), because that is how drives are sold and specified. Ceph itself reports capacity in binary tebibytes (TiB, 2⁴⁰). The tool lets you switch the display unit; internally every computation happens in bytes (number, not BigInt — cluster sizes stay far below the precision limit of IEEE-754 doubles).
| Unit | Definition | Bytes |
|---|---|---|
| TB (decimal) | 10¹² bytes | 1,000,000,000,000 |
| TiB (binary) | 2⁴⁰ bytes | 1,099,511,627,776 |
Source: packages/ceph-core/src/units.ts (BYTES_PER_TB, BYTES_PER_TIB).
Capacity
Source: packages/ceph-core/src/capacity.ts.
Raw capacity.
rawBytes = Σ nodes Σ osdGroups (count × sizeBytes)Per-pool efficiency — usable bytes per raw byte:
| Redundancy | Efficiency |
|---|---|
| Replicated, size copies | 1 / size |
| Erasure coded, k data + m coding chunks | k / (k + m) |
Usable capacity of a pool, and of the cluster (sum over pools):
usableBytes(pool) = effectiveRawBytes × (percent / 100) × efficiency
usableBytes(cluster) = Σ pools usableBytes(pool)effectiveRawBytes is the raw capacity _after_ the imbalance correction described below; it equals rawBytes whenever the cluster is even enough that no correction applies.
Planning capacity. The number to actually plan with is the usable capacity up to the nearfull ratio:
plannedUsableBytes = usableBytes × NEARFULL_RATIO (NEARFULL_RATIO = 0.85)The tool shows both usableBytes and plannedUsableBytes and explains that Ceph raises a health warning above 85 % fill (mon_osd_nearfull_ratio) and blocks writes above 95 % (mon_osd_full_ratio). The three configured thresholds are shown against raw capacity:
| Constant | Value | Ceph config key | Meaning |
|---|---|---|---|
| NEARFULL_RATIO | 0.85 | mon_osd_nearfull_ratio | Ceph raises a health warning |
| BACKFILLFULL_RATIO | 0.90 | mon_osd_backfillfull_ratio | Ceph refuses to backfill onto the OSD |
| FULL_RATIO | 0.95 | mon_osd_full_ratio | Ceph blocks writes |
Source: packages/ceph-core/src/constants.ts, citing https://docs.ceph.com/en/latest/rados/configuration/mon-config-ref/ (retrieved 2026-09-17).
Imbalance correction `[ASSUMPTION: approximation]`
With failure domain host, CRUSH places at most one copy or erasure chunk of any given object per host. A host that is larger than its even share of the raw capacity — rawBytes / width, where width is size (replicated) or k + m (erasure) — therefore cannot be filled completely: the surplus stays permanently empty, no matter how the rest of the cluster is balanced.
Closed form used by the planner, per pool width:
evenShare = rawBytes / width
maxHost = max(node raw bytes)
effectiveRawBytes =
rawBytes if maxHost ≤ evenShare
(rawBytes − maxHost) × width / (width − 1) otherwiseThis is exact when at most one host is oversized — the realistic case of "one big node added to an otherwise even cluster". With several oversized hosts the formula is conservative: it never reports more usable capacity than CRUSH can actually place, but it may slightly under-report it. The tool flags the largest host with finding host-oversized (warning) and states the unusable amount in TB.
Mixed OSD sizes _within_ one host are not computed at all — CRUSH weights OSDs by size, so larger OSDs receive proportionally more data, and the tool only surfaces this as the informational finding mixed-osd-sizes without attempting a number.
Source: packages/ceph-core/src/capacity.ts (effectiveRawForWidth), plan section 5.2.
Failure scenarios: two separate questions
Any number of hosts and OSDs can be marked as failed at the same time. Losing them raises two independent questions, answered separately (never merged into one verdict).
How the failures are counted:
- A
nodetarget removes the whole node; naming it twice changes nothing. - An
osdtarget removes one drive from one OSD group. Repeating it removes one more drive of that group, which is how two distinct drives of the same group are expressed, and it never removes more drives than the group has. - An
osdtarget inside a node that is already failed as a whole is ignored, so the two kinds of target cannot double count.
From that tally:
totalDomains = hosts (failure domain host)
totalDomains = osds (failure domain osd)
affectedDomains = hosts that lost at least one OSD (failure domain host)
affectedDomains = number of failed OSDs (failure domain osd)
remainingDomains = totalDomains - fully failed domainsaffectedDomains and remainingDomains are deliberately not complementary: a host that lost one of twelve drives is assumed to have held a copy of the placement group under consideration, and it is still a place CRUSH can put a replacement copy. A host counts as _fully_ failed, and therefore as down, when every one of its OSDs is gone, however the failures were entered. [ASSUMPTION] The worst-case reading of a partially failed host is a planning choice: the planner cannot know which PGs sat on which drive.
1. Is the data available right now? CRUSH cannot place more copies or chunks than there are failure domains. A pool of size 3 on a single host therefore has one copy, not three, and the two copies that do not exist must not be counted as survivors:
placementDomains = min(width, totalDomains)
copiesLost = min(affectedDomains, placementDomains)
remainingCopies = placementDomains - copiesLost
dataAvailable = remainingCopies > 0 and remainingCopies >= minSizewidth is size (replicated) or k + m (erasure). This is also what makes a one-host cluster honest: its single host holds the only copy, and losing it loses everything.
2. Can Ceph repair it? Repairing needs enough _distinct_ failure domains left to hold a full set, and enough surviving pieces to reconstruct from. How many pieces that takes depends on the redundancy:
rebuildMinimum = 1 (replicated: any surviving replica can be copied)
rebuildMinimum = k (erasure coded: k chunks reconstruct a stripe, fewer reconstruct nothing)
selfHealing = remainingDomains >= width and remainingCopies >= rebuildMinimum
dataLost = remainingCopies < rebuildMinimumFor an erasure coded pool dataLost is reached long before the last chunk is gone: a 4+2 pool with three surviving chunks is below k and cannot be rebuilt, even though half the stripe still exists and plenty of hosts are left. Ceph recovers below min_size, but never below k.
Every pool with dataLost raises finding failure-data-lost (danger) and names itself, because one destroyed pool next to a healthy one is still a data loss.
Source for the erasure coding property: https://docs.ceph.com/en/latest/rados/operations/erasure-code/ (retrieved 2026-09-19).
If a pool can heal, the tool also checks that recovering does not push the surviving capacity past nearfull:
bytesToRecover = lostRawBytes * fillTargetPercent / 100 * healingShare
recoveryFitsBelowNearfull = usedRawBytes <= rawAfterBytes * NEARFULL_RATIOwhere healingShare is the summed percent of the pools that can actually heal, usedRawBytes = rawBytes * fillTargetPercent / 100 (the cluster's planned fill level) and rawAfterBytes = rawBytes - lostRawBytes. Bytes of a pool that cannot be rebuilt are not counted, because nothing will rewrite them. If the check does not hold, finding recovery-exceeds-nearfull (warning) is raised; the code additionally requires rawAfterBytes > 0 and allows a floating-point epsilon.
The summary values follow the same split as the two questions: allDataAvailable is true only when _every_ pool is available, while anySelfHealing is true as soon as _one_ pool can rebuild, and it is anySelfHealing that decides whether a recovery estimate is shown at all.
Source: packages/ceph-core/src/capacity.ts (analyseFailures), plan section 5.2.
Device classes: what the planner asks for, and what Ceph sees
The planner offers four storage classes, Ceph knows three. Ceph derives its device class from the device itself: rotational becomes hdd, NVMe becomes nvme, and everything else non-rotational becomes ssd. A SAS SSD is therefore ssd to Ceph, however it is labelled on the invoice.
The distinction is still worth making, because the interface sets the ceiling: SATA stops at 6 Gbit/s while SAS runs at 12, which roughly doubles what a drive can sustain and shows up directly in the recovery estimate. So sas exists as a planning class and is mapped through cephDeviceClass() wherever it reaches Ceph. The generated commands name the class the cluster will report, ssd, and add one comment line saying that SAS drives were planned — a comment above a command block has to match what ceph osd tree will say.
Source: https://docs.ceph.com/en/latest/rados/operations/crush-map/#device-classes (retrieved 2026-09-20).
How many placement groups a failure actually touches
The failure model above answers for the worst-case placement group: it says whether _some_ PG can be in trouble. That is the right answer to "is my data safe" and a poor one to "how bad is it", because in a pool of 512 PGs the worst case may be a single PG or all of them.
The second question is answered separately. CRUSH spreads a pool's PGs over the failure domains pseudo-randomly, so the number of copies a given PG had on the failed domains follows a hypergeometric distribution: placementDomains copies drawn without replacement from totalDomains domains, of which affectedDomains are gone.
P(k copies lost) = C(affected, k) * C(total - affected, placed - k) / C(total, placed)Each PG is then classified by what is left of it, with the same thresholds the pool-level verdict uses:
remaining = placed - k
lost when remaining < rebuildMinimum
blocked when remaining < minSize
degraded when k > 0
intact otherwiseMultiplying by pg_num gives the expected number of PGs in each state; the four numbers are rounded so that they add up to pg_num exactly.
A worked example, small enough to check by hand: ten hosts, replicated 3/2, pg_num 512, two hosts down. Of the 120 possible triples of hosts, 56 avoid both failed hosts, 56 contain exactly one and 8 contain both — so 239 PGs are untouched, 239 are degraded and 34 have only one copy left and block IO. None are lost, because one replica is enough to rebuild from. The end-to-end test pins exactly these numbers.
[ASSUMPTION] Uniform placement. Real CRUSH weights by capacity, so a cluster with very unevenly sized hosts deviates from this; the shape of the answer does not change. The implementation avoids factorials entirely and multiplies ratios instead, so it stays exact for a 2048 OSD cluster.
Source: packages/ceph-core/src/pg-impact.ts, and https://docs.ceph.com/en/latest/rados/operations/placement-groups/ (retrieved 2026-09-20).
Choosing `pg_num` by hand
pg_num can be set per pool instead of being derived. The value is used as given, including one that is not a power of two: Ceph accepts those, it only distributes less evenly, so the planner raises pg-num-not-power-of-two (info) and names the nearest recommendation rather than refusing the value. Everything downstream follows the chosen number, including the PGs-per-OSD findings and the generated pveceph pool create --pg_num.
Placement groups
Source: packages/ceph-core/src/pg.ts, citing https://docs.ceph.com/en/latest/rados/operations/pgcalc/ and https://docs.ceph.com/en/latest/rados/operations/placement-groups/ (both retrieved 2026-09-17).
For every pool:
osdCount= total OSDs in the cluster (MVP: one CRUSH root; per-device-class roots are a later extension).width=size(replicated) ork + m(erasure).- Ideal raw PG count:
ideal = targetPgsPerOsd × osdCount × (percent / 100) / width- Minimum: at least one PG participation per OSD and pool:
rawPgs = max(ideal, osdCount / width)- Rounding to a power of two, with the 25 % rule.
pgcalc's rule: take the nearest power of two; if that nearest value is more than 25 % _below_rawPgs, take the next power of two up instead.
Algorithm as implemented (roundToPgNum):
lower = largest power of two ≤ rawPgs (found by doubling, not log2 — avoids
float rounding pushing an exact power
of two to the wrong side)
upper = 2 × lower
candidate = (rawPgs − lower ≤ upper − rawPgs) ? lower : upper // nearest; ties round down
if (candidate < rawPgs × 0.75) candidate = upper // the 25 % guard
pgNum = candidaterawPgs ≤ 1 is special-cased to pgNum = 1.
Worked table (all values from the implementation plan and reproduced as Vitest vectors, test/pg-rounding.test.ts):
| raw | lower | upper | nearest (before guard) | gap of nearest vs. raw | 25 % guard triggered? | pgNum |
|---|---|---|---|---|---|---|
| 400 | 256 | 512 | 512 (upper is nearer) | — | no | 512 |
| 700 | 512 | 1024 | 512 | 700→512 is 26.9 % below | yes → 1024 | 1024 |
| 320 | 256 | 512 | 256 | 320→256 is 20.0 % below | no (≤ 25 %) | 256 |
| 60 | 32 | 64 | 64 (upper is nearer) | — | no | 64 |
| 20 | 16 | 32 | 16 | 20→16 is 20.0 % below | no (≤ 25 %) | 16 |
| 150 | 128 | 256 | 128 | 150→128 is 14.7 % below | no | 128 |
| 96 | 64 | 128 | 64 (tie, rounds down) | 96→64 is 33.3 % below | yes → 128 | 128 |
| 100 | 64 | 128 | 128 (upper is nearer) | 100→64 would be 36 % below, but 128 was already picked | no (already upper) | 128 |
| 3 | 2 | 4 | 2 (tie, rounds down) | 3→2 is 33.3 % below | yes → 4 | 4 |
| 1 | — | — | special case | — | — | 1 |
- Result
pgNum. Additionally, the pool's contribution to the cluster-wide PGs-per-OSD figure:
pgsPerOsdContribution = pgNum × width / osdCount
pgsPerOsd = Σ pools pgsPerOsdContributionThresholds, evaluated against the complete figure pgsPerOsdIncludingDerived (see the assumption below):
| Threshold | Constant | Finding | Severity |
|---|---|---|---|
| > 200 | WARN_PGS_PER_OSD | pgs-per-osd-high | warning — costs memory and CPU on every OSD |
| > 250 | MAX_PGS_PER_OSD (mon_max_pg_per_osd) | pgs-per-osd-critical | danger — Ceph refuses to create further pools without an override |
| < 50 | LOW_PGS_PER_OSD | pgs-per-osd-low | info — little parallelism, uneven data distribution |
A cluster with zero OSDs produces finding no-osds (error) instead of a PG plan.
- Autoscaler alternative, always shown alongside the static number:
pg_autoscale_mode onplustarget_size_ratio = percent / 100per pool. The autoscaler targetsTARGET_PGS_PER_OSD_AUTOSCALER = 100PGs/OSD (mon_target_pg_per_osd); the staticpgNumis only the starting point. Proxmox's own default for a newly created pool isPVE_DEFAULT_PG_NUM = 128PGs with the autoscaler inwarnmode (it does not resize automatically until switched toon).
`[ASSUMPTION]` EC metadata pool excluded from the headline PGs/OSD figure
Every erasure coded pool causes Proxmox to also create a small replicated metadata pool (see Redundancy rules). Its PG contribution is real but tiny. The library computes two numbers:
pgsPerOsd— configured pools only. This is the number shown as the headline KPI.pgsPerOsdIncludingDerived— configured pools plus every derived EC metadata pool. This is the number the 200/250/50 thresholds above actually evaluate, and the number interpolated into the resulting finding's text.
Source: packages/ceph-core/src/pg.ts (PgPlan.pgsPerOsd / PgPlan.pgsPerOsdIncludingDerived).
Redundancy rules
Every row is a finding emitted by packages/ceph-core/src/rules.ts. Severity follows the fixed order info < warning < danger < error; error means CRUSH cannot place the layout at all, so no commands are generated (see below).
Replication (`size` / `min_size`). Proxmox default: size 3 / min_size 2.
| id | severity | condition | meaning |
|---|---|---|---|
| min-size-one | danger | minSize === 1 | Writes are accepted with a single surviving copy. Any further failure loses data; the Proxmox documentation explicitly advises against this. |
| size-two | warning | size === 2 | No protection against a double failure. With min_size 2, every single OSD failure blocks IO on the affected PGs. |
| size-equals-min-size | warning | size ≥ 3 && size === minSize | Every failure blocks IO on affected PGs until recovery finishes. |
| size-exceeds-hosts | error | failure domain host and size > hosts | Not placeable: size N needs N hosts. |
| size-equals-hosts | info | failure domain host and size === hosts | Data stays available after one host failure, but Ceph cannot recreate the missing copy. Plan for hosts ≥ size + 1. |
Erasure coding. min_size is derived by Proxmox as k + 1 when m > 1, otherwise k (i.e. when m = 1) — see erasureMinSize(), sourced from the Proxmox VE Administration Guide.
| id | severity | condition | meaning |
|---|---|---|---|
| ec-metadata-pool-added | info | pool is erasure coded | Proxmox creates a small replicated metadata pool next to the EC pool, because RBD cannot keep its metadata (omap) on an EC pool. |
| ec-m-one | warning | m === 1 | No reserve during recovery: min_size equals k, so a second failure stops IO. |
| ec-rbd-write-amplification | info | pool application is rbd and erasure coded | EC for VM disks works on Proxmox but costs write performance and CPU; replication is the usual choice for VM storage, EC for backup/archive/CephFS data. |
| ec-hosts-insufficient | error | failure domain host and hosts < k + m | Not placeable: EC k+m with failure domain host needs at least k + m hosts (k + m + 1 recommended). |
| ec-hosts-exactly-sufficient | info | hosts === k + m | Chunks fit exactly, but Ceph cannot rebuild a lost chunk anywhere. Plan for k + m + 1 hosts. |
| ec-hosts-one-spare | info | hosts === k + m + 1 | Exactly one spare failure domain available for self-healing. |
Topology.
| id | severity | condition | meaning |
|---|---|---|---|
| nodes-below-three | error | hosts < 3 (MIN_HA_NODES) | A highly available Ceph cluster needs at least 3 nodes; fewer is a test setup, not production. |
| failure-domain-osd | warning | failure domain osd and hosts > 1 | CRUSH may place every copy of a PG on the same host; a single host failure can then take all copies at once. |
| mixed-osd-sizes | info | a node mixes OSD sizes | CRUSH weights OSDs by size; larger OSDs receive proportionally more PGs and load. |
_(The related imbalance finding host-oversized is emitted by capacity.ts, not rules.ts; it is documented under Capacity above.)_
Network. Minimum recommended link speed: MIN_RECOMMENDED_GBPS = 10 Gbit/s.
| id | severity | condition | meaning |
|---|---|---|---|
| public-network-slow | warning | publicGbps < 10 | Below the recommended minimum; recovery can take days and client latency suffers. |
| no-cluster-network | info | clusterGbps === null | Replication and recovery traffic share the link with client IO. |
| nvme-network-bottleneck | info | any NVMe OSD present and min(publicGbps, clusterGbps ?? publicGbps) ≤ 10 | The network, not the drives, will set the pace. |
Planning / structure.
| id | severity | condition | meaning |
|---|---|---|---|
| pool-percent-sum | warning | Σ pool percent ≠ 100 | The configured pool shares do not add up to 100 %. |
| fill-target-above-nearfull | warning | fillTargetPercent > 85 | The planned fill level is above the nearfull ratio; Ceph would already be warning at that level. |
| pg-num-not-power-of-two | info | hand-set pg_num is not 2ⁿ | Ceph accepts it, but some OSDs then carry about twice the placement groups of others. |
Failure simulation. Only raised while a failure is simulated; see "Failure scenarios" above.
| id | severity | condition | meaning |
|---|---|---|---|
| failure-data-lost | danger | a pool has remainingCopies < rebuildMinimum | The affected placement groups of that pool can neither be served nor rebuilt: zero copies replicated, fewer than k chunks erasure coded. |
| recovery-exceeds-nearfull | warning | self-healing possible, but recovery > nearfull | Restoring the lost copies would push the surviving OSDs past the nearfull ratio. |
Monitors and managers. Not a finding table entry but a recommendation (recommendedMonMgr): 3 monitors + 3 managers when nodeCount ≥ 3 (the Proxmox/Ceph recommendation for HA); below that, one monitor/manager per available node, alongside the nodes-below-three error.
Source: packages/ceph-core/src/rules.ts, citing https://pve.proxmox.com/pve-docs/chapter-pveceph.html and https://docs.ceph.com/en/latest/rados/operations/erasure-code/ (both retrieved 2026-09-17).
Recovery estimate
This is a rough, deliberately simple estimate — not a prediction. Real recovery time depends on osd_recovery_* tuning, CPU, concurrent client load, object size distribution and how evenly data is spread across the cluster, none of which the planner knows. The tool always shows a range, never a single number, and labels it as such.
Source: packages/ceph-core/src/recovery.ts, packages/ceph-core/src/constants.ts. Marked [ASSUMPTION] in full — the plan does not source this model from official documentation.
Model:
bytesToRecover = lostRawBytes × (fillTargetPercent / 100)
networkBytesPerSecond = min(publicGbps, clusterGbps ?? publicGbps)
× BYTES_PER_SECOND_PER_GBPS × RECOVERY_NETWORK_SHARE
diskBytesPerSecond = Σ (surviving OSDs) writeBytesPerSecond(deviceClass)
× RECOVERY_DISK_SHARE
effectiveBytesPerSecond = min(networkBytesPerSecond, diskBytesPerSecond)
hours = bytesToRecover / effectiveBytesPerSecond / 3600
lowHours / highHours = hours × RECOVERY_RANGE_LOW / hours × RECOVERY_RANGE_HIGHEvery constant, named exactly as in constants.ts:
| Constant | Value | Meaning |
|---|---|---|
| BYTES_PER_SECOND_PER_GBPS | 125,000,000 B/s | Bytes/second per 1 Gbit/s of link speed |
| RECOVERY_NETWORK_SHARE | 0.5 | Share of the link assumed available for recovery traffic; the rest is left for clients |
| RECOVERY_DISK_SHARE | 0.3 | Share of a surviving OSD's sustained write throughput spent on recovery while still serving clients |
| OSD_WRITE_BYTES_PER_SECOND.hdd | 120,000,000 B/s | Assumed sustained sequential write throughput, HDD — conservative mid-range, not a vendor peak figure |
| OSD_WRITE_BYTES_PER_SECOND.ssd | 400,000,000 B/s | Same, SATA SSD — the 6 Gbit/s interface is the ceiling, whatever the flash could do |
| OSD_WRITE_BYTES_PER_SECOND.sas | 800,000,000 B/s | Same, SAS SSD — a 12 Gbit/s interface lifts that ceiling |
| OSD_WRITE_BYTES_PER_SECOND.nvme | 1,500,000,000 B/s | Same, NVMe |
| RECOVERY_RANGE_LOW | 0.5× | Lower end of the displayed range |
| RECOVERY_RANGE_HIGH | 2× | Upper end of the displayed range |
The estimate is only computed when the simulated failure allows self-healing at all (FailureAnalysis.anySelfHealing); otherwise applicable is false and no time is shown.
Generated commands
Source: packages/ceph-core/src/commands.ts, citing https://pve.proxmox.com/pve-docs/chapter-pveceph.html (retrieved 2026-09-17).
The tool emits two tabs: a pveceph-flavoured script (install, init, monitors/managers, OSDs, pools) matching the layout entered, and a second tab with the equivalent native ceph osd pool create / ceph osd pool set / ceph osd erasure-code-profile set commands for clusters not managed through pveceph.
`--size` and `--min_size` are always shown, even when they equal the Proxmox default (size 3 / min_size 2). This is deliberate: the redundancy level is the decision this tool exists to help make, so it is never left implicit. The showAllParameters toggle only adds _further_ flags that do repeat a default (--target_size_ratio, --application, --crush_rule) — it never removes --size/--min_size. See docs/DECISIONS.md, ADR-007, for the resulting difference from the plan text.
The Ceph public/cluster network is a fixed placeholder (10.10.10.0/24 / 10.10.20.0/24), never a value the user typed. ClusterSpec only carries link speeds (publicGbps, clusterGbps), not a CIDR — there is no field for it to come from. This is a deliberate security boundary: the generated commands are meant to be pasted into a root shell, and the tool never turns free-form user input into a string that ends up there unexamined. See Security model below and ADR-008.
No commands are produced for a layout that cannot be placed. generateCommands() returns an empty array whenever any finding has severity error (checked via hasBlockingError), and — independently — whenever any node or pool name fails the same name check used for permalink validation. An unplaceable plan or an unsafe name must never hand out commands that would create it; this holds even if a caller passes showAllParameters: true.
Security model of the planner itself
The planner has no backend, but its state is fully attacker-influenceable through the permalink, so the domain library treats every ClusterSpec as untrusted until validated.
- The permalink is untrusted input. State round-trips through
serializeSpec/deserializeSpec(lz-string.compressToEncodedURIComponent).deserializeSpecnever throws: it bounds the compressed length, bounds the decompressed length, uses plainJSON.parse(no reviver, noeval), and hands the parsed object tovalidateClusterSpec, which rebuilds a new object from validated primitives only — no unexpected or prototype-polluting property can survive into the application. A value that fails validation is rejected outright, never "repaired" or coerced. - Names are restricted to
^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$(SAFE_NAME_PATTERN), plus a reject-list for.and... This is deliberately narrower than what Ceph itself accepts: no spaces, no quotes, no shell metacharacters, no Unicode look-alikes — because node and pool names are interpolated, unescaped, into commands meant for a root shell. Anything outside the pattern is rejected, never escaped or sanitised. - All counts and sizes are bounded (
LIMITSinvalidation.ts), so a crafted link cannot make the browser allocate or iterate an unbounded amount of work:
| Limit | Value |
|---|---|
| maxNodes | 64 |
| maxOsdGroupsPerNode | 8 |
| maxOsdsPerGroup | 128 |
| maxTotalOsds | 2048 |
| maxPools | 16 |
| maxNameLength | 63 |
| minOsdSizeBytes | 1,000,000,000 (1 GB) |
| maxOsdSizeBytes | 1,000,000,000,000,000 (1 PB) |
| maxReplicaSize | 10 |
| maxErasureK | 16 |
| maxErasureM | 8 |
| maxErasureWidth (k + m) | 24 |
| maxGbps | 800 |
| minGbps | 1 |
| maxSerializedLength (compressed #s= payload) | 8192 |
| maxDecompressedLength (decompressed JSON) | 65536 |
- Deserialisation never throws. Every failure path (empty input, over-long input, decompression failure, invalid JSON, wrong schema version, structural mismatch, failed validation) returns a typed
DeserializeResultwith a friendlyStateError; the UI falls back to the default preset. This is exercised directly by property-based tests (test/state.test.ts,test/security.test.ts) over arbitrary strings, plus a fixed list of hostile payloads (shell metacharacters, script tags, prototype-pollution attempts, over-long strings). - No user data ever leaves the browser. The library performs no network I/O, reads no cookies, and calls no external service; the only external dependency at runtime is
lz-stringfor the permalink codec.
Assumptions
Every place in the source marked [ASSUMPTION] (searched across packages/ceph-core/src), in file order:
- Imbalance correction is an approximation (
src/capacity.ts,effectiveRawForWidth). Exact when at most one host is oversized; conservative (never overpromises) with several oversized hosts. Affects:effectiveRawBytes,usableBytes,plannedUsableBytes, and thehost-oversizedfinding. - EC metadata pools are excluded from the headline PGs-per-OSD figure (
src/pg.ts,PgPlan.pgsPerOsd). The complete figure,pgsPerOsdIncludingDerived, is what the 200/250/50 thresholds actually evaluate. Affects: the KPI shown to the user vs. the number thepgs-per-osd-*findings are based on. - The whole recovery-time model is a deliberately simple upper bound, not a prediction (
src/recovery.ts, module-level). Affects: every number in the "Recovery estimate" panel. - Half the network link and 30 % of surviving OSD write throughput are assumed available for recovery traffic (
src/recovery.ts,estimateRecovery) — restates assumptions 6 and 7 below at the point they are combined. Affects:networkBytesPerSecond,diskBytesPerSecond, and thereforehours. - `EC_METADATA_POOL_PERCENT = 1` % (
src/constants.ts) — the share of raw cluster capacity reserved for the replicated metadata pool Proxmox creates alongside every erasure coded pool. The real pool is tiny; 1 % is a deliberately generous placeholder. Affects: the metadata pool's own capacity/PG numbers (not the EC data pool's). - `RECOVERY_NETWORK_SHARE = 0.5` (
src/constants.ts) — the fraction of the link Ceph is assumed to use for recovery traffic, the rest reserved for clients. Affects: the recovery estimate's network ceiling. - `RECOVERY_DISK_SHARE = 0.3` (
src/constants.ts) — the fraction of a surviving OSD's sustained write throughput spent on recovery while still serving clients. Affects: the recovery estimate's disk ceiling. - `OSD_WRITE_BYTES_PER_SECOND` per device class (
src/constants.ts: HDD 120 MB/s, SATA SSD 400 MB/s, SAS SSD 800 MB/s, NVMe 1500 MB/s) — conservative mid-range sustained sequential write figures, not vendor peak numbers. Affects: the recovery estimate's disk ceiling. - `RECOVERY_RANGE_LOW = 0.5`× / `RECOVERY_RANGE_HIGH = 2`× (
src/constants.ts) — the multipliers used to turn a single point estimate into the displayed range. Affects: the low/high bounds shown in the "Recovery estimate" panel.
Two further judgement calls follow directly from the implementation plan (section 5.5/5.6) but are not currently tagged [ASSUMPTION] in the corresponding code comment in rules.ts; they are listed here for completeness because no specific numeric threshold in the official documentation backs them:
- `ec-rbd-write-amplification` (
src/rules.ts) — "EC for VM disks works but costs write performance and CPU; replication is the usual choice for VM storage, EC for backup/archive/CephFS data" is presented as a practitioner recommendation, not a value derived from a cited formula. - `nvme-network-bottleneck` (
src/rules.ts) — flags NVMe OSDs behind a link at or below 10 Gbit/s as an informational bottleneck hint without a supporting throughput calculation.
Sources
All retrieved 2026-09-17.
- Ceph Documentation — PG Calc (formula, minimum, power-of-two rounding with the 25 % rule, target PGs/OSD 100 vs. 200): https://docs.ceph.com/en/latest/rados/operations/pgcalc/
- Ceph Documentation — Placement Groups (autoscaler,
mon_target_pg_per_osd,mon_max_pg_per_osd): https://docs.ceph.com/en/latest/rados/operations/placement-groups/ - Ceph Documentation — Storage Capacity / full ratios (
mon_osd_nearfull_ratio0.85,mon_osd_backfillfull_ratio0.90,mon_osd_full_ratio0.95): https://docs.ceph.com/en/latest/rados/configuration/mon-config-ref/ - Ceph Documentation — Erasure Code: https://docs.ceph.com/en/latest/rados/operations/erasure-code/
- Proxmox VE Administration Guide — Deploy Hyper-Converged Ceph Cluster (defaults
size 3/min_size 2, 128 PGs, autoscaler modes,pvecephcommands, EC pools with a metadata pool,min_sizerulek+1/k, 3 monitors, 10 GbE, separate cluster network): https://pve.proxmox.com/pve-docs/chapter-pveceph.html - Proxmox VE Wiki — Ceph pages and forum threads (context only, not used as a formula source): https://pve.proxmox.com/wiki/ , https://forum.proxmox.com/
- Comparable tools (referenced only to differentiate this planner, never copied from): 45drives.com/ceph/placement-groups, zdalnyadmin.com.pl/ceph-calculator, bennetgallein.de/tools/ceph-calculator
Changelog of this methodology
| Version | Date | Change |
|---|---|---|
| 1.0 | 2026-09-18 | First version, covering packages/ceph-core as of milestone M1 (domain library complete, test vectors V1–V10 passing). |