btrfs-backup-ng-doctor - Man Page

diagnose backup system health and fix common issues

Analyze and diagnose problems with the backup system. The doctor command checks configuration, snapshot health, transfer state, and system resources, providing a comprehensive health report with optional auto-fix capabilities.

The command is designed for both interactive troubleshooting and automated monitoring. JSON output is available for integration with monitoring systems.

Options

--json

Output results in JSON format for scripting and monitoring integration.

--check CATEGORY

Check only the specified category. Valid categories:

config: Configuration checks: config file exists and valid, volume paths exist and are btrfs subvolumes, targets reachable, compression programs available.
snapshots: Snapshot health checks: orphaned snapshots (on disk but not tracked), missing snapshots (tracked but not on disk), broken parent chains.
transfers: Transfer and operation checks: stale locks (process not running), incomplete transfers, recent failures in transaction log.
system: System state checks: destination space availability, quota limits approaching, systemd timer status, last backup age.

--fix

Auto-fix safe issues. Currently fixes:

Stale lock files from dead processes
Temporary files from incomplete operations

--interactive

When used with --fix, prompt for confirmation before applying each fix. Without this flag, all safe fixes are applied automatically.

-q, --quiet

Only show problems. Suppress OK and INFO findings in output.

--volume PATH

Check only the specified volume. Can be used to focus diagnostics on a specific backup volume.

Diagnostic Categories

Configuration Checks

Configuration file exists and is valid TOML
All configured volume paths exist and are btrfs subvolumes
SSH targets are reachable (connection test)
Required compression programs are installed (zstd, gzip, etc.)
Retention policies are valid and reasonable

Snapshot Health Checks

Orphaned snapshots: exist on disk but not tracked in backup metadata
Missing snapshots: tracked in metadata but not present on disk
Broken parent chains: incremental backup parents are missing
Unparseable snapshot dates: naming convention issues

Transfer/Operation Checks

Stale locks: lock files where the owning process is no longer running
Incomplete transfers: partial backup data from interrupted operations
Recent failures: errors in 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 last successful backup

Severity Levels

OK: Check passed, no issues found.
INFO: Informational finding, no action required.
WARN: Warning condition that should be addressed but is not critical.
ERROR: Error condition that will likely cause backup failures.
CRITICAL: Critical issue requiring immediate attention.

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 full diagnostics:: btrfs-backup-ng doctor
JSON output for monitoring:: btrfs-backup-ng doctor --json
Check only configuration:: btrfs-backup-ng doctor --check config
Check only snapshot health:: btrfs-backup-ng doctor --check snapshots
Auto-fix safe issues:: btrfs-backup-ng doctor --fix
Interactive fix with confirmation:: btrfs-backup-ng doctor --fix --interactive
Only show problems:: btrfs-backup-ng doctor --quiet
Check specific volume:: btrfs-backup-ng doctor --volume /home

Output Format

Human-Readable Output

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

Configuration
  [OK]    Config file valid
  [OK]    Volume /home exists and is btrfs subvolume
  [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, 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: Array of diagnostic findings with category, severity, message, and details

Automation

Monitoring Integration

Use JSON output with 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

Info

January 2026 btrfs-backup-ng