zrepover - ZFS Replication Takeover Tool

Companion tool for zrep that enables system cloning and takeover from zrep snapshots.

What is zrepover?

zrepover (ZFS REPlication takeOVER) takes zrep snapshots from a backup pool and creates bootable live filesystems through space-efficient clones. It's designed for the "laptop cloning" use case: replicate your main system to a USB SSD with zrep, then use zrepover on a target machine to take over those snapshots as a running system.

Key Features

• Two-Stage Workflow: Stage snapshots with send, then create live clones with takeover
• Space-Efficient Clones: Uses ZFS clones (not copies) - instant creation, shared blocks
• Smart Path Remapping: --strip option for flexible source-to-destination mapping
• Property Preservation: Automatically sets correct mountpoint and canmount on clones
• Incremental Updates: Re-run to update from newer zrep snapshots
• Safety First: Validates snapshots on ALL datasets before recursive operations

Use Case: Clone Your Laptop

You have a Gentoo laptop backed up with zrep to a USB SSD (jBAK pool). You want to clone it to a new laptop.

Source Laptop                    USB SSD (jBAK)                Target Laptop
┌─────────────┐    zrep          ┌─────────────┐    zrepover   ┌─────────────┐
│ tank/zroot  │ ───────────────► │ jBAK/j1/tank│ ───────────► │ tank/zroot  │
│ data/...    │   snapshots      │ jBAK/j1/data│   takeover    │ data/...    │
└─────────────┘                  └─────────────┘               └─────────────┘

Quick Start

# On target laptop with USB SSD connected:

# 1. Import the backup pool
zpool import jBAK

# 2. Stage snapshots to local pool (preserves zrep_* for future incrementals)
zrepover send jBAK/j1/tank tank/j1 --strip 2
zrepover send jBAK/j1/data data/j1 --strip 2

# 3. Takeover: clone staged snapshots to live filesystems
zrepover takeover tank/j1/tank tank --strip 3
zrepover takeover data/j1/data data --strip 3

# 4. Export USB and reboot!
zpool export jBAK
reboot

Commands

Command	Description
send	Send snapshots with path remapping (zfs send -R | zfs recv)
takeover	Clone staged snapshots to live filesystems (alias for clone -R -F)
clone	Clone snapshots to new datasets
sync	Simple pool-to-pool sync (alias for send --strip 1)
list	List available snapshots

send - Stage Snapshots

# Send from USB backup to local staging area
zrepover send jBAK/j1/tank tank/j1 --strip 2

# Path mapping with --strip 2:
#   jBAK/j1/tank/zroot/opt → tank/j1/tank/zroot/opt
#   (strips "jBAK/j1" prefix)

# Options:
#   -S, --strip N    Strip N path components from source
#   -s, --snapshot   Target specific snapshot (default: auto-detect latest)
#   -F, --force      Force send (destroys existing destination)
#   -P, --preview    Preview path mappings
#   -n, --dry-run    Show commands without executing

takeover - Clone to Live FS

# Takeover: create live bootable clones from staging
zrepover takeover tank/j1/tank tank --strip 3

# Path mapping with --strip 3:
#   tank/j1/tank/zroot/opt → tank/zroot/opt
#   (strips "tank/j1/tank" prefix, result is "zroot/opt")

# Smart features:
# - Skips cloning pool root to preserve staging area
# - Sets correct mountpoint (e.g., /opt for tank/zroot/opt)
# - Sets canmount property from source
# - Unsets source mountpoint to prevent conflicts

Two-Stage Workflow Explained

Why Two Stages?

1. Stage 1 (send): Preserves all zrep snapshots for future incremental updates
2. Stage 2 (takeover): Creates space-efficient clones that can be updated independently

After Stage 1 (send):
  tank/j1/tank/zroot/opt@zrep_000001  ← preserved for incrementals
  tank/j1/tank/zroot/opt@zrep_000002  ← preserved for incrementals

After Stage 2 (takeover):
  tank/j1/tank/zroot/opt@zrep_000002  ← staging (mountpoint=none)
  tank/zroot/opt                       ← live clone (mountpoint=/opt)

Incremental Updates

# After more zrep snapshots are created on source...

# Re-run send (auto-detects incremental)
zrepover send jBAK/j1/tank tank/j1 --strip 2

# Re-run takeover (destroys old clones, creates new from latest)
zrepover takeover tank/j1/tank tank --strip 3

Safety Features

Recursive Send/Receive Safety

• Snapshot validation: Verifies target snapshot exists on ALL datasets in tree
• Base snapshot validation: For incrementals, validates base exists everywhere
• No destructive incremental: Uses -u not -F to prevent data loss

Clone Safety

• Smart root skipping: Preserves staging area when cloning to pool root
• Property preservation: Sets mountpoint, canmount from source
• Conflict prevention: Unsets source mountpoint after clone
• Preview mode: --preview shows mappings before execution
• Dry-run mode: -n shows exact commands

Requirements

• ZFS utilities (zfs, zpool commands)
• Bash 4.3+ (for mapfile and local -n)
• Root/sudo privileges for ZFS operations
• zrep snapshots on source

Installation

git clone https://github.com/sineer/zrepover.git
cd zrepover
chmod +x zrepover.sh

# Optional: add to PATH
ln -s $(pwd)/zrepover.sh /usr/local/bin/zrepover

File Structure

zrepover/
├── zrepover.sh            # Main CLI script
├── lib/
│   ├── common.sh          # Shared utilities
│   ├── send.sh            # Send with path remapping
│   ├── clone.sh           # Clone functions (including recursive)
│   ├── replicate.sh       # Replication functions
│   └── recursive.sh       # Recursive sync functions
├── examples/
│   └── snapshots.txt      # Example input file
└── README.md

Credits

• zrep by Philip Brown (https://github.com/bolthole/zrep) - The ZFS replication tool that zrepover complements
• Built with assistance from Claude Code

License

MIT License