Expand description
zfs-core — a pure-Rust, from-scratch ZFS on-disk reader.
P0 parses the ZFS bootstrap: the four vdev labels, the XDR-encoded
nvlist config (pool version/name/pool_guid/txg and the nested
vdev_tree ashift/asize), and the endian-adaptive uberblock array
(active = highest valid txg), exposing the active uberblock’s ub_rootbp
block pointer to the MOS. Later phases resolve the block-pointer tree,
dnodes, objsets, ZAP, and datasets.
Import path is zfs_core (the bare zfs and zfs-core crate names are both
taken on crates.io — see the repo README), e.g. use zfs_core::VdevLabel;.
§Safety and robustness
This crate parses untrusted, attacker-controllable disk images. It is
#![forbid(unsafe_code)] and every integer is read through bounds-checked,
endian-adaptive helpers (bytes) that yield 0/None out of range rather
than panic (the Paranoid Gatekeeper standard). nvlist length/count fields are
capped against allocation bombs.
Re-exports§
pub use xattr::has_unread_spill_xattrs;pub use xattr::list_xattrs;pub use xattr::Xattr;pub use bytes::Endian;pub use bytes::Reader;pub use checksum::ChecksumType;pub use compress::CompressType;
Modules§
- bytes
- Bounds-checked, endian-adaptive readers (the Paranoid Gatekeeper standard).
- checksum
- ZFS block checksums (fletcher2, fletcher4, sha256).
- compress
- ZFS block decompression (off, lzjb, lz4, gzip, zle, zstd).
- xattr
- ZFS extended attributes — both storage modes.
Structs§
- Blkptr
- A fully-decoded 128-byte block pointer.
- Blkptr
Summary - The P0 subset of a
blkptr_t: enough to expose the MOS root without walking the tree. Full DVA translation across vdevs, gang blocks, embedded blkptrs, checksum verify, and decompression are later phases. - Block
- A block read from the image: its logical bytes plus the checksum verdict.
- Dnode
- A parsed
dnode_phys_t. - Dva
- A Data Virtual Address: one ditto copy a block pointer records.
- NvList
- A decoded nvlist: an ordered set of
(name, value)pairs. - Objset
Phys - A parsed
objset_phys_t. - SaAttr
Desc - One SA attribute’s registration: its numeric id, its byte length, and its
byteswap class — decoded from a
REGISTRYZAP value ([length:bswap:id]). - SaLayouts
- The SA layouts: layout number → ordered array of attribute ids.
- SaRegistry
- The SA attribute registry: attribute name →
SaAttrDesc. - Uberblock
- A parsed uberblock: the pool root at one transaction group.
- Vdev
Label - A parsed vdev label: its config nvlist and its active uberblock.
- Vdev
Tree - The P0 subset of the nested
vdev_treeconfig. - ZplAttrs
- Decoded ZPL file/directory metadata — the superset the SA layout carries (and
the legacy
znode_phys_tprovides). Timestamps are(seconds, nanoseconds).
Enums§
- DmuType
- A DMU object type. Use
DmuType::rawfor the on-disk numeric value (e.g.DmuType::Objset.raw() == 11); the data-carryingDmuType::Othervariant means the enum is not a plain#[repr(u8)]cast. - NvValue
- A decoded nvpair value (the subset P0 needs from the pool config).
- ZfsError
- Errors surfaced while parsing ZFS on-disk structures.
Constants§
- BLKPTR_
SIZE - The size of one block pointer.
- BOOT_
SKEW - The 4 MiB skew that skips the two front vdev labels + boot block, added when translating a DVA offset to a raw byte position on the vdev.
- BPE_
PAYLOAD_ SIZE BPE_PAYLOAD_SIZE— bytes of inline payload an embedded blkptr carries in the three non-blk_prop/non-pad regions of the 128-byte pointer ([0,48) ++ [56,88) ++ [96,128)= 48 + 32 + 32).- DMU_
OST_ META DMU_OST_META— the objset type of the MOS.- DMU_
OST_ ZFS DMU_OST_ZFS— the objset type of a ZPL filesystem dataset.- DMU_
OT_ SA DMU_OT_SA(44) — a dnode bonus holding System Attributes.- DMU_
OT_ ZNODE DMU_OT_ZNODE(17) — a legacyznode_phys_tbonus.- DNODE_
CORE_ SIZE - The size of a dnode’s fixed core, before the block-pointer array
(
DNODE_CORE_SIZE). - DNODE_
SIZE - The base size of a dnode (
DNODE_MIN_SIZE), one slot. - LABEL_
SIZE - Size of a single vdev label (256 KiB).
- MAX_
BLOCK_ SIZE - Hard upper bound on a single block’s logical size (32 MiB —
SPA_MAXBLOCKSIZEwith headroom). A blkptr claiming more is an allocation bomb. - MAX_
INDIRECT_ LEVELS - Maximum indirect-block-tree depth to follow (
dn_nlevelsnever legitimately exceeds a handful; a lying value is bounded here). - NVLIST_
OFFSET - Offset of the packed nvlist config within a label (16 KiB).
- NVLIST_
SIZE - Size of the packed nvlist config region (112 KiB).
- SA_
LAYOUTS_ NAME - The SA master object’s
LAYOUTSentry name (→ the attribute-layouts ZAP). - SA_
MAGIC SA_MAGIC— thesa_hdr_phys_t.sa_magicvalue.- SA_
REGISTRY_ NAME - The SA master object’s
REGISTRYentry name (→ the attribute-registration ZAP). - SA_
TIME_ SIZE - The size of one packed timestamp attribute (
[u64 sec, u64 nsec]). - UBERBLOCK_
MAGIC UBERBLOCK_MAGIC(OuroBoros).- UBERBLOCK_
MIN_ SHIFT UBERBLOCK_SHIFT— log2 of the minimum uberblock slot size (1 KiB). The actual slot size ismax(1 KiB, 2^ashift), so aashift == 12pool uses 4 KiB slots and therefore 32 slots per 128 KiB ring (not 128).- UBERBLOCK_
RING_ OFFSET - Offset of the uberblock ring array within a label (128 KiB).
- UBERBLOCK_
RING_ SIZE - Size of the uberblock ring array (128 KiB).
- UB_
MMP_ MAGIC MMP_MAGIC— multi-modifier protection magic in the uberblock tail.- VDEV_
BOOT_ HEADER_ SIZE - Size of the boot-block header region (8 KiB).
- VDEV_
PAD_ SIZE - Size of the leading blank pad region (8 KiB).
- ZAP_
LEAF_ MAGIC ZAP_LEAF_MAGIC— a fat-ZAP leaf magic (zap_leaf_phys_t.l_magic).- ZAP_
MAGIC ZAP_MAGIC— the fat-ZAP header magic (zap_phys_t.zap_magic).- ZBT_
HEADER ZBT_HEADER— a fat-ZAP header block’szap_block_type.- ZBT_
LEAF ZBT_LEAF— a fat-ZAP leaf block’sl_block_type.- ZBT_
MICRO ZBT_MICRO— a micro-ZAP block’smz_block_type.- ZFS_
MAXPATHLEN MAXPATHLENon Linux (include/os/linux/spl/sys/sysmacros.h):zfs_symlinkrefuses a longer target withENAMETOOLONG.- ZNODE_
PHYS_ SIZE - The size of the legacy
znode_phys_tbonus. - ZPL_
DIRENT_ OBJ_ MASK - Mask for the object id within a ZPL directory-entry value (low 48 bits); the
top 4 bits carry the
ZFS_DIRENT_TYPE. - ZPL_
MASTER_ NODE_ OBJ - The ZPL master node object id (fixed by the on-disk format).
- ZPL_
ROOT_ NAME - The name under which the master node records the root directory’s object id.
- ZPL_
SA_ ATTRS_ NAME - The name under which the master node records the SA master object id.
Functions§
- active_
uberblock - Scan an uberblock ring, returning the valid uberblock with the highest
txgand its slot index, orNoneif no slot holds a valid uberblock. - decode_
sa_ bonus - Decode a
DMU_OT_SAbonus intoZplAttrs, resolving attribute sizes/ids via the registry and the packed order via the layout. - decode_
znode_ phys - Decode a legacy
znode_phys_tbonus (bonustypeDMU_OT_ZNODE= 17) intoZplAttrs. ReturnsNoneif the bonus is shorter than the 264-byte struct. - detect_
blkptr_ endian - Detect the byte order to decode a blkptr with, from its
blk_propbyteorder bit — used when a blkptr is read from a block whose endianness the caller does not already know. Reads the prop word both ways; the one whose byteorder bit is self-consistent with a plausible level/type is preferred, but for the single-endian pools P1 targets the caller passes the pool endian directly, so this helper is a convenience for standalone blkptr bytes. - dsl_
dataset_ bp - The
ds_bpblock pointer from a DSL dataset dnode’s bonus (dsl_dataset_phys_t.ds_bp) — the pointer to that dataset’s objset. - dsl_
dataset_ prev_ snap - The previous-snapshot object id from a DSL dataset dnode’s bonus
(
dsl_dataset_phys_t.ds_prev_snap_obj) — the older snapshot dataset in this dataset’s snapshot chain, or0when there is none (the origin). - dsl_
dir_ head_ dataset - The head dataset object id from a DSL directory dnode’s bonus
(
dsl_dir_phys_t.dd_head_dataset_obj). - label_
offsets - The byte offsets of the four vdev labels on a vdev of
vdev_sizebytes. - mos_
dnode - Resolve
object_idto itsdnode_phys_twithinobjset. - nvlist_
parse - Parse a packed XDR nvlist config from a buffer beginning with the 4-byte
packed header. Convenience re-export of the crate-private
nvlist::parse. - parse_
sa_ layouts - Parse the SA attribute layouts (
LAYOUTS) fat-ZAP into anSaLayouts. Each entry’s name is the layout number (decimal string) and its value is an array of big-endian u16 attribute ids. - parse_
sa_ registry - Parse the SA attribute registration (
REGISTRY) micro-ZAP into anSaRegistry. Each entry’s u64 value packs[length:bswap:id](ATTR_LENGTH = bits[24..40),ATTR_BSWAP = bits[16..24),ATTR_NUM = bits[0..16)). - read_
block - Read the block a
bppoints at from the raw vdevimage. - read_
dnode_ data - Read logical block
blkidof the object described bydnode, following thedn_nlevelsindirect-block tree. - read_
zap_ object - Read a ZAP object’s entire logical data by concatenating every L0 block of
dnode(blocks0..=dn_maxblkid), so a multi-block fat-ZAP is presented as one contiguous buffer tozap_list/zap_lookup. - sa_
attr_ bytes - Locate one System Attribute’s bytes within an SA buffer, by registry name.
- uberblock_
parse - Parse a single uberblock slot, detecting byte order from the magic. Returns
Nonefor a slot that is not a live uberblock. Convenience re-export ofuberblock::Uberblock::parse. - zap_
list - List every
(name, value)entry of a ZAP object, given its whole-object data (one micro-ZAP block, or a concatenated fat-ZAP asread_zap_objectreturns). Handles both micro- and fat-ZAP, detected from the block-type word. - zap_
list_ arrays - List every
(name, value_bytes)entry of a fat-ZAP object, preserving the full byte payload of each value rather than folding it to au64. - zap_
lookup - Look up
namein a ZAP object’s data, returning its raw value if present. Handles both micro- and fat-ZAP (detected from the block-type word). - zpl_
attrs - Decode object
object_id’s ZPL metadata intoZplAttrs, dispatching on the dnode’s bonus type:DMU_OT_SA(44) → SA decode viaregistry/layouts;DMU_OT_ZNODE(17) → legacyznode_phys_t. ReturnsNoneif the object is absent, its bonus type is neither, or the bonus does not decode. - zpl_
list_ dir - List a ZPL directory object
dir_obj_idwithin objsetzplas(name, object_id)pairs, masking theZFS_DIRENT_TYPEbits off each value. - zpl_
lookup - Resolve an absolute path (
/dir/sub/file) within a ZPL objset to its target object id andZplAttrs, descending the directory tree from the root. - zpl_
master_ root - The root directory’s object id, read from a ZPL objset’s master node
(object 1)
ROOTentry. ReturnsNoneif the master node or theROOTentry is absent. - zpl_
objset - Resolve a dataset’s ZPL
objset_phys_tfrom the MOS, walking MOS object directory →root_dataset(DSL dir) →dd_head_dataset_obj(DSL dataset) →ds_bp→ the ZPL objset block. - zpl_
read_ file - Read object
object_id’s file content, truncated to its SA/znode logical size. - zpl_
read_ file_ with - Read object
object_id’s file content: concatenate its data blocks0..=dn_maxblkidand truncate to the object’s logical size. - zpl_
read_ path - Resolve
path(seezpl_lookup) and read the target file’s content. - zpl_
read_ symlink - Read the target of symlink object
object_idwhere OpenZFS keeps it. - zpl_
root_ dir - The root directory’s dnode within a ZPL objset (the object named
ROOTby the master node). ReturnsNoneif the master node, theROOTentry, or the root object cannot be resolved. - zpl_
sa_ context - Build the SA decoding context for a ZPL objset: parse the
REGISTRYandLAYOUTSZAPs reachable from the master node’sSA_ATTRSentry.