Uh oh!
There was an error while loading. Please reload this page.
Plan C: .zfs image format (zfs send streams) - #7
Merged
Conversation
ensure_template_from_stream is the recv-side sibling of ensure_template: same atomic .tmp lock pattern, sweep + touch integration with Plan B's warm/cold lifecycle, but uses 'zfs receive' instead of 'unsquashfs' to materialize the template. The received dataset's snapshot may not be named @pristine (depends on what the sender sent), so we look it up and rename if needed. send_stream is the export-side helper: zfs send the clone's origin @pristine snapshot to a file. For non-clones (containers created by some other means), takes a fresh snapshot, sends, then destroys it. zfs receive does not auto-create parents, so the templates parent is created via 'zfs create -p' before the recv attempt. Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
.zfs is a zfs send stream; only valid with the ZFS backend. .sqsh keeps existing two-axis dispatch (extension first, then backend). Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
CLI gains a --format flag (default sqsh; zfs requires the ZFS backend). runtime::export refactors into format-specific helpers: _export_sqsh keeps the existing mksquashfs path byte-for-byte; _export_zfs writes a zfs send stream of the clone's @pristine snapshot via zfs::send_stream. Behavior change: the function signature now takes an optional third format argument from enroot::export. Old callers that didn't pass a third arg still work — sqsh is the default. Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
Audit of the function refactors landed across Plans A and C found seven upstream comments that were dropped during the function splits. Restoring them brings the helpers back to byte-for-byte parity with upstream's documentation. In runtime::_create_dir (Plan A): restore # Resolve the container rootfs path. # Extract the container rootfs from the image. In runtime::remove and the new _remove_dir / _remove_zfs (Plan A): restore # Resolve the container rootfs path. # Remove the rootfs specified after asking for confirmation. In runtime::_export_sqsh (Plan C): restore # Resolve the container rootfs path. # Generate an absolute filename if none was specified. # Export a container image from the rootfs specified. Plan E's runtime::start and Plan F's docker::load were verified to have preserved their upstream comments in full. Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
Per the same principle that drove the Plan F refactor, keep ZFS code together so the delta to existing files (here, src/runtime.sh) stays minimal. The previous commit had two private runtime helpers (runtime::_create_zfs_from_stream and runtime::_export_zfs) that were thin wrappers over zfs:: calls; consolidating them into the ZFS module and dispatching directly from runtime::create / runtime::export is cleaner. New helpers in src/storage_zfs.sh: - zfs::create_from_stream IMAGE NAME Counterpart of zfs::ensure_template + zfs::clone_container for the .sqsh path; called from runtime::create when the input image has a .zfs extension. - zfs::export_to_file NAME FILENAME Owns filename defaulting and the file-already-exists guard so runtime::export's ZFS branch is a single dispatch call. src/runtime.sh now calls the new helpers directly; the deleted private wrappers were boilerplate. Signed-off-by: Patrick Sodré <patrick@zero-ae.com>
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
.zfs(zfs send stream) as a second image format alongside.sqsh.enroot create foo.zfsmaterializes the stream into the template cache viazfs receive, then clones to the user's container.enroot export --format=zfs NAMEproduces a.zfsfile from a clone's@pristinesnapshot.Implements Plan C. Builds on Plans A (#1), B (#5).
What changed
src/storage_zfs.sh— two new helpers (allzfs::*):zfs::ensure_template_from_stream STREAM SHA— recv-side sibling ofzfs::ensure_template. Same atomic.tmplock pattern, sweep + touch integration with Plan B's warm/cold lifecycle, but useszfs receiveinstead ofunsquashfs. Auto-creates the templates parent dataset (zfs receive doesn't auto-create parents). The received dataset's snapshot may not be named@pristine(depends on what the sender sent), so we look it up and rename if needed.zfs::send_stream NAME FILENAME— exports the clone's origin@pristinesnapshot to a file. For non-clones (containers created some other way), takes a fresh snapshot, sends, then destroys it.src/runtime.sh(runtime::create) — two-axis dispatch (extension first, backend second).*.zfs→runtime::_create_zfs_from_stream(requiresENROOT_STORAGE_BACKEND=zfs; hard error otherwise). Other extensions → existing.sqshpath with backend dispatch from Plan A.src/runtime.sh(runtime::export) — refactored into_export_sqsh(today'smksquashfsbyte-for-byte) and_export_zfs(new). Top-level dispatches on the format argument; default issqsh.enroot.in(enroot::export) — added--format/--format=CLI flag; updated usage block.doc/zfs.md+CLAUDE.md— status notes flipped to "Plans A, B, C, E, F implemented".Why no magic-byte sniffing
The dispatcher decides what a file is purely by extension (
*.zfsvs everything-else). No magic-byte sniffing. If a user feeds a.zfsfile to a non-ZFS host they get a clear ".zfsimages requireENROOT_STORAGE_BACKEND=zfs" error rather than a confusing failure deep insideunsquashfs -s. Symmetric to how.sqshis unambiguously squashfs.Test Plan
Verified manually against a loopback ZFS pool on Linux 6.12.75 (aarch64), zfs-2.4.1:
create -n a alpine.sqsh→export -f --format=zfs -o donor.zfs a→ wipe template cache →create -n b donor.zfs→start b /bin/cat /etc/os-releaseprints alpine os-release./etclisting of a container created fromalpine.sqshmatches the listing of one created from the round-trippeddonor.zfs..sqshregression:enroot export -f -o foo.sqsh NAME(no--format) still produces a valid squashfs..zfshard error on dir backend:ENROOT_STORAGE_BACKEND=dir enroot create foo.zfserrors with ".zfsimages requireENROOT_STORAGE_BACKEND=zfs".--format=zfshard error on dir backend:ENROOT_STORAGE_BACKEND=dir enroot export --format=zfs ...errors with "--format=zfsrequiresENROOT_STORAGE_BACKEND=zfs".--format=invaliderrors:enroot export --format=tar ...errors with "Invalid format: tar".ensure_template_from_streamcallszfs::sweep_templatesfirst (cold/warm/pressure logic applies) andzfs::touch_templateon extract and on cache-hit reuse — same lifecycle as the.sqshpath.Known limitations
zfs send/receiveproduces a stream with the origin snapshot's name embedded in metadata (e.g.tank/enroot/sodre/.templates/<sha>@pristine). The sender's pool/dataset name is therefore visible in the stream header. For Plan D (zfs://URI), the equivalent stdin/stdout helpers will need to strip this if cross-host privacy matters; for.zfsfiles passed between trusted operators, it's a non-issue..zfsis the sha256 of the file, not of the underlying snapshot's content. Two.zfsfiles produced from the same template at different times will differ byte-for-byte (different stream timestamps in the header) and cache as separate templates. ZFS block-level dedup on the templates dataset recovers most of this.zfs send -i) — full streams only. A future iteration could add--from=BASEto--format=zfs, but it requires the receiver to already have the base snapshot, which conflicts with the "drop a file on a host" simplicity of the current scheme.