Btrfs (B-Tree File System) is an advanced, copy-on-write filesystem increasingly popular in the Linux ecosystem, known for its powerful snapshotting, checksumming, and subvolume capabilities. However, these advanced features come with a maintenance overhead. In Ubuntu Server (and other Debian-based distributions that support Btrfs), a background daemon called btrfs-cleaner runs periodically to reclaim unused blocks, delete dropped subvolumes, and run defragmentation routines. While crucial for long-term filesystem health, btrfs-cleaner is notoriously resource-intensive. When it triggers on a production server, it can cause massive, unexpected spikes in disk I/O, leading to severe latency for hosted databases, web servers, or virtual machines.
This guide explains how to identify and completely disable the background btrfs-cleaner threads in Ubuntu Server, allowing you to schedule maintenance manually during off-peak hours.
Identify and Disable the Btrfs Maintenance Timers
Unlike traditional daemons managed by a single systemd service file, Btrfs maintenance in modern Ubuntu releases is often handled by a set of systemd timers that trigger specific scripts (like balance, scrub, and trim). To stop the cleaner from running automatically, you must disable these timers.
- Log into your Ubuntu Server via SSH or local console with
sudoprivileges. - First, list all active Btrfs-related timers to see what is currently scheduled:
systemctl list-timers | grep btrfs - You will typically see timers for
btrfs-scrub.timer,btrfs-balance.timer, andbtrfs-trim.timer. To completely disable automatic maintenance, you must stop and disable all of them. - Disable the Scrub timer (which verifies checksums):
sudo systemctl disable --now btrfs-scrub.timer - Disable the Balance timer (which reallocates chunks across disks):
sudo systemctl disable --now btrfs-balance.timer - Disable the Trim timer (which issues DISCARD commands to SSDs):
sudo systemctl disable --now btrfs-trim.timer
Managing the Kernel btrfs-cleaner Thread
Even with the user-space systemd timers disabled, the Linux kernel maintains a low-level thread named [btrfs-cleaner] that handles synchronous cleanup tasks (like deleting subvolumes after you run btrfs subvolume delete). You cannot entirely kill this kernel thread without unmounting the filesystem, but you can prevent it from causing massive I/O spikes by changing how you delete snapshots.
To prevent the btrfs-cleaner thread from locking up your disk, never delete massive snapshots synchronously. Instead, use the --commit-each flag or utilize a dedicated snapshot management tool like Snapper, which paces the deletions. If you are experiencing an ongoing I/O lockup caused by the cleaner, you can temporarily mitigate it by remounting the filesystem with the enospc_debug option, though the safest approach is simply to wait for the kernel thread to finish its current block reclamation queue.