Smart CBT: Incremental Backups

The duration of a backup window depends significantly on how the system identifies modified data. Traditional file-based backup solutions use stat() calls and timestamp comparisons (mtime), which requires scanning the filesystem tree. This metadata scan can be time-consuming on volumes with large numbers of files.

StateWarden utilizes Smart CBT (Changed Block Tracking) to address this limitation. By integrating with the native mechanisms of the host operating system, StateWarden tracks sector-level modifications to identify changed data without a full directory scan.

1. How Smart CBT Works

StateWarden’s Smart CBT engine interacts with the host OS to monitor block-level changes.

• Windows (USN Journal): The Agent parses the native NTFS Update Sequence Number (USN) Journal to identify modified files. It then maps these modifications to their physical Logical Cluster Numbers (LCNs) using the FSCTL_GET_RETRIEVAL_POINTERS API call.
• Linux (dm-era / LVM): The Agent integrates with dm-era (device mapper) and LVM to intercept write operations at the block device level. This tracks changed sectors independently of the underlying filesystem (e.g., ext4, xfs, btrfs).

Incremental backups process only the blocks that have changed since the last snapshot.

2. Enabling CBT per Volume

Smart CBT requires low-level system access and is controlled per volume from the Dashboard.

Step 1: Enable the CBT Toggle

1. Navigate to the Devices panel and open the target Device's detail view.
2. Select the Storage & Backups tab.
3. Locate the volume and switch its CBT toggle on. Enabling CBT on a critical system partition requires confirmation; a system reboot may be necessary before tracking becomes active.

The Dashboard reports the CBT state of every volume:

• CBT Possible - an indicator shown on volumes that meet the requirements for change tracking (reported by current agent versions).
• Where CBT cannot be enabled, a tooltip on the toggle explains why:
  • CBT Unavailable: Conflict with active tracking on ... - another tracked object overlaps the volume.
  • LVM uses native snapshots. CBT wrapper not required. - LVM logical volumes are snapshotted natively, so no CBT wrapper is applied.
  • Whole-disk CBT is disabled for multi-partition drives. Arm partitions individually. - enable CBT on the individual partitions instead of the whole disk.
  • CBT ineffective on encrypted volume. - raw encrypted data (BitLocker/LUKS) defeats block-level change tracking; such volumes are backed up as full reads.
  • CBT not available on this volume.

Step 2: The Baseline Scan (Full Scan)

When CBT is first enabled, StateWarden must establish a baseline. The next scheduled backup will be a Forced Full Scan. The Agent hashes the entire volume and uploads the necessary chunks to the Data Plane (Driad) to create the cryptographic baseline.

Step 3: Incremental Scans

Subsequent backups will execute as Incremental CBT Scans.

1. The Agent queries the OS (USN Journal or dm-era) for the list of blocks modified since the last snapshot.
2. The Agent hashes only the modified blocks.
3. The Agent uploads the new, unique chunks to the storage node.

This process reduces the overall time required to complete the backup operation.

3. Disabling CBT

CBT can be disabled per volume for system maintenance, partition resizing, or troubleshooting.

1. Open the Device's detail view and select the Storage & Backups tab.
2. Switch the volume's CBT toggle off and confirm the dialog.

Note: Disabling CBT destroys the current tracking metadata (on Linux, the dm-era tracking metadata). The subsequent backup will default to a Full Scan to rebuild the baseline.

4. Troubleshooting CBT

StateWarden will automatically fall back to standard file-system scanning if CBT encounters operational issues.

• Access Denied (Windows): The Agent requires Administrator privileges to access the USN Journal and \\.\PhysicalDrive paths. Ensure the StateWarden service has the appropriate permissions.
• Missing Dependencies (Linux): Linux CBT requires the dmsetup and thin-provisioning-tools packages. If these are absent, the Agent logs a warning and falls back to standard file-system scanning. The Dashboard will reflect this fallback state.
• System Upgrades: Major kernel upgrades or bare-metal restorations may invalidate the block tracking sequence, triggering an automatic fallback to a Full Scan on the next execution.