btrfs-backup-ng-estimate - Man Page

estimate backup transfer sizes and check destination space

Synopsis

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

Calculate and display estimated transfer sizes for backup operations before actually running them. Optionally verify that the destination has sufficient space, including awareness of btrfs quotas (qgroups). This helps with:

Planning bandwidth usage and backup windows
Verifying expected transfer sizes before proceeding
Checking destination space availability before transfers fail
Scripting and automation decisions

The estimate command analyzes which snapshots need to be transferred and calculates their sizes using multiple methods for accuracy.

Arguments

SOURCE: Source snapshot location (local path or ssh://user@host:/path).
DESTINATION: Backup destination (local path or ssh://user@host:/path).

Options

Config-Driven Options

-c, --config FILE: Path to configuration file.
--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).

Filtering Options

--prefix PREFIX: Filter snapshots by prefix.

SSH Options

--ssh-sudo: Use sudo for btrfs commands on the remote host.
--ssh-key FILE: Path to SSH private key file.

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.
--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.

Filesystem Check Options

--fs-checks MODE

Filesystem verification mode. Valid values:

auto: (Default) Warn about issues but continue operation.
strict: Error out on filesystem check failures.
skip: Bypass all filesystem verification checks.

--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.

Estimation Methods

The estimate command uses multiple methods to determine snapshot sizes, in order of preference:

btrfs subvolume show - Uses exclusive data size (most accurate, requires quotas enabled)
btrfs filesystem du - Handles reflinks and deduplication correctly
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.

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.

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

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

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

Notes

Estimates are approximate and actual transfer sizes may vary slightly due to btrfs stream overhead and compression.
Incremental estimates require the parent snapshot to exist.
The estimation process is read-only and does not modify any data.
For large backup sets, estimation may take several minutes.
Space checking queries quota information using btrfs qgroup show. If quotas are not enabled, only filesystem space is checked.

Copyright

License: MIT License

Referenced By

btrfs-backup-ng(1).

January 2026 btrfs-backup-ng