Plan A: ZFS storage backend foundation

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.

[sodre]

Summary

Adds an opt-in ENROOT_STORAGE_BACKEND=zfs storage driver that replaces unsquashfs-per-create with extract-once-then-zfs clone. First create of a given image pays full extraction cost; subsequent creates from the same image are near-instant clones whose disk cost is only the diff from the shared template. Default dir backend is byte-for-byte unchanged.

This is the first of six plans (A-F) for the ZFS backend, each landing as its own PR. See doc/plans/README.md for the full landing order.

Scope (Plan A):

• New module src/storage_zfs.sh with zfs:: namespace helpers.
• Backend dispatch in runtime::create and runtime::remove on ${ENROOT_STORAGE_BACKEND}.
• Templates at ${ENROOT_DATA_PATH}/.templates/<sha256> with @pristine snapshot.
• User clones at ${ENROOT_DATA_PATH}/<NAME> (zfs clone of @pristine).
• Refcount-only template lifecycle: template destroyed when last clone goes away.
• Atomic concurrent-extraction via <sha>.tmp dataset lock + bounded snapshot wait.
• Design captured in doc/zfs.md.

Out of scope (later plans): template warm/cold lifecycle (B), .zfs file format (C), zfs:// URI transport (D), ephemeral start <image> ZFS path (E), Docker layer-stacking on ZFS (F).

Test Plan

This codebase has no automated test suite; verification is manual. Plan A's tasks were executed against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1; all verifications pass.

• bash -n src/storage_zfs.sh clean
• make builds with src/storage_zfs.sh in SRCS
• enroot info reports ENROOT_STORAGE_BACKEND=zfs when set
• dir backend regression: enroot create alpine.sqsh then enroot remove works as before
• ZFS create extracts template + clones; second create from same .sqsh is <100ms (no extraction log)
• Concurrent enroot creates race-safe: 4 concurrent extractions yield exactly one template
• ZFS remove keeps template alive while sibling clones exist; reaps template when last clone removed
• enroot list enumerates ZFS clones; .templates dotfile is hidden (no code change needed)
• enroot start <name> /bin/echo hello runs against ZFS clone

Linux mount(2) caveat: ZFS delegation on Linux still requires CAP_SYS_ADMIN for the kernel mount(2) syscall. Practical workaround documented in doc/zfs.md: run enroot create privileged (sudo); start/exec/remove work unprivileged.