The recovery settings and what each does

Advanced⏱ ~17 minceph

What you'll learn

State what each recovery setting controls
Identify which are active under the current scheduler
Change them safely and observe the effect
Avoid settings that have been superseded

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Recovery settings are copied from blog posts more than any other part of Ceph configuration, and many of the values circulating apply to a scheduler that is no longer the default. Knowing what each one does is what distinguishes tuning from cargo cult.

The settings

ceph config get osd osd_recovery_max_active
ceph config get osd osd_recovery_max_active_hdd
ceph config get osd osd_recovery_max_active_ssd
ceph config get osd osd_recovery_op_priority
ceph config get osd osd_recovery_sleep_hdd
ceph config get osd osd_recovery_sleep_ssd

Setting	Unit	Effect
`osd_recovery_max_active`	operations	concurrent recovery ops per OSD
`osd_recovery_max_active_hdd`	operations	the HDD-specific value
`osd_recovery_max_active_ssd`	operations	the SSD-specific value
`osd_recovery_sleep_hdd`	seconds	delay inserted between recovery ops
`osd_recovery_sleep_ssd`	seconds	the SSD-specific delay
`osd_recovery_op_priority`	1–63	queue priority relative to client ops

The device-class-specific variants take precedence over the generic one where the OSD’s class matches, which is why setting the generic value alone often has no visible effect.

Which are active

ceph config get osd osd_op_queue

With mclock_scheduler — the default since Quincy — the recovery concurrency and sleep settings are overridden by the profile:

ceph config show osd.0 | grep -E 'osd_recovery_max_active|osd_recovery_sleep'
ceph config get osd osd_mclock_profile

osd_recovery_op_priority is a WPQ concept and has no effect under mClock, which allocates by reservation and weight rather than by strict priority.

Changing safely

# check what is currently effective, not what is configured
ceph config show osd.0 | grep recovery

# change
ceph config set osd osd_recovery_max_active_hdd 5

# confirm it took effect
ceph config show osd.0 | grep osd_recovery_max_active_hdd

ceph config get shows the configured value; ceph config show shows what the running daemon is actually using. Under mClock those differ, and reading the wrong one is the usual reason a change appears to do nothing.

Superseded settings

Setting	Status
`osd_recovery_threads`	removed
`osd_recovery_max_chunk`	rarely useful
`osd_client_op_priority`	WPQ only
`osd_recovery_op_priority`	WPQ only

Values recommended in older material frequently include these, which is a reliable signal that the material predates mClock.

Quiz

Knowledge check · 4 questions

Q1. Why does setting `osd_recovery_max_active` sometimes have no effect?

It requires an OSD restart, since concurrency limits are read once when the daemon starts The device-class-specific variant takes precedence, or mClock overrides it entirely It applies only to backfill operations rather than to the log-based recovery path It was removed in recent releases along with osd_recovery_threads and the WPQ knobs
Q2. `osd_recovery_op_priority` is inert on a cluster running the default scheduler.

True False
Q3. Apply tuning advice found in an online guide.

A guide recommends setting osd_recovery_threads=4, osd_recovery_max_active=8, and osd_recovery_op_priority=1 to reduce recovery impact. The cluster runs a current release with default settings.
Q4. Why does mClock override the recovery concurrency settings rather than honouring them?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Verify recovery setting changes with ceph config show against a specific daemon rather than ceph config get; under mClock the two disagree and the difference is the whole reason a change appears to do nothing. Treat osd_recovery_threads or osd_recovery_op_priority in any guide as a marker that it predates the current scheduler.

Cross-course references

Kubernetes: deprecated flags in old guides cause the same silent no-ops
Linux: I/O scheduler changes invalidate tuning advice written for the previous one