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 on Devices

Smart CBT requires low-level system access and must be explicitly enabled per device from the Dashboard.

Step 1: Arming the Device

1. Navigate to the Devices panel in the StateWarden Dashboard.
2. Select the target Device.
3. Click the CBT Toggle Switch to enable CBT.

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. Disarming and Resetting CBT

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

1. Navigate to the Devices panel.
2. Toggle the CBT Switch to the "Off" position.

Note: Disarming CBT clears the current tracking sequence. The subsequent backup will default to a standard File-System Walk (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 sw 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.