BTRFSMAINTENANCE(8)

💖 NAME 💖

btrfsmaintenance — automate btrfs maintenance tasks ✨

(btw bestie, this is the page for btrfsmaintenance from the System Manager's Manual, section 8 — yes she's that girl 💅)

---

🎀 NOTE 🎀

okay so real talk, this man page is NOT the whole story. you also need to read /usr/share/doc/btrfsmaintenance/README.Debian alongside it, no cap. both. not one or the other. both 🫶

---

🌸 DESCRIPTION 🌸

• Tuning periodic snapshotting ⟨#tuning-periodic-snapshotting⟩

so basically: this is a bundle of scripts that rides shotgun with the btrfs filesystem and handles a few maintenance chores for you automatically. the chores in question are scrub, balance, trim and defragmentation 💫

each one of these tasks can be switched on/off and configured independently — like, they don't all have to be doing the most at once. the default config values were picked to fit the default installation profile, i.e. btrfs on the root filesystem 🏠

the overall tuning of those defaults is meant to give you a good balance between the effects of the tasks and keeping the impact on the rest of your system's work low. if that doesn't fit what you need, bestie, just go ahead and adjust the settings ✨

🛠️ Tasks 🛠️

the next few sections break each task down in detail. there's one config option that touches task concurrency: BTRFS_ALLOW_CONCURRENCY. it exists to avoid extra high resource consumption or unexpected interaction among the tasks — basically it serializes them in the order they're started by timers. so like, one at a time, in line, in order, periodt 🚦

🌊 scrub

Description: the scrub operation reads all data and metadata off the devices and verifies the checksums. it's not mandatory, but it can call out problems with faulty hardware early, because it touches data that might not even be in use, plus bit rot 👀

if there's redundancy in your data/metadata — like the DUP or RAID1/5/6 profiles — scrub is able to repair the data automatically when there's a good copy available. iconic behavior honestly 💅

Impact when active: intense read operations are happening, and they may slow down or block other filesystem activities — possibly only for short periods though.

Tuning:

• the recommended period is once in a month, but a weekly period is also acceptable 🗓️
• you can turn off the automatic repair (BTRFS_SCRUB_READ_ONLY)
• the default IO priority is set to idle, but scrub may take a long time to finish — you can change the priority to normal (BTRFS_SCRUB_PRIORITY)

Related commands:

• you can check the status of the last scrub run (whether it was manual or through the cron job) with btrfs scrub status /path
• you can cancel a running scrub anytime if you find it inconvenient (btrfs scrub cancel /path). the progress state is saved each 5 seconds, and next time scrub will start from that point 🌈

⚖️ balance

Description: the balance command can do a lot of things — in general it moves data around in big chunks. here we use it to reclaim back the space of underused chunks so that space can be allocated again according to current needs 🔄

the point is to prevent some corner cases where it's not possible to, e.g., allocate new metadata chunks because the whole device space is reserved for all the chunks — even though the total space occupied is smaller and the allocation should succeed. rude, honestly.

the balance operation needs enough workspace so it can shuffle data around. by workspace we mean device space that has no filesystem chunks on it — do not confuse this with free space as reported by, e.g., df 🙈

Impact when active: possibly big. there's a mix of read and write operations, and it's seek-heavy on rotational devices. this can interfere with other work in case the same set of blocks is affected 😭

the balance command uses filters to do the work in smaller batches.

before kernel version 5.2, the impact with quota groups enabled can be extreme. the balance operation performs quota group accounting for every extent being relocated, which can have the impact of stalling the file system for an extended period of time. 💀

Expected result: if possible, all the underused chunks are removed, and the value of total in the output of btrfs fi df /path should be lower than before. check the logs 📝

the balance command may fail with a no-space reason, but this is considered a minor fault, because the internal filesystem layout may prevent the command from finding enough workspace. this might be a time for manual inspection of space 🔍

Tuning:

• you can make the space reclaim more aggressive by adding a higher percentage to BTRFS_BALANCE_DUSAGE or BTRFS_BALANCE_MUSAGE. a higher value means a bigger impact on your system and becomes very noticeable 👀
• the metadata chunks usage pattern is different from data, and it's not necessary to reclaim metadata block groups that are more than 30 full. the default maximum is 10, which should not degrade performance too much, but may be suboptimal if the metadata usage varies wildly over time. the assumption is that underused metadata chunks will get used at some point, so it's not absolutely required to do the reclaim 💭
• the useful period highly depends on the overall data change pattern on the filesystem 🦋

Changed defaults since 0.5:

versions up to 0.4.2 had the usage filter set up to 50% for data and up to 30% for metadata. based on user feedback, those numbers have been reduced to 10% (data) and 5% (metadata) ✨ the system load during the balance service will be smaller, and the result of space compaction is still reasonable. multiple data chunks filled to less than 10% can be merged into fewer chunks. the file data can change in large volumes — e.g. deleting a big file can free a lot of space. if the space is left unused for the given period, it's desirable to make it more compact. metadata consumption follows a different pattern, and reclaiming only the almost-unused chunks makes more sense — otherwise there's enough reserved metadata space for operations like reflink or snapshotting 🫶

