Dear Maintainer,

as distributed, /etc/default/btrfsmaintenance has the following information:
## Path:           System/File systems/btrfs
## Type:           string(none,daily,weekly,monthly)
## Default:        "weekly"
## ServiceRestart: btrfsmaintenance-refresh
#
# Frequency of periodic balance.
#
# The frequency may be specified using one of the listed values or
# in the format documented in the "Calendar Events" section of systemd.time(7),
# if available.
BTRFS_BALANCE_PERIOD="weekly"

however /lib/systemd/system/btrfs-balance.timer has:
[Timer]
OnCalendar=monthly

it would seem that either the value/note in /etc/default/btrfsmaintenance
or the OnCalendar value in btrfs-balance.timer should be updated to match
the other.

thanks in advance.

	andy

Hi Andrew,

andrew bezella <andrew@diatribes.org> writes:

Oh yeah!  I had forgotten about this minor issue.  The reason I hadn't
harmonised the files, doing this implicitly says that I (and Debian)
might recommend weekly balanced, or recommend monthly balances.

From what I've been able to gather, metadata balances have been
considered to be actively harmful for some time; This is mostly at the
level of tribal knowledge on the linux-btrfs mailing list.  It's also
the case that empty block groups are now automatically reclaimed by the
kernel, so a periodic balance only seems to be useful in
space-constrained situations where a lot of [meta]data churn occurs.

Thus, if I do anything, I'm inclined to set the period for balance to
"none" everywhere.

Also, what do you think about enabling the systemd patch watcher, so
that the timers are updated automatically when
/etc/default/btrfsmaintenance is modified?

Best,
Nicholas

Hi Andrew,

andrew bezella <andrew@diatribes.org> writes:

Oh yeah!  I had forgotten about this minor issue.  The reason I hadn't
harmonised the files, doing this implicitly says that I (and Debian)
might recommend weekly balanced, or recommend monthly balances.

From what I've been able to gather, metadata balances have been
considered to be actively harmful for some time; This is mostly at the
level of tribal knowledge on the linux-btrfs mailing list.  It's also
the case that empty block groups are now automatically reclaimed by the
kernel, so a periodic balance only seems to be useful in
space-constrained situations where a lot of [meta]data churn occurs.

Thus, if I do anything, I'm inclined to set the period for balance to
"none" everywhere.

Also, what do you think about enabling the systemd patch watcher, so
that the timers are updated automatically when
/etc/default/btrfsmaintenance is modified?

Best,
Nicholas

hello -

thanks for the feedback...  some comments inline.  i must stress that
while i am a multi-year user of btrfs i do not read the linux-btrfs
mailing list and my opinions should be given appropriate weight.
[...]

regarding balance recommendations, my initial thought would be to make
the language in the README.Debian stronger.  i had read that "Some
advocate not running it at all" but to me that implies "may be
unnecessary" rather than "may be actively harmful."  on the basis of
the latter i am certainly considering setting the balance.timer back to
disabled.  alternatively/additionally are there default options that
might make it safe(r)?  e.g., Marc MERLIN's `btrfs-scrub`[1] (which i
used previously) suggested that "a null [metadata] rebalance should
help corner cases."

from my pov i'd still like to see the values harmonized.  i originally
noticed the inconsistency because what i believed was the default
setting was creating a seemingly unnecessary systemd override file.
this became a nagging question to resolve :)  if the (informed) user
has chosen to enable the btrfs-balance.timer then i would say harmonize
the value at "monthly" (1/4 the opportunity for issues).

given that one already needs to manually enable the service via
`systemctl enable btrfs-balance.timer` i don't think it's necessary to
set the default value to "none."  this would result in the (imho)
counter-intuitive behavior of enabling something only to have it do
nothing.  although an add'l comment re: the potential for harm in
`/etc/default/btrfs` that one would hopefully see when changing the
value from "none" to e.g., "monthly" may be the best way to ensure that
they are an informed user.  so i could go either way on that.

as a sysadmin the steps of modifying a file and then running a command
for it to take effect is a normal part of my workflow.  so i'm fine
leaving it disabled by default.  other users might feel differently.

thank you...

	andy

1. https://marc.merlins.org/linux/scripts/btrfs-scrub

Hi Andy!

Sorry for the delay, reply follows inline.

andy <andrew@diatribes.org> writes:

Thank you for your willingness to share your experience along with what
you'd like to see.  After all, what's the point if real-world users
aren't accommodated? :)
[snip]

Would this be enough to guard naive users from potential data loss?  You
know, the people who read docs as an afterthought, or the "it will be
fine; it won't happen to me" crowd...  At the same time, I worry that
there might be a social cost to using stronger language (it could
demotivate developers or scare people off of trying btrfs).  What do you
think?

I agree, the docs should be updated; however, I'll also need to be
prepared to provide citations and reasoning.  To be honest, I'm trusting
a recurring upstream statements on the question of metadata rebalancing.

Btw, I'm curious to learn why you've enabled balancing!

The "may be actively harmful" bit is tricky, because Btrfs gets way too
complicated way too fast...  My hope to put in place safe defaults that
work for most people, that don't bait users/sysadmins into taking on
risk, and that are good enough for the general case.  Of course you know
that a solid enough replication and backup strategy makes it ok to take
risks for optimisation, but that's the "educated/experienced sysadmin"
class of cases ;)  If rebalancing does something like keeping database
performance from degrading, then it would be worth documenting this
somewhere, along with the fact that several core devs upstream have
written statements to the effect of this: never balance metadata, unless
necessary.  Rebalancing to a new profile counts as "necessary",
obviously, and the only other corner case I'm aware is noted two
paragraphs below.

I believe that [metadata] balancing should probably be disabled in
upstream btrfsmaintenance.  If I remember correctly, it's enabled by
default because upstream targets 10year LTS releases such as SUSE's 11
series, which uses linux 3.0.76, where the harm reduction of metadata
balancing is significant enough to make the risk worthwhile on
server-grade hardware.

Has that corner case existed since linux-3.18?

https://btrfs.wiki.kernel.org/index.php/Balance_Filters

Or are you referring to cleaning up inefficient use of metadata after
a batch deletion of thousands of snapshots or subvolumes (all at once)?

Sorry, what is this "unnecessary systemd override file"?

People are funny, because when you write or say "This is bad, you must
never do this, but if you do this, here is how to do it" the message
that is understood is "here is how to do it" ;)

Good point, and yes, I agree that two knobs seems silly; however, there
is already precedent for this with '"BTRFS_TRIM_PERIOD="none"'.  As
there doesn't seem to be any interest in #887461, I'm wondering if might
be time to follow the consensus of the General Resolution in favour of
systemd, and soon start shipping systemd timers in an enabled state, and
disable everything in the config file, but provide suggested values...

I guess keeping it the way it is right now can act as a kind of safety
gate, so if I install the timers in an enabled state, but disabled, then
only users who read the docs will be able to update those times.  Maybe
that, plus some "NOT RECOMMENDED" comments in the config file would be a
nice compromise?

Regards,
Nicholas

hi - thank you for closing Bug#1027846, my turn to apologize for the
delay.  february was busy...
[...]

one question would be: should the btrfsmaintenance package provide a
convenient way to use an (unnecessary?) feature that might cause data
loss?  are there cases in which it is recommended for the average (or
even somewhat adventurous) user to regularly schedule a btrfs balance?
if so, maybe spell out those cases explicitly in the README?  from this
conversation it does not sound like something that i would regard as
"maintenance" in the vein of max-mount-counts/interval-between-checks
driven fsck's in the ext{2,3,4} world or periodic btrfs scrubs.  otoh,
see below...

from a user's perspective it's really hard to judge.  for instance,
https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Balancing states:
"It is _quite_ [their emphasis] useful to balance periodically any
Btrfs volume subject to updates."

been a long time, but i _think_ that at one point (related to a disk
failure/replacement in raid1 that may not have gone 100% smoothly?) i
ended up in an unbalanced situation where i couldn't write even though
there was apparently space available.  iirc `balance` was needed to get
me out of that corner.  and then i found Marc MERLIN's `btrfs-scrub`
script which included `btrfs balance` commands and he seemed like a
knowledgeable source.  that in combination w/the btrfs wiki led me to
believe it was a safe operation.  e.g., in addition to the above,
https://btrfs.wiki.kernel.org/index.php/Status lists it as "stable"
with only a note about performance.

yes, it sounds like one viable approach may be to explicitly document
cases where balance is recommended.

based on what has come up in this thread, my feedback would be that the
debian pkg should diverge from upstream wrt balancing.

sorry, i don't know any details beyond the comments in the script.

when i enabled the balance component i initially left
`BTRFS_BALANCE_PERIOD="weekly"` which is noted as the default in
`/etc/default/btrfsmaintenance`.  but then it created a systemd
override file with `OnCalendar=weekly` in `/etc/systemd/system/btrfs-
balance.timer.d/schedule.conf`.  this surprised me because i wouldn't
expect this to be necessary when using the default.  then i checked
`/lib/systemd/system/btrfs-balance.timer` and found that the _actual_
default is `OnCalendar=monthly` and, well, here we are :)

[...]

sure, that would eliminate the "two knobs" and makes sense from my pov.

also makes sense to me, with a pointer to the README for add'l
information.

best,

	andy

Hello Andy,

Thank you again for the discussion at this bug, and ouf, sorry I didn't
follow-up with your latest reply after partially addressing it in 0.5-4.
In that release I started patching the config to disable balance as well as
installing the timer in a disabled state, so this bug might have been
solved by then.  Please see reply inline:

andy <andrew@diatribes.org> writes:

I'm inclined to say yes, because Debian provides all sorts of mechanisms
to potentially accidentally erase and/or corrupt one's data.  Users are
responsible for not blindly following non-Debian documentation and
screwing up their system.  Would you agree that it's a good thing to
provide maximum liberty within a clearly-defined responsibility
boundary?

I've updated the README.Debian text to show this:

      systemctl enable btrfs-balance.timer  —  Not recommended    [1]
      systemctl enable btrfs-defrag.timer   —  Avoid if possible  [2]
      systemctl enable btrfs-scrub.timer    —  Highly recommended [3]

  [1] This rewrites all data that is not excluded by a filter.  Periodic
      balancing is not useful, nor recommended, for the vast majority of
      workloads.  If a corner case is found where balancing is useful,
      this case (with steps to reproduce) should be reported upstream.

I agree 100%, and that's why I started maintaining our Debian btrfs wiki
page and this package...  Upstream docs have historically been somewhere
between aspirational and obsolete (both cases may be harmful).
Thankfully the page you linked to is finally marked "OBSOLETE CONTENT".

Yes, balance is basically the sledgehammer that beats ancient corner
case bugs into uniformity.  I forget when it was (linux-4.4, I think),
but I had to do a full balance (data and metadata) when converting from
single profile data (DUP profile metadata) to raid1 profile (both data
and metadata) twice, with a reboot in between...and things were worse
when Marc MERLIN's guide was published.  For anyone reading this in
2025 (or later), it's almost certainly no longer relevant.
[snip]

I still haven't found any.  Have you?

I agree, and I've forwarded this bug upstream.  I'm leaning towards
removing Debian's btrfsmaintenance support for balancing well before
forky's release.

Yuck, I don't like that behaviour either.  The current (in git, soon to
be uploaded) default is a soft-disabled "OnCalendar=monthly", with
BTRFS_BALANCE_PERIOD="none".

Aha, this is why I took so long to reply.  So, to start off with, the
balance timer should always be installed in a disabled state, because
timers with an enabled state allegedly run on boot!  Beyond that, I'm
honestly not sure how to achieve this with systemd.  Do you have a
solution in mind?  I've now removed the redundant TRIM support from
Btrfsmaintenance for Debian.

git clone https://salsa.debian.org/sten/btrfsmaintenance.git

or you can try this prebuilt prerelease:

https://people.debian.org/~sten/test-builds/btrfsmaintenance_0.5.2-2_all.deb
  (you can use the changes file signature and checksums to verify)
https://people.debian.org/~sten/test-builds/

Cheers,
Nicholas