BTRFS-BACKUP-NG-DOCTOR(1)

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

💖 NAME 💖

btrfs-backup-ng-doctor — the little wellness checkup for ur whole backup system, bestie. It diagnoses what's healthy and what's lowkey falling apart, and it can fix the easy stuff too.

✨ SYNOPSIS ✨

btrfs-backup-ng doctor [OPTIONS]

🩺 DESCRIPTION 🩺

Okay so picture this: ur backups have been doing their thing, and u just wanna know if everything's actually fine. That's the doctor command. It analyzes and diagnoses problems with the backup system — it checks ur configuration, snapshot health, transfer state, and system resources, then hands u a full health report. And if u want, it'll even auto-fix stuff. Iconic behavior honestly.

It's built for both vibes: u can sit there interactively troubleshooting like a detective 🔍, or u can let it run automated monitoring in the background while u live ur life. And because it's a main character, it can spit out JSON output so monitoring systems can just... absorb the info. no cap.

💅 OPTIONS 💅

  • --json — Drops the results as JSON instead of pretty text. Perfect for scripting and monitoring integration. feed it to ur machines, they'll eat it up 🍓
  • --check CATEGORY — Only runs the checks in one category. Here's the menu, and yes it's a valid list, don't get creative:
    • config — Configuration checks: does the config file exist and is it valid, are the volume sources usable (this is literally the same check as config validate), are targets reachable, are the compression programs available.
    • snapshots — Snapshot health checks: orphaned snapshots (they're on disk but nobody's tracking them 💀), missing snapshots (tracked in metadata but not actually on disk), broken parent chains.
    • transfers — Transfer and operation checks: stale locks (the process owning them isn't running anymore), incomplete transfers, recent failures in the transaction log.
    • system — System state checks: destination space availability, quota limits approaching, systemd timer status, last backup age.
  • --fix — Auto-fixes the safe issues. Currently that's:
    • Stale lock files from dead processes
    • Temporary files from incomplete operations
  • --interactive — When u pair this with --fix, it asks u to confirm before applying each fix. Without this flag? It just applies all the safe fixes automatically. no questions asked, queen behavior.
  • -q, --quiet — Only shows problems. Suppresses all the OK and INFO findings so u're not drowning in good news. (iykyk, sometimes u just want the drama.)
  • --volume PATH — Only checks the one volume u name. Great for zooming ur diagnostics in on a specific backup volume instead of scanning everything.

🔬 DIAGNOSTIC CATEGORIES 🔬

🛠️ Configuration Checks

  • The configuration file exists and is valid TOML
  • Every volume's source can be read, exists, and is a directory on btrfs; a native source is also a subvolume root (a snapper source doesn't have to be, since snapper takes its snapshots)
  • SSH targets are reachable (there's a connection test)
  • The required compression programs are installed (zstd, gzip, etc.)
  • Retention policies are valid and reasonable

🦋 Snapshot Health Checks

  • Orphaned snapshots: they exist on disk but aren't tracked in backup metadata
  • Missing snapshots: they're tracked in metadata but not present on disk
  • Broken parent chains: incremental backup parents are missing
  • Unparseable snapshot dates: naming convention issues, messy

🚚 Transfer/Operation Checks

  • Stale locks: lock files where the owning process is no longer running
  • Incomplete transfers: partial backup data left over from interrupted operations
  • Recent failures: errors in the transaction log from failed operations
  • Long-running operations: transfers that may be stuck

🌡️ System State Checks

  • Destination space low: less than 20% free space (warning)
  • Destination space critical: less than 5% free space (error)
  • Quota limits approaching: btrfs qgroup limits nearly reached
  • Systemd timer not active: scheduled backups may not run 😭
  • Last backup too old: more than 24 hours since the last successful backup

🚦 SEVERITY LEVELS 🚦

  • OK — Check passed, no issues found. slay.
  • INFO — Informational finding, no action required.
  • WARN — A warning condition that should be addressed, but it's not critical.
  • ERROR — An error condition that will likely cause backup failures.
  • CRITICAL — A critical issue requiring immediate attention. drop everything bestie 🚨

🚪 EXIT STATUS 🚪

  • 0 — Healthy: all findings are OK or INFO level.
  • 1 — Warnings present: one or more WARN findings.
  • 2 — Errors or critical issues: one or more ERROR or CRITICAL findings.

🌈 EXAMPLES 🌈

Run the full diagnostics:

btrfs-backup-ng doctor

JSON output for monitoring:

btrfs-backup-ng doctor --json

Check only the configuration:

btrfs-backup-ng doctor --check config

Check only snapshot health:

btrfs-backup-ng doctor --check snapshots

Auto-fix the safe issues:

btrfs-backup-ng doctor --fix

Interactive fix, with u confirming each one:

btrfs-backup-ng doctor --fix --interactive

Only show the problems:

btrfs-backup-ng doctor --quiet

Check one specific volume:

btrfs-backup-ng doctor --volume /home

📄 OUTPUT FORMAT 📄

🫶 Human-Readable Output

btrfs-backup-ng Doctor
=======================================================

Configuration
  [OK]    Config file valid
  [OK]    Volume path valid: /home
  [WARN]  Compression program 'pigz' not found

Snapshots
  [OK]    Volume /home: 24 snapshots, chain intact

Transfers
  [WARN]  Stale lock: home-20260110 (process 12345 not running)
          [FIXABLE] Run with --fix to remove

System
  [OK]    Destination: 524 GiB available (52%)
  [OK]    Systemd timer active, next: 2h 15m

=======================================================
Summary: 7 passed, 2 warnings, 0 errors
Fixable: 1 issue (run with --fix)

🧾 JSON Output

When --json is specified, the output is a JSON object containing:

  • timestamp: ISO 8601 timestamp of the diagnostic run
  • duration_seconds: time taken for diagnostics
  • summary: counts of ok, warnings, errors, and fixable issues
  • findings: an array of diagnostic findings with category, severity, message, and details

🤖 AUTOMATION 🤖

📡 Monitoring Integration

Use the JSON output with ur monitoring systems:

#!/bin/bash
result=$(btrfs-backup-ng doctor --json)
exit_code=$?

if [ $exit_code -ne 0 ]; then
    echo "$result" | jq '.findings[] | select(.severity != "ok")'
    # Send to monitoring system
fi

⏰ Cron Job Health Check

# Check backup health daily
0 8 * * * /usr/bin/btrfs-backup-ng doctor --quiet ||     mail -s "Backup health check failed" admin@example.com

🔧 Auto-Fix in Scripts

#!/bin/bash
# Run doctor with auto-fix, alert on remaining issues
btrfs-backup-ng doctor --fix --quiet
if [ $? -ne 0 ]; then
    btrfs-backup-ng doctor --json |         jq '.findings[] | select(.severity == "error" or .severity == "critical")' |         mail -s "Backup issues requiring attention" admin@example.com
fi

👀 SEE ALSO 👀

btrfs-backup-ng(1), btrfs-backup-ng-verify(1), btrfs-backup-ng-status(1), btrfs-backup-ng-config(1)

okay that's the whole page pookie 🎀 this came from btrfs-backup-ng, and this version is dated January 2026. take ur backups seriously and ur health checks even more seriously, mwah 💋 periodt.

✨ stay healthy, stay backed up ✨

📦 where this page comes from