🧹 trim

Description: the TRIM operation (aka. discard) can instruct the underlying device to optimize blocks that are not used by the filesystem. this task is performed on-demand by the fstrim utility ✨

this makes sense for SSD devices or other types of storage that can translate the TRIM action into something useful (e.g. thin-provisioned storage) 💾

Impact when active: should be low, but it depends on the amount of blocks being trimmed.

Tuning:

• the recommended period is weekly, but monthly is also fine 🗓️
• the trim commands might not have an effect and are up to the device — e.g. a block range too small, or other constraints that may differ by device type/vendor/firmware 👑
• the default configuration is off, because of the system fstrim.timer

🧩 defrag

Description: run defragmentation on configured directories. this is for convenience, and it's not necessary, because defragmentation needs are usually different for various types of data 🌸

please note that the defragmentation process does not descend to other mount points and nested subvolumes or snapshots. all nested paths would need to be enumerated in the respective config variable. the command utilizes find -xdev — you can use that to verify in advance which paths the defragmentation will affect 👀

---

⏰ Periodic scheduling ⏰

so there are now two ways to schedule and run the periodic tasks: cron and systemd timers. only one can be active on a system, and this should be decided at installation time 🎯

🕰️ Cron

cron takes care of the periodic execution of the scripts — but honestly the scripts can be run any time directly from /usr/share/btrfsmaintenance/, respecting the configured values in /etc/default/btrfsmaintenance 💖

the changes to the configuration file need to be reflected in the /etc/cron directories, where the scripts are linked for the given period.

if the period is changed, the cron symlinks have to be refreshed:

• manually — use systemctl restart btrfsmaintenance-refresh (or the rcbtrfsmaintenance-refresh shortcut) 💅
• using a file watcher — if btrfsmaintenance-refresh.path is enabled, this will utilize the file monitor to detect changes and will run the refresh 👀

🌀 Systemd timers

there's a set of timer units that run the respective task script. the periods are configured in the /etc/default/btrfsmaintenance file as well. please note that the '.timer' and the respective '.service' files must be manually enabled before the timers will work properly ⚠️

some package managers (e.g. apt) will configure the timers automatically at install time — you can check with ls /usr/lib/systemd/system/btrfs* 🔍

to install the timers manually, run btrfsmaintenance-refresh-cron.sh timer 🚀

---

🚀 Quick start 🚀

refer to /usr/share/doc/btrfsmaintenance/README.Debian for instructions to enable the Systemd timers 🫶

⏳ cron jobs

the periodic execution of the tasks is done by the 'cron' service. symlinks to the task scripts are located in the respective directories in /etc/cron.<PERIOD> 🔗

the script btrfsmaintenance-refresh-cron.sh will synchronize the symlinks according to the configuration files. this can be called automatically by a GUI configuration tool if it's capable of running post-change scripts or services. in that case there's the btrfsmaintenance-refresh.service systemd service ✨

this service can also be automatically started upon any modification of the configuration file in /etc/default/btrfsmaintenance by enabling the btrfsmaintenance-refresh.path systemd watcher 👑

---

okay bestie that's not the end — hang tight, there's more incoming 💖

🎀 Tuning periodic snapshotting 🎀

okay bestie, so there are like so many tools and handwritten scripts out there for managing periodic snapshots and cleaning them up. 💖 And the problem they all hit is the same: you gotta tune the retention policy so it's constrained by the filesystem size and you don't just... run out of space. 😭

This section walks through the factors that affect all of that, using snapper (https://snapper.io) as the example, but adapting it to other tools should be straightforward. fr fr. ✨

---

🌸 Intro 🌸

Snapper is a tool for managing snapshots of btrfs subvolumes. It can create snapshots of a given subvolume manually, periodically, or in a pre/post way for a given command. And it can be configured to retain existing snapshots according to time-based settings. 🎀

The thing is, the retention policy can be super different depending on your use case, so we need to be able to find the matching settings. Periodt.

Those settings should satisfy the user's expectation about storing previous copies of the subvolume — without taking up too much space. In the extreme case, you'd consume the whole entire filesystem space and prevent some operations from finishing. 💀 not cute.

So to avoid all that drama, snapper's settings should be tuned according to the expected use case and the filesystem size. iykyk. 🦋

🌈 Sample problem 🌈

Default settings of snapper on a default root partition size can easily lead to no-space conditions (all TIMELINE values set to 10). Frequent system updates make it happen earlier, but this also affects long-term use. 😭 so yeah, watch out.

👑 Factors affecting space consumption 👑

1. frequency of snapshotting
2. amount of data changes between snapshots (delta)
3. snapshot retention settings
4. size of the filesystem

Each one gets its own little explainer below, don't worry bestie. 💅

The way the files are changed affects the space consumption. When new data overwrites existing data, the new data will be pinned by the following snapshot, while the original data will belong to the previous snapshot. What this means: the allocated file blocks are freed after the last snapshot pointing to them is gone. 🧚 so like, they linger until everything pointing at them dips.

✨ Tuning ✨

The administrator/user is supposed to know the approximate use of the partition with snapshots enabled. 👑

The decision criteria for tuning is space consumption, and we're optimizing to maximize retention without running out of space. 🔥

All the factors are intertwined, so we can't give you definite answers — we can only describe the tendencies. ngl that's just how it is.

💜 Snapshotting frequency 💜

• automatic: if turned on with the TIMELINE config option, the periodic snapshots are taken hourly. The daily/weekly/monthly/yearly periods will keep the first hourly snapshot in the given period. ⭐
• at package update: a package manager with snapper support will create pre/post snapshots before/after an update happens.
• manual: the user can create a snapshot manually with snapper create, with a given snapshot type (i.e. single, pre, post). 💅

🍓 Amount of data change 🍓

This is a parameter that's hard to predict and calculate. We work with rough estimates, e.g. megabytes, gigabytes etc. 🤷 like, vibes-based math, but for storage.

🦋 Retention settings 🦋

The user is supposed to know the possible needs of recovery or examination of previous file copies stored in snapshots. 🔍

It's not recommended to keep too old snapshots — e.g. monthly or even yearly — if there's no apparent need for that. And listen: the yearly snapshots should not substitute backups, because they reside on the same partition and cannot be used for recovery. 💀 no cap.

🧚 Filesystem size 🧚

Bigger filesystem allows for longer retention, higher frequency updates and amount of data changes. simple as that. 🫶

As an example of a system root partition, the recommended size is 30 GiB, but 50 GiB is selected by the installer if the snapshots are turned on.

For a non-system partition, it's recommended to watch the remaining free space. Although getting an accurate value on btrfs is tricky — due to shared extents and snapshots — the output of df gives a rough idea. Low space, like under a few gigabytes, is more likely to lead to no-space conditions, so it's a good time to delete old snapshots or review the snapper settings. 👀

🌸 Typical use cases 🌸

A rolling distro

• frequency of updates: high, multiple times per week
• amount of data changed between updates: high

Suggested values:

TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="5"
TIMELINE_LIMIT_WEEKLY="2"
TIMELINE_LIMIT_MONTHLY="1"
TIMELINE_LIMIT_YEARLY="0"

The size of root partition should be at least 30GiB, but more is better. 💖

Regular/enterprise distro

• frequency of updates: low, a few times per month
• amount of data changed between updates: low to moderate

Most data changes probably come from the package updates, in the range of hundreds of megabytes per update.

Suggested values:

TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="4"
TIMELINE_LIMIT_MONTHLY="6"
TIMELINE_LIMIT_YEARLY="1"

Big file storage

• frequency of updates: moderate to high
• amount of data changed between updates: no changes in files, new files added, old deleted

Suggested values:

TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="4"
TIMELINE_LIMIT_MONTHLY="6"
TIMELINE_LIMIT_YEARLY="0"

Note, that deleting a big file that has been snapshotted will not free the space until all relevant snapshots are deleted. 😭 the space is being held hostage fr.

Mixed

• frequency of updates: unpredictable
• amount of data changed between updates: unpredictable

Examples:

• home directory with small files (in range of kilobytes to megabytes), large files (hundreds of megabytes to gigabytes).
• git trees, bare and checked out repositories

Not possible to suggest config numbers, as it really depends on user expectations. Keeping a few hourly snapshots should not consume too much space and provides a copy of files, e.g. to restore after accidental deletion. 🙈

Starting point:

TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="1"
TIMELINE_LIMIT_MONTHLY="0"
TIMELINE_LIMIT_YEARLY="0"

⭐ Summary ⭐

here's the whole vibe in one place, bestie:

┌───────────┬────────┬───────┬────────┬─────────┬────────┐
│ Type      │ Hourly │ Daily │ Weekly │ Monthly │ Yearly │
├───────────┼────────┼───────┼────────┼─────────┼────────┤
│ Rolling   │ 12     │ 5     │ 2      │ 1       │ 0      │
├───────────┼────────┼───────┼────────┼─────────┼────────┤
│ Regular   │ 12     │ 7     │ 4      │ 6       │ 1      │
├───────────┼────────┼───────┼────────┼─────────┼────────┤
│ Big files │ 12     │ 7     │ 4      │ 6       │ 0      │
├───────────┼────────┼───────┼────────┼─────────┼────────┤
│ Mixed     │ 12     │ 7     │ 1      │ 0       │ 0      │
└───────────┴────────┴───────┴────────┴─────────┴────────┘

---

💖 About 💖

The goal of this project is to help with administering btrfs filesystems. It is not supposed to be distribution specific. Common scripts/configs are preferred, but per-distro exceptions will be added when necessary. 🌈

License: GPL 2 (https://www.gnu.org/licenses/gpl-2.0.html) 👑

Contributing guide: CONTRIBUTING.md. 🫶

---

okay that's the whole page bestie, you're officially a btrfs snapshot tuning icon now 💅✨ this was v0.5.2 dropped on 2026-01-14, and yes it lives at BTRFSMAINTENANCE(8) — go forth and slay 🎀🦋🌸