Learn Borg Backup - Check & Maintenance

#Introduction

After backups run automatically via borgmatic and are sent remotely over SSH, there is one danger that often slips through: silently corrupt backups. Disks can suffer bit rot, networks can cut transfers, and nobody knows until restore time. Episode 12 closes this gap: regular integrity verification and disciplined maintenance.

#borg check: Consistency Verification

#The Basic Check

borg check /backup/borg

borg check verifies the internal consistency of the repository:

• Index vs segments: whether every referenced chunk actually exists in a segment.
• Manifest and archive metadata: whether each archive is readable and consistent.
• Rebuild hints: if the index is damaged, borg check reconstructs it from the segments.

The result is "yes, the repository is structurally healthy". Note: this is not proof that the file contents are correct — that is the job of --verify-data.

#Content Verification: --verify-data

borg check --verify-data /backup/borg

--verify-data re-reads every chunk and verifies its checksum/hash. This is the most thorough check, but also the slowest — taking time proportional to the total stored data. The strategy:

• Regular borg check: monthly (cheap, fast).
• borg check --verify-data: once a year or after a suspicious event (e.g. the disk ran full, a crash, or I/O error reports).

#Checks in borgmatic

In episode 9 we already defined check frequencies in borgmatic:

checks:
  - name: repository
    frequency: 1 month
  - name: data
    frequency: 1 year

borgmatic remembers when the last check ran (stored in its cache) and only runs the ones that are due — so a check does not slow down every daily backup.

#Routine Maintenance

#Scheduled Compact

borg compact cleans up segments that hold unused chunks after prune/delete. Run it as part of the routine:

borg compact /backup/borg

If you use borgmatic, add a compact: true line to the config or call a scheduled borgmatic compact.

#Log Review

Failed backups usually leave a trail in the logs. Make a short review ritual:

tail -50 /var/log/borgmatic.log

Look for patterns: does it always fail on the same file? Does backup duration spike? A consistently rising duration can signal a weakening disk or data accumulating without exclusions.

#Disk Health

The Borg repository depends entirely on disk health. Monitor it with SMART:

sudo smartctl -H /dev/sdb
sudo smartctl -A /dev/sdb | grep -E "Reallocated|Pending|CRC"

• A rising Reallocated_Sector_Ct or Current_Pending_Sector is a red flag: migrate the repository to a healthy disk immediately and run borg check --verify-data.
• Keep free space always above a safe threshold. A repository running out of space mid-segment-write can become corrupt.

#A Recommended Maintenance Calendar

Daily   : automatic backup (borgmatic) + quick log check
Weekly  : borg check (repository) + disk space review
Monthly : borg compact + smartctl -H + verify one restore
Yearly  : borg check --verify-data + full restore drill

The key to this calendar: everything is scheduled, nothing depends on memory. Cron or a systemd timer handles the daily; the monthly check can also be scheduled via borgmatic's frequency.

#Common Pitfalls

• Only checking when suspicious: damage is discovered years later — when a restore is needed. Schedule it.
• Forgetting compact: the repository bloats because segments hold dead chunks. Compact is part of maintenance, not optional.
• A full disk without knowing it: set up disk space alerts (episode 20); running out of space mid-write is a classic corruption cause.
• Running --repair without a backup: one bad decision can delete data that could actually have been saved.

#Closing

• borg check verifies the structural consistency of the repository.
• borg check --verify-data verifies the contents of every chunk — thorough but slow.
• borgmatic can schedule checks with frequency without slowing down daily backups.
• Maintenance: scheduled compact, log reviews, and SMART + disk space monitoring.
• --repair deletes data that cannot be repaired — be careful.
• Every maintenance ritual must be scheduled, not memory-dependent.

In episode 13 we lock the repository down from the backup's worst enemy: repository security — append-only mode as an anti-ransomware defense (Borg 1.2+), authenticated encryption, and the SSH lock with command="borg serve --restrict-to-path ...".