ZFS Snapshot Extractor

A bash script that helps you recover older versions of files from ZFS snapshots with an interactive interface.

Features

• Interactive Selection: Browse through available snapshots with an easy-to-use numbered menu
• Smart Deduplication: Only shows snapshots where the file actually changed (based on modification time)
• Pagination: View 5 snapshots at a time, with the option to show older versions
• Human-Readable Output: Displays snapshot names, modification dates, and file sizes
• Organized Recovery: Saves recovered files in dated directories for easy identification

Requirements

• Linux system with ZFS filesystem
• Bash 4.0 or later (for associative arrays)
• Standard utilities: stat, date, basename, mkdir, cp

Installation

1. Clone or download this repository
2. Make the script executable:
   bash chmod +x zfs-snapshot-extract.sh
3. Optionally, move it to a directory in your PATH:
   bash sudo mv zfs-snapshot-extract.sh /usr/local/bin/zfs-snapshot-extract

Usage

Basic Usage

Navigate to the root of a ZFS dataset mountpoint and run:

./zfs-snapshot-extract.sh <relative-file-path>

To see help information:

./zfs-snapshot-extract.sh --help
# or
./zfs-snapshot-extract.sh -h

Example

cd /tank/mydata
./zfs-snapshot-extract.sh documents/report.txt

This will:

1. Scan all snapshots in .zfs/snapshot/
2. Find all versions of documents/report.txt
3. Deduplicate by modification time
4. Display the 5 newest versions
5. Let you select which version to recover
6. Copy the selected version to ~/report.txt_<timestamp>/report.txt

Sample Output

ZFS Snapshot Extractor
=====================

File: documents/report.txt
Found 12 distinct version(s)

Showing snapshots 1-5 of 12:

#    Snapshot                       Modified                  Size
---- ------------------------------ ------------------------- ----------
1    autosnap_2024-01-15_14:00     2024-01-15 13:45:22       256KB
2    autosnap_2024-01-14_14:00     2024-01-14 16:20:15       245KB
3    autosnap_2024-01-12_14:00     2024-01-12 09:30:45       238KB
4    autosnap_2024-01-10_14:00     2024-01-10 11:15:33       220KB
5    autosnap_2024-01-08_14:00     2024-01-08 14:22:10       215KB

  1-5      - Select snapshot by number
  (N)ext, (D)ate, (E)xit

Enter your choice:

Navigation

The interactive menu supports:

• Number keys (1-5): Select a snapshot by its number - recovers the file and returns to menu
• P key: Show previous 5 newer versions (if not on first page)
• N key: Show next 5 older versions (if available)
• D key: Jump to a specific date/time - centers display around snapshots near that date
• E key: Exit the program

Both uppercase and lowercase letters are accepted.

Date Jump Feature

Press D to jump to snapshots from a specific date/time. The script accepts various date formats:

• ISO format (recommended): 2024-01-15 or 2024-01-15 14:30
• Text format: 15 Jan 2024 or 15 Jan 2024 14:30
• US format with slashes: 01/15/2024

The display will center around the snapshot closest to your specified date/time.

Multiple File Recovery

After recovering a file, you'll be prompted to press (E)xit or any other key to continue. This allows you to easily recover multiple versions when you're not sure which one you need.

Output Structure

When you select a snapshot, the file is copied to:

~/[filename]_[ISO-datetime]/[filename]

Example:

~/report.txt_20240115T134522/report.txt

How It Works

1. Validation: Checks that you're in a ZFS dataset root (.zfs/snapshot exists)
2. Scanning: Iterates through all snapshot directories
3. Deduplication: Groups files by modification time, keeping only the newest snapshot for each unique timestamp
4. Sorting: Orders snapshots by modification time (newest first)
5. Display: Shows 5 snapshots at a time with formatted dates and sizes
6. Selection: Uses bash's built-in select for numbered menu navigation
7. Recovery: Creates a timestamped directory and copies the selected file

Limitations

• Requires running from the ZFS dataset root (where .zfs is accessible)
• File path must be relative to the dataset root
• Only works with regular files (not directories)
• Assumes .zfs snapshots are visible (ZFS snapdir property set to visible)

Troubleshooting

"Cannot access .zfs directory"

• Ensure you're at the root of a ZFS dataset
• Check that snapshots are visible: zfs get snapdir <dataset>
• If snapdir=hidden, set it to visible: zfs set snapdir=visible <dataset>

"File not found in any snapshot"

• Verify the file path is correct and relative to the dataset root
• Check that snapshots actually contain this file
• Ensure the file existed when snapshots were taken

Script won't run

• Check execute permissions: chmod +x zfs-snapshot-extract.sh
• Verify bash is available: which bash
• Ensure you have bash 4.0+: bash --version

License

This project is provided as-is for free use and modification.

Contributing

Feel free to submit issues or pull requests for improvements.