BTRFS-BACKUP-NG-ESTIMATE(1)

📦
version 0.9.20 · 2 versions
, in fedora 43, fedora 44

💖 BTRFS-BACKUP-NG-ESTIMATE(1) 💖

okay bestie, welcome to Section 1: User Commands of the manual — this is btrfs-backup-ng-estimate, and she is literally the ✨vibe-checker✨ of your backup game. Before you yeet a terabyte across the network, you ask her "hey, how big is this gonna be, and will it even fit?" 🦋

✨ NAME ✨

btrfs-backup-ng-estimate — estimate backup transfer sizes and check destination space. no cap, that's the whole job 🎀

🌸 SYNOPSIS 🌸

btrfs-backup-ng estimate [OPTIONS] SOURCE DESTINATION
btrfs-backup-ng estimate --volume PATH [--target INDEX] [--check-space]

two modes, pick your fighter 💅

🫶 DESCRIPTION 🫶

So the whole thing here is: she calculates and displays estimated transfer sizes for backup operations before you actually run them. Optionally she'll also verify that your destination has enough space, and yeah she's aware of btrfs quotas (qgroups) because she's thorough like that 💅

This is lowkey a lifesaver for:

  • Planning bandwidth usage and backup windows 📶
  • Verifying expected transfer sizes before proceeding
  • Checking destination space availability before transfers fail (iconic, honestly)
  • Scripting and automation decisions 🤖

The estimate command analyzes which snapshots need to be transferred and calculates their sizes using multiple methods for accuracy. multiple. methods. for. accuracy. she's an overachiever and we love her for it 🏆

🎀 ARGUMENTS 🎀

  • SOURCE — Source snapshot location (local path or ssh://user@host:/path). where the tea is coming from ☕
  • DESTINATION — Backup destination (local path or ssh://user@host:/path). where it's going 🚚

💅 OPTIONS 💅

🌈 Config-Driven Options

  • -c, --config FILE — Path to configuration file. your lil settings bestie 📄
  • --volume PATH — Estimate for volume defined in config (e.g., /home). Uses the backup target(s) configured for that volume.
  • --target INDEX — Target index to estimate for (0-based). Default: first target (0).
  • --skip-remote-lock — Proceed even if a lock cannot be recorded on the remote target. Only safe when nothing else can prune this target during the run.
⚠️ bestie. read that again. only safe when nothing else can prune this target during the run. don't be reckless, she's warning you fr fr 😭
  • --timestamp-format FMT — strftime format for parsing snapshot timestamps in direct mode (defaults to the config's [global] timestamp_format, else the built-in).

🌸 Filtering Options

  • --prefix PREFIX — Filter snapshots by prefix. narrowing it down, cute 🎯

🦋 SSH Options

  • --ssh-sudo — Use sudo for btrfs commands on the remote host.
  • --ssh-key FILE — Path to SSH private key file. 🔑
  • --ssh-auth-sock PATH — Explicit ssh-agent socket (overrides auto-discovery; useful under sudo).
  • --ssh-host-key-policy POLICY — Host-key verification for this run: accept-new (default) or strict.

⭐ Space Checking Options

  • --check-space — Check if the destination has sufficient space for the estimated transfer. When enabled, queries both filesystem free space and btrfs quota limits (if quotas are enabled), using the more restrictive value. she takes the stricter one because she's looking out for you 🫶
  • --safety-margin PERCENT — Safety margin percentage to add to required space calculation. Default is 10%. A minimum of 100 MiB is always applied regardless of the percentage. (yes, even if you set it to like 1%. the 100 MiB floor is non-negotiable, periodt.)

🧚 Filesystem Check Options

  • --fs-checks MODE — Filesystem verification mode. Valid values:
    • auto — (Default) Warn about issues but continue operation. chill but observant
    • strict — Error out on filesystem check failures. no mercy, slay 💀
    • skip — Bypass all filesystem verification checks. living dangerously 🙈
  • --no-fs-checks — Skip btrfs subvolume verification. Alias for --fs-checks=skip.

👑 Output Options

  • --json — Output results in JSON format for scripting. When --check-space is enabled, includes a space_check object with detailed space information including quota data. for the automation girlies 🤖✨

🍓 ESTIMATION METHODS 🍓

She uses multiple methods to determine snapshot sizes, in order of preference:

  1. btrfs subvolume show — Uses exclusive data size (most accurate, requires quotas enabled)
  2. btrfs filesystem du — Handles reflinks and deduplication correctly
  3. du — Fallback when btrfs commands aren't available

For incremental transfers, the command uses btrfs send --no-data to estimate the delta size without actually transferring data. she's just peeking, not touching, it's giving respectful 👀

✨ OUTPUT FORMAT ✨

The default output shows a table with:

  • Snapshot name
  • Size (incremental or full)
  • Transfer type (incremental or full)
  • Parent snapshot (for incremental)

Followed by totals for data to transfer and estimation time. receipts, basically 🧾

💜 JSON OUTPUT 💜

With --json, the output includes:

  • source, destination paths
  • snapshot_count, new_snapshot_count, skipped_count
  • total_transfer_bytes, total_transfer_human
  • total_full_bytes, total_full_human
  • estimation_time_seconds
  • snapshots array with details for each snapshot

perfect for piping into your lil scripts, iykyk 🐍

🎀 EXAMPLES 🎀

Estimate transfer for direct paths:

btrfs-backup-ng estimate /mnt/snapshots /mnt/backup

Estimate for remote backup:

btrfs-backup-ng estimate /home/.snapshots ssh://backup@server:/backups/home

Estimate using configuration file:

btrfs-backup-ng estimate --volume /home

Estimate for specific target:

btrfs-backup-ng estimate --volume /home --target 1

Estimate with destination space check:

btrfs-backup-ng estimate --volume /home --check-space

Space check with custom safety margin (20%):

btrfs-backup-ng estimate /mnt/snapshots /mnt/backup --check-space --safety-margin 20

JSON output with space check for scripting:

btrfs-backup-ng estimate --volume /home --check-space --json

Check if backup will fit (bash example using built-in space check):

if ! btrfs-backup-ng estimate --volume /home --check-space --json | \
     jq -e '.space_check.sufficient' > /dev/null; then
    echo "Warning: Not enough space for backup"
    exit 1
fi

like?? she's a whole devops girlie 💅

🔥 SPACE CHECK OUTPUT 🔥

When --check-space is enabled, the output includes a destination space check section showing:

  • Filesystem space: Available and total space on the destination filesystem
  • Quota limit: If btrfs quotas are enabled, shows the quota limit, current usage, and remaining space
  • Effective limit: The more restrictive of filesystem space or quota remaining
  • Required: Estimated transfer size plus safety margin
  • Status: OK or INSUFFICIENT with details

Example output with quotas:

Destination Space Check
------------------------------------------------------------
Filesystem space:  850.00 GiB available of 1.00 TiB
Quota limit:       100.00 GiB (45.50 GiB used, 54.50 GiB remaining)
Effective limit:   54.50 GiB (quota is more restrictive)
Required:          2.49 GiB (+ 10% safety margin = 2.74 GiB)
Status:            OK - Sufficient space available

look at her, doing the math for you 😭💖

🌸 NOTES 🌸

  • Estimates are approximate and actual transfer sizes may vary slightly due to btrfs stream overhead and compression. she said approximate, don't come for her 💀
  • Incremental estimates require the parent snapshot to exist.
  • The estimation process is read-only and does not modify any data. 🫶 safe, respectful, consensual
  • For large backup sets, estimation may take several minutes. grab a snack 🍓
  • Space checking queries quota information using btrfs qgroup show. If quotas are not enabled, only filesystem space is checked.

🦋 SEE ALSO 🦋

btrfs-backup-ng(1), btrfs-backup-ng-run(1), btrfs-backup-ng-transfer(1) — the rest of the friend group, go say hi 💕

Copyright 2024-present Michael Berry.

License: MIT License

okay that's the whole page, bestie 💅 and for the sign-off: this was the btrfs-backup-ng manual page, dated January 2026 — go forth and estimate responsibly, mwah 😘💖✨

📦 where this page comes from