Configuring Btrfs: where storage breaks and what to check
Storage under load breaks not when the disk fails, but earlier and more quietly. Btrfs calculates block checksums, but without regular integrity checks, data corruption is discovered at read time—when the source and its copies are already damaged.
Configuring Btrfs starts with these checks running on a schedule, rather than on the administrator's request after a complaint.
The second failure point is snapshots. At first they take up almost no space, but under active writes consumption grows, and the pool hits full capacity: the filesystem goes read-only, writes stop until manual intervention.
Next to it is the array: a RAID profile protects against media failure, but not against a logical error and not against corruption propagated across copies.
The third is recovery after disk failure. Without a verifiable replica and a pre-defined procedure, recovery turns into manual troubleshooting: what to mount, which snapshot to consider the reference, which subvolumes to roll back.
Subvolume layout, snapshot retention policy, and check schedule determine what such a failure will cost.
Below we examine typical configuration defects and the checks that reveal them: how data integrity is closed, uncontrolled snapshot growth, and replication you can trust.
What managed storage provides: snapshots, integrity, replicas
Data snapshots in Btrfs are designed as copy-on-write: a snapshot does not duplicate the volume's contents but references already written blocks.
Therefore, a pre-update snapshot takes seconds, and rolling back changes is switching the root to the previous snapshot, not restoring a backup.
Rollback time after a failed update drops from hours to minutes, and old snapshots do not bloat the volume if they are deleted on a schedule.
Integrity rests on checksums: they are calculated for data and metadata blocks and verified on every read, not only during a scheduled check.
A damaged sector on disk surfaces before the application receives corrupted data—the share of failures discovered only after data loss falls almost to zero.
In mirrored profiles, a damaged block is replaced with a working copy right during read: self-healing runs in the background, without manual intervention and without stopping the service.
Data replication is built on incremental snapshot transfer: only the difference between two points goes to the second node, not the entire array.
This also determines recovery time—a node is brought up from a replica predictably quickly, because only the volume of changes since the last synchronization is transferred, not a full storage image.
For an engineer, the practical meaning is three metrics visible on charts: how many minutes it takes to roll back a failed release, what share of corruption was caught before data loss, and how quickly a node is brought up from a replica.
Snapshots, RAID, and replication: comparing approaches
Btrfs storage schemes differ not by tools, but by the failure class they close. A local snapshot subvolume helps with a failed update, a mirror with drive failure, a replica on a second node with loss of the machine itself. Below is a comparison by when a scheme is appropriate and where its limit lies.
| Option | When it fits | Limitations |
|---|---|---|
| Local snapshots | Frequent releases and data schema migrations, need rollback in seconds | Live on the same array: filesystem corruption or disk failure takes data along with snapshots |
| Disk mirroring | Need continuity during drive failure, reading from two copies | Does not protect against operator error, a failed script, or ransomware—writes are duplicated to both disks |
| Replica on a second node | Need protection against node loss and an external recovery point | Data lags by the send interval; network bandwidth and monitoring of the incremental chain are required |
| Hybrid scheme | Production with requirements for recovery time and history depth | More expensive to maintain: need to monitor the schedule, free space for snapshots, and replica state |
In practice, a hybrid scheme is chosen: local mirror plus scheduled snapshots and incremental sending of changes to a second node. Then rollback after a failed update takes minutes, and switchover during node failure fits within the agreed recovery time.
The key limitation of snapshots is one: they do not replace a backup. We explain how to assemble such a configuration without registry growth and extra copies.
How Btrfs configuration proceeds: stages of work
We start with an audit: we look at the load profile, share of small files, growth rate, and presence of databases or virtual machines. This determines which datasets get separate subvolumes and where to enable compression. Then the route looks like this.
- Storage audit. Current layout, drive state, fill history, daily I/O profile. It shows what will survive disk degradation and what requires a mirror.
- Placement scheme. We lay out data, logs, backups, and recovery points across subvolumes so that a snapshot of one dataset does not pull the others. We choose data and metadata profiles separately.
- Layout and mount options. We create the filesystem, enable transparent compression and integrity checking, and select mount options for the workload.
- Snapshots and schedule. Automatic timer-based snapshots with a retention policy: how many copies we keep, what goes to archive, what is deleted by count rather than by date.
- Replication. Incremental subvolume transfer to a second node with checksum verification on the receiver and clear behavior when the channel breaks.
- Failure scenario testing. We run drive failure, lack of space, a damaged block, and snapshot recovery. We separately test array scrub.
- Handover to operations. Placement scheme, schedules, mount options, and recovery procedure. The on-call team learns to read storage state before an alert arrives.
Configurations, diagrams, and procedures: what you keep
After project handover, you keep not only working storage, but also a set of artifacts you can use to develop it, hand it to another team, and recover it without us. We document every decision in writing—from mount parameters to the procedure in an incident.
- Working configurations — mount settings files for subvolumes, compression and redundancy profile parameters, with an explanation of why each parameter was chosen and how to change it safely.
- Data and replica placement scheme — which pools are assembled, what resides on fast drives, where the replication stream goes, and at what frequency.
- Snapshot schedule and rotation policy — how many snapshots we keep by hour, day, and week, what is deleted automatically, and what remains for rollback to the previous release.
- Access rules — to whom and at what level subvolumes are exposed, how service and administrator rights are separated, and what is forbidden to do manually.
- Incident response procedure — step-by-step actions for drive degradation, checksum errors, pool overflow, and replication node loss.
- Storage documentation — subvolume tree, mount points, service dependency map, configuration change log.
- Check and recovery procedures — how integrity checking is started, how rollback and data transfer to the standby node are performed.
Documents are written for your infrastructure, not from a template: an engineer on your team can use them to repeat the configuration independently, verify it, and hand it to the on-call engineer.
Case study: failure rate and recovery time before and after
The customer came with storage on the edge: shared directories, build artifacts, and database copies resided on one set of disks with manual partitioning.
Disk failure did not degrade services, it stopped them for hours—recovery came from the nightly copy, and data for the day before the failure was lost irretrievably. System updates were rolled back manually: no recovery point existed.
We moved the storage to Btrfs: disks were assembled into mirrored sets with checksums, directories were split across subvolumes with different retention policies, state changes are captured by scheduled snapshots and sent incrementally to a standby node. A copy of the current state appears every few minutes, not once a day.
Metrics before and after: share of failures causing downtime—from 40% to zero over the observed period; update rollback time—from 3–4 hours of manual work to a few minutes to return a snapshot; share of recoveries without data loss—from 60% to 100%.
A separate class of "silent" block corruption is gone: checksums catch it on read, not through user complaints.
Capacity now grows by adding a disk to the set, integrity checking runs without stopping services, and before any update an engineer takes a snapshot and knows exactly that rollback will take minutes. Downtime has ceased to be a standard storage operation scenario.
How a snapshot differs from a replica and when RAID is needed
A snapshot in Btrfs is not a copy of data, but a separate subvolume referencing the same extents: a block stops being shared only at the moment of writing.
While there are no changes, the snapshot takes almost no space, but it provides a recovery point—rolling back a failed update, migration, or directory deletion can be done in minutes, without unpacking an archive.
It does not protect against disk failure: the snapshot lives in the same filesystem, on the same drive. That failure class is closed by a replica—incremental sending of snapshots to another node via send/receive.
It saves you when a server is lost, the filesystem is destroyed, or an operator makes a mistake in production, but it is asynchronous: recovery goes to the last received point, not to the moment of failure, and the loss window depends on the send schedule.
Physical disk failure is closed by a third mechanism—mirroring via RAID1 or RAID10 profiles, configured separately for data and metadata.
The filesystem verifies checksums, substitutes the correct copy on mismatch, and continues working until the disk is replaced, while background scrub detects silent corruption that a mirror alone does not notice.
Important: the array synchronously repeats both a write error and a deletion, so it is not a replacement for a replica.
Schemes are not chosen, but combined. A mirror holds live data, scheduled snapshots with a retention policy provide fast rollback, and sending to a separate node covers site loss.
Extra costs arise where protection is duplicated: for example, an expensive array for snapshots that are already sent to a second node. The order is the reverse: first name what we are protecting against and within what time we must recover, then calculate disks and schedule.
Common technical concerns before implementation
Concerns before moving storage to Btrfs relate not to the filesystem itself, but to the transition: service unavailability, behavior during drive failure, snapshot volume, integrity checking, timelines. We answer point by point.
Will there be downtime during migration?
On a single server, unavailability is a volume switchover and mount verification, usually minutes. In a cluster, we go through nodes one at a time, while the rest carry the load: large arrays are synchronized by changes and switched over when ready, not on a schedule.
What happens if a disk fails?
With RAID1 or RAID10, the array continues operating in degraded mode, writes do not stop, and damaged blocks are marked by checksums. Drive replacement and recovery proceed online. We do not plan RAID5/6 for actively writing workloads.
How much will snapshots grow in volume?
A snapshot does not copy data but captures state: only changes after its creation take up space. A retention policy—daily snapshots for two weeks, weekly for a couple of months—keeps growth within a few percent of the volume.
How is data integrity checked?
Checksums are calculated for data and metadata blocks, so corruption is visible on read, not during recovery. Background scrub compares checksums with the redundant copy and restores the block from it. Backup remains a separate contour.
How long does the work take?
Configuring btrfs on a single server takes days, including a test run and rollback verification; a cluster with replication takes weeks in stages, with acceptance after each. We need access, a switchover window, and your current backup scenarios.
Let's discuss your task: work plan and estimate for your setup
To make the storage estimate based on facts rather than general considerations, we need source data about how storage is currently arranged.
Send fragmented exports—configurations, array state, descriptions of procedures: consolidating them into a single picture is our job, not yours.
- Volume layout: where the root is, where data is, whether a separate volume is allocated for snapshots and metadata.
- Subvolume scheme: what is snapshotted on a schedule, what is published as a separate dataset, what deliberately lives without snapshots.
- Redundancy: whether metadata is duplicated separately from data, and what happens during array degradation.
- Mount options and compression: whether compression is enabled, what limits are set for qgroups.
- Retention policy: snapshot frequency and depth, rotation period, what counts as a rollback point.
- Replication: locally or to a remote node, incremental transfer, channel bandwidth, acceptable lag.
- Problem areas: growth in snapshot count, stuck balancing, disk failures that have already occurred.
- Constraints: maintenance window, access levels, target recovery time, and acceptable data loss.
Then we assemble a work plan: inventory of the current layout, integrity and free space checks, redundancy profile calculation, snapshot schedule, replication scheme, check and rollback procedure.
We return with a proposal for the scheme as a document—with justification for each decision and an implementation sequence without stopping service.
Describe the task and attach what you have at hand—we will return with an estimate and plan.