### Snapper snapshot retention configuration examples

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Provides example configurations for snapper timeline limits based on different distribution types and update frequencies. Adjust these values to manage snapshot storage.

```bash
# Rolling distribution (frequent, large updates)
# /etc/snapper/configs/root
TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="5"
TIMELINE_LIMIT_WEEKLY="2"
TIMELINE_LIMIT_MONTHLY="1"
TIMELINE_LIMIT_YEARLY="0"
```

```bash
# Regular / enterprise distribution (infrequent updates)
TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="4"
TIMELINE_LIMIT_MONTHLY="6"
TIMELINE_LIMIT_YEARLY="1"
```

```bash
# Big file storage (many large files added/deleted)
TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="4"
TIMELINE_LIMIT_MONTHLY="6"
TIMELINE_LIMIT_YEARLY="0"
```

```bash
# Mixed / home directory with unpredictable change patterns
TIMELINE_LIMIT_HOURLY="12"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="1"
TIMELINE_LIMIT_MONTHLY="0"
TIMELINE_LIMIT_YEARLY="0"
```

--------------------------------

### Install btrfs-defrag-plugin.py

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Installs the btrfs-defrag-plugin.py script to the zypper commit plugins directory on SUSE/openSUSE systems.

```bash
install -m 755 btrfs-defrag-plugin.py /usr/lib/zypp/plugins/commit/
```

--------------------------------

### Install btrfs-defrag-plugin.sh

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Installs the btrfs defrag plugin script to the zypper commit plugins directory. This script is automatically executed after package installations or updates.

```bash
install -m 755 btrfs-defrag-plugin.sh /usr/lib/zypp/plugins/commit/
```

--------------------------------

### Configure weekly balance timer

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Example of a systemd drop-in configuration file to schedule a weekly btrfs balance timer.

```ini
[Timer]
OnCalendar=
OnCalendar=weekly
```

--------------------------------

### Scrub RAID 5/6 devices sequentially

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Internal logic for scrubbing RAID 5/6 devices sequentially, waiting for each scrub to complete before starting the next.

```bash
for DEV in $(btrfs filesystem show / | awk '/ path /{print $NF}'); do
    btrfs scrub start -Bd "$DEV"
    until btrfs scrub status "$DEV" | grep finished; do sleep 5; done
done
```

--------------------------------

### Install Btrfs Maintenance Toolbox Scripts

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

This script installs the Btrfs Maintenance Toolbox scripts, functions library, and configuration template to standard system locations. It can auto-detect the sysconfig directory or accept an explicit override.

```bash
# Auto-detect sysconfdir (/etc/sysconfig or /etc/default) and install
sudo bash dist-install.sh

# Override sysconfdir explicitly
sudo bash dist-install.sh /etc/default

# Expected output:
# Installation path: /etc/default
# For cron-based setups:
# - edit cron periods and mount points in /etc/default/btrfsmaintenance
# - run ./btrfsmaintenance-refresh-cron.sh to update cron symlinks
#
# For systemd.timer-based setups:
# - copy *.timer files to the systemd.unit path ...
# - copy *.service files to the systemd.unit path ...
# - edit cron periods and mount points in /etc/default/btrfsmaintenance
# - run './btrfsmaintenance-refresh-cron.sh timer' to enable and schedule the timers

```

--------------------------------

### Expected fstrim output

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Example output from the fstrim command when run on a btrfs mount point, indicating the amount of space trimmed.

```bash
# Running fstrim on /
# /: 4.5 GiB (4831838208 bytes) trimmed
```

--------------------------------

### Balance non-mixed filesystem metadata

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Internal commands for balancing metadata in non-mixed btrfs filesystems, starting with fully empty block groups and progressing to reclaiming space from underused ones.

```bash
btrfs balance start -musage=0 /
# reclaim ≤5% used metadata BGs
btrfs balance start -v -musage=5 /
```

--------------------------------

### Balance non-mixed filesystem data

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Internal commands for balancing data in non-mixed btrfs filesystems, starting with fully empty block groups and progressing to reclaiming space from underused ones.

```bash
btrfs balance start -dusage=0 /
# reclaim ≤5% used data BGs
btrfs balance start -v -dusage=5 /
# reclaim ≤10% used data BGs
btrfs balance start -v -dusage=10 /
```

--------------------------------

### Balance mixed block groups

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Internal commands for balancing both data and metadata in mixed btrfs block groups, starting with fully empty groups and then reclaiming space from underused ones.

```bash
btrfs balance start -musage=0 -dusage=0 /
btrfs balance start -v -musage=5 -dusage=5 /
```

--------------------------------

### Enable weekly trim for SSD

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Configuration steps to enable weekly TRIM for an SSD, involving editing sysconfig and refreshing the cron timer.

```bash
# Enable weekly trim for an SSD (edit sysconfig, then refresh):
# BTRFS_TRIM_PERIOD="weekly"
# BTRFS_TRIM_MOUNTPOINTS="auto"
sudo btrfsmaintenance-refresh-cron.sh timer
```

--------------------------------

### Source btrfsmaintenance-functions library

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Sources the shared btrfsmaintenance-functions library into a custom script. This makes all helper functions available for use.

```bash
. /usr/share/btrfsmaintenance/btrfsmaintenance-functions
```

--------------------------------

### Monitor free space and delete old snapper snapshots

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Monitors free disk space and provides commands to delete old snapper snapshots when space becomes low. This is crucial for preventing disk full errors.

```bash
# Monitor remaining free space (low space → delete old snapshots)
df -H /
# If free space drops below a few GiB, prune old snapshots:
snapper -c root list
snapper -c root delete 10-50
```

--------------------------------

### Run btrfs balance manually

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Executes the btrfs-balance.sh script to manually initiate a filesystem balance operation.

```bash
sudo /usr/share/btrfsmaintenance/btrfs-balance.sh
```

--------------------------------

### Configure Monthly Snapshot Retention for Enterprise Distro

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of monthly snapshots to retain for a regular/enterprise distribution, allowing for more historical data.

```shell
TIMELINE_LIMIT_MONTHLY="6"
```

--------------------------------

### View btrfs-scrub journal logs

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Retrieves log entries for the btrfs-scrub process from the system journal.

```bash
journalctl -t btrfs-scrub
```

--------------------------------

### Configure Weekly Snapshot Retention for Enterprise Distro

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of weekly snapshots to retain for a regular/enterprise distribution.

```shell
TIMELINE_LIMIT_WEEKLY="4"
```

--------------------------------

### Run btrfs scrub manually

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Executes the btrfs-scrub.sh script to manually initiate a filesystem scrub. This script respects settings in /etc/sysconfig/btrfsmaintenance.

```bash
sudo /usr/share/btrfsmaintenance/btrfs-scrub.sh
```

--------------------------------

### Configure Monthly Snapshot Retention

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of monthly snapshots to retain. Ensure these align with recovery needs and available space.

```shell
TIMELINE_LIMIT_MONTHLY="1"
```

--------------------------------

### Check btrfs filesystem space usage

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Displays filesystem space usage details for data and metadata, useful for observing changes before and after a balance operation.

```bash
btrfs filesystem df /
```

--------------------------------

### Find files for defragmentation

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Uses the `find` command to locate regular files larger than 1MB within the /home directory, which would be targeted by the defragmentation script.

```bash
find /home -xdev -size +1M -type f
```

--------------------------------

### Configure Daily Snapshot Retention for Enterprise Distro

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of daily snapshots to retain for a regular/enterprise distribution, typically with lower update frequency.

```shell
TIMELINE_LIMIT_DAILY="7"
```

--------------------------------

### Configure Yearly Snapshot Retention for Enterprise Distro

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of yearly snapshots to retain for a regular/enterprise distribution. This provides a long-term recovery point.

```shell
TIMELINE_LIMIT_YEARLY="1"
```

--------------------------------

### Configure Daily Snapshot Retention

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of daily snapshots to retain. Consider the need for daily recovery points.

```shell
TIMELINE_LIMIT_DAILY="5"
```

--------------------------------

### Set Snapshot Retention Limits

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Configure the number of snapshots to retain for different time periods. Adjust these values based on your storage capacity and recovery needs.

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

--------------------------------

### Expand auto mountpoints with expand_auto_mountpoint

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Resolves the 'auto' keyword to all currently mounted btrfs filesystems. Useful for applying maintenance tasks to all relevant mountpoints.

```bash
MOUNTS=$(expand_auto_mountpoint "auto")
echo "$MOUNTS"
```

```bash
MOUNTS=$(expand_auto_mountpoint "/data:/backup")
echo "$MOUNTS"
```

--------------------------------

### Restart btrfsmaintenance-refresh service

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Restarts the btrfsmaintenance-refresh service, typically used with systemd path watchers or manual triggers.

```bash
sudo systemctl restart btrfsmaintenance-refresh
```

--------------------------------

### Configure Weekly Snapshot Retention

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of weekly snapshots to retain. Useful for longer-term recovery points.

```shell
TIMELINE_LIMIT_WEEKLY="2"
```

--------------------------------

### Run task with flock serialisation using run_task

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Executes a given command with flock-based serialisation to prevent concurrent runs, unless BTRFS_ALLOW_CONCURRENCY is set. It acquires a lock file based on the filesystem UUID.

```bash
run_task btrfs balance start -dusage=5 /
# Acquires /run/btrfs-maintenance-running.<UUID>, then runs the command
```

--------------------------------

### Configure Yearly Snapshot Retention

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of yearly snapshots to retain. Note that yearly snapshots should not replace backups.

```shell
TIMELINE_LIMIT_YEARLY="0"
```

--------------------------------

### Check if balance is running with check_balance_running

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Performs a non-blocking check to determine if a btrfs balance operation is currently in progress on the specified filesystem.

```bash
if check_balance_running /; then
    echo "Balance already running on /"
fi
```

--------------------------------

### Configure Btrfs Maintenance Settings

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

This is the central configuration file for the Btrfs Maintenance Toolbox. All settings are shell variable assignments and control logging, concurrency, and scheduling periods for scrub, balance, trim, and defragmentation tasks. Changes to scheduling periods require re-running the refresh script.

```bash
# /etc/sysconfig/btrfsmaintenance  (or /etc/default/btrfsmaintenance on Debian)

# ── Logging ──────────────────────────────────────────────────────────────────
# Options: stdout | journal | syslog | none
BTRFS_LOG_OUTPUT="journal"

# ── Concurrency ───────────────────────────────────────────────────────────────
# false = serialise all tasks with flock (recommended); true = allow parallel runs
BTRFS_ALLOW_CONCURRENCY="false"

# ── Scrub ─────────────────────────────────────────────────────────────────────
BTRFS_SCRUB_MOUNTPOINTS="/"          # colon-separated paths, or "auto"
BTRFS_SCRUB_PERIOD="monthly"         # none | daily | weekly | monthly | systemd.time(7)
BTRFS_SCRUB_PRIORITY="idle"          # idle | normal
BTRFS_SCRUB_READ_ONLY="false"        # true = verify only, no repair

# ── Balance ───────────────────────────────────────────────────────────────────
BTRFS_BALANCE_MOUNTPOINTS="/"        # colon-separated paths, or "auto"
BTRFS_BALANCE_PERIOD="weekly"        # none | daily | weekly | monthly | systemd.time(7)
BTRFS_BALANCE_DUSAGE="5 10"          # space-separated usage % thresholds for data BGs
BTRFS_BALANCE_MUSAGE="5"             # usage % threshold(s) for metadata BGs

# ── Trim ──────────────────────────────────────────────────────────────────────
BTRFS_TRIM_MOUNTPOINTS="/"           # colon-separated paths, or "auto"
BTRFS_TRIM_PERIOD="none"             # off by default; set "weekly" for SSDs

# ── Defrag ────────────────────────────────────────────────────────────────────
BTRFS_DEFRAG_PATHS=""                # colon-separated paths to defragment
BTRFS_DEFRAG_PERIOD="none"           # none | daily | weekly | monthly
BTRFS_DEFRAG_MIN_SIZE="+1M"          # find(1) -size argument; skip files smaller than this

```

--------------------------------

### Run btrfs trim manually

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Executes the btrfs-trim.sh script to manually initiate TRIM/discard operations on configured btrfs mount points.

```bash
sudo /usr/share/btrfsmaintenance/btrfs-trim.sh
```

--------------------------------

### Zypper defrag plugin action

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

The action performed by the btrfs-defrag-plugin.py when invoked by zypper after a commit, defragmenting the RPM database directory.

```bash
#   btrfs filesystem defragment -v -f -r -t 33554432 /var/lib/rpm
```

--------------------------------

### Configure Hourly Snapshot Retention

Source: https://github.com/kdave/btrfsmaintenance/blob/master/README.md

Sets the number of hourly snapshots to retain. Adjust based on update frequency and data change rate.

```shell
TIMELINE_LIMIT_HOURLY="12"
```

--------------------------------

### Refresh Cron Symlinks or Systemd Timers

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

This script synchronises cron symlinks or systemd timer drop-in files with the current configuration. It must be re-run whenever a `*_PERIOD` variable in the configuration file changes.

```bash
# Install / refresh cron symlinks (reads BTRFS_*_PERIOD from config)
sudo btrfsmaintenance-refresh-cron.sh cron

# Install / refresh systemd timers (creates drop-in schedule.conf files)
sudo btrfsmaintenance-refresh-cron.sh timer

# Remove all cron symlinks
sudo btrfsmaintenance-refresh-cron.sh cron uninstall

# Remove all systemd timer drop-ins and stop/disable the timers
sudo btrfsmaintenance-refresh-cron.sh timer uninstall

```

--------------------------------

### Run btrfs defrag manually

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Executes the btrfs-defrag.sh script to manually initiate defragmentation of files exceeding a specified size.

```bash
sudo /usr/share/btrfsmaintenance/btrfs-defrag.sh
```

--------------------------------

### Detect RAID 5/6 with is_raid56

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Detects if the specified mountpoint is part of a RAID 5 or RAID 6 configuration. This is relevant for choosing appropriate scrub strategies.

```bash
if is_raid56 /mnt/array; then
    echo "RAID 5/6 detected — scrub devices sequentially"
fi
```

--------------------------------

### Detect mixed block groups with detect_mixed_bg

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Detects if a filesystem uses mixed Data and Metadata block groups. This can inform decisions about balance filters.

```bash
if detect_mixed_bg /; then
    echo "Mixed block groups detected, adjusting balance filters"
fi
```

--------------------------------

### Retrieve filesystem UUID with btrfs_fsid

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Retrieves the unique filesystem identifier (UUID) for the specified mountpoint. This is often needed for configuration or logging.

```bash
UUID=$(btrfs_fsid /)
echo "$UUID"
```

--------------------------------

### Check if scrub is running with check_scrub_running

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Performs a non-blocking check to determine if a btrfs scrub operation is currently in progress on the specified filesystem.

```bash
if check_scrub_running /; then
    echo "Scrub already running on /"
fi
```

--------------------------------

### Check btrfs scrub status

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Checks the status of the most recent btrfs scrub operation on a specified mount point.

```bash
btrfs scrub status /
```

--------------------------------

### Check if a path is on a btrfs filesystem with is_btrfs

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Checks if the specified path resides on a btrfs filesystem. This is useful for conditional logic in scripts.

```bash
if is_btrfs /home; then
    echo "/home is btrfs"
fi
```

--------------------------------

### Cancel a running btrfs scrub

Source: https://context7.com/kdave/btrfsmaintenance/llms.txt

Cancels an ongoing btrfs scrub operation. Progress is saved every 5 seconds.

```bash
btrfs scrub cancel /
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.