Plan D: zfs:// URI transport over SSH

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.

[sodre]

Summary

Adds a zfs://[USER@]HOST/NAME URI scheme for transporting containers between enroot hosts as zfs send streams over SSH. Both ends must run enroot with ENROOT_STORAGE_BACKEND=zfs.

• enroot load zfs://host/NAME — pull and instantiate as a container in one step.
• enroot export NAME zfs://host (or zfs://host/REMOTE) — push a local container to a remote enroot host.
• enroot import -o file.zfs zfs://host/NAME — pull and save as a portable file (.zfs by default; .sqsh if the output filename ends in .sqsh).

Implements Plan D. Builds on Plans A (#1), C (#7).

What changed

All ZFS-specific lifecycle stays in src/storage_zfs.sh; touch points in enroot.in and src/runtime.sh are minimal dispatches.

• src/storage_zfs.sh — six new helpers (all zfs::*):
  • zfs::parse_uri URI — zfs://host/NAME → two lines (host then NAME), matching docker::_parse_uri's convention.
  • zfs::send_clone_stdout NAME — zfs send the clone's @pristine (or fresh snapshot for non-clones) to stdout.
  • zfs::recv_to_template_stdin NAME — buffers stdin to a temp file, hashes for cache key, materializes via zfs::ensure_template_from_stream, clones to NAME. Same Plan B sweep + touch lifecycle.
  • zfs::pull_via_ssh URI [NAME] — ssh host enroot export --zfs-send REMOTE | zfs::recv_to_template_stdin LOCAL.
  • zfs::push_via_ssh NAME URI — zfs::send_clone_stdout NAME | ssh host enroot import --zfs-recv -n REMOTE.
  • zfs::import_uri URI FILENAME — pulls and writes a file. Format inferred from output extension: .sqsh triggers a recv-into-temp-dataset → mksquashfs → destroy-temp pipeline (requires local ZFS); anything else streams the raw zfs send bytes to file (no local ZFS receive required).
• enroot.in — added --zfs-send to enroot::export and --zfs-recv (with -n NAME) to enroot::import. Both gate on ENROOT_STORAGE_BACKEND=zfs. Internal flags used by the SSH peer side. Updated import / load / export usage blocks to document zfs://.
• src/runtime.sh — three thin dispatches: runtime::load routes zfs://* to zfs::pull_via_ssh; runtime::export routes zfs://* destinations to zfs::push_via_ssh; runtime::import routes zfs://* to zfs::import_uri.
• doc/zfs.md + CLAUDE.md — status notes flipped to "All six plans implemented".

Why enroot import zfs:// is allowed (originally was rejected)

Initial design treated zfs:// as transport-only — import would produce no portable artifact, so it was rejected with "use 'enroot load'". That framing missed a real case: a .zfs file IS portable, just to ZFS hosts. And a .sqsh produced from a remote ZFS source serves a useful relay workflow (pull on a host with SSH access, transfer the file to a host without). The current behavior accepts both forms; format is inferred from the output filename extension so no new flag is needed.

Wire format and privacy

The wire is just ssh host enroot ... invocations. The URI names a container on a remote enroot host, not a raw dataset path. The remote's pool name and dataset hierarchy never leak — the remote enroot resolves its own store layout. (One small caveat: zfs send includes the source snapshot's full dataset path in the stream header. For trusted-host replication this is fine; for cross-org transfers it leaks the sender's pool naming. Same as the .zfs file format from Plan C.)

Test Plan

Verified manually with passwordless SSH to root@localhost on a loopback ZFS pool (Linux 6.12.75, aarch64, zfs-2.4.1):

• enroot load zfs://root@localhost/donor pulls a clone, rootfs readable, enroot start pulled /bin/cat /etc/os-release prints alpine os-release.
• enroot export pulled -o zfs://root@localhost/pushed ships the container; the remote enroot list shows pushed.
• enroot import -o file.zfs zfs://... writes a 10MB ZFS send stream; subsequent enroot create file.zfs instantiates correctly.
• enroot import -o file.sqsh zfs://... writes a valid 8MB squashfs (recv-temp-dataset path); the resulting .sqsh works on the dir backend with no local ZFS required.
• Hard error without ZFS backend: enroot load zfs://... errors with "zfs:// URIs require ENROOT_STORAGE_BACKEND=zfs".
• Hard error without ZFS backend on push: enroot export -o zfs://... errors with "zfs:// destinations require ENROOT_STORAGE_BACKEND=zfs".
• zfs::recv_to_template_stdin integrates with Plan B: sweep + touch fire on the receive side too.

Known limitations

• No incremental sends (zfs send -i) — full streams only. A future iteration could add --since=BASE and have the receiver enumerate locally-cached templates over the wire to find a common ancestor; out of scope here.
• Stream metadata leaks the sender's pool/dataset path in the snapshot name embedded in the stream header. Same caveat as .zfs files (Plan C).
• No fallback if the remote enroot doesn't speak --zfs-send / --zfs-recv. The remote will print its usage and produce no stream; the local side will fail receive. Acceptable per the design — silent fallback would be confusing.
• Authentication via standard SSH config. Passwordless SSH and any ssh_config Host blocks (port, identity, jump hosts) are honored because we shell out to ssh.
• enroot import -o file.sqsh zfs://... requires local ZFS to do the temp-dataset receive + mksquashfs transform. This is a mild surprise but unavoidable without remote-side cooperation.