From 14a6992a4ebe826266a1ea4320c34c0ac91932ee Mon Sep 17 00:00:00 2001
From: sommerfeld <sommerfeld@sommerfeld.dev>
Date: Wed, 13 May 2026 13:43:35 +0100
Subject: feat(systemd): monthly btrfs balance template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Template service+timer that runs `btrfs balance start -dusage=50
-musage=50 %f` once a month on the instance's mount path. Mirrors the
shape of the stock btrfs-scrub@.{service,timer} so the operational
model is identical: enable btrfs-balance@-.timer for /, btrfs-balance@\
x2dhome.timer for /home, etc.

Why a partial balance and not a full one: full `btrfs balance start`
rewrites every block group, which on a multi-TB volume takes hours and
can chew through enormous amounts of CSUM/free-space-tree work.
`-dusage=50 -musage=50` only consolidates block groups that are less
than half full, which is exactly the operation that reclaims space
'lost' to fragmentation after lots of small writes — the only practical
reason a healthy single-disk btrfs needs balancing at all.

`Nice=19 IOSchedulingClass=idle` keeps it out of the way of foreground
work; `KillSignal=SIGINT` (same as btrfs-scrub) lets a graceful Ctrl-C
checkpoint the operation cleanly. Persistent=true catches the run on
next boot if the machine was off when the timer fired.

Enabled in systemd-units/system.txt as btrfs-balance@-.timer (root
volume only — /home isn't a separate subvolume on this machine).
---
 etc/systemd/system/btrfs-balance@.service | 13 +++++++++++++
 etc/systemd/system/btrfs-balance@.timer   | 12 ++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 etc/systemd/system/btrfs-balance@.service
 create mode 100644 etc/systemd/system/btrfs-balance@.timer

(limited to 'etc/systemd')

diff --git a/etc/systemd/system/btrfs-balance@.service b/etc/systemd/system/btrfs-balance@.service
new file mode 100644
index 0000000..a81c58d
--- /dev/null
+++ b/etc/systemd/system/btrfs-balance@.service
@@ -0,0 +1,13 @@
+[Unit]
+Description=Balance btrfs filesystem on %f (data/metadata <50%% block-group fill)
+Documentation=man:btrfs-balance(8)
+RequiresMountsFor=%f
+ConditionPathIsMountPoint=%f
+ConditionPathExists=/usr/bin/btrfs
+
+[Service]
+Type=oneshot
+Nice=19
+IOSchedulingClass=idle
+KillSignal=SIGINT
+ExecStart=/usr/bin/btrfs balance start -dusage=50 -musage=50 %f
diff --git a/etc/systemd/system/btrfs-balance@.timer b/etc/systemd/system/btrfs-balance@.timer
new file mode 100644
index 0000000..91a009c
--- /dev/null
+++ b/etc/systemd/system/btrfs-balance@.timer
@@ -0,0 +1,12 @@
+[Unit]
+Description=Monthly btrfs balance on %f
+Documentation=man:btrfs-balance(8)
+
+[Timer]
+OnCalendar=monthly
+AccuracySec=1d
+Persistent=true
+RandomizedDelaySec=1h
+
+[Install]
+WantedBy=timers.target
-- 
cgit v1.3.1