Skip to main content

Crate zfs_core

Crate zfs_core 

Source
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.
BlkptrSummary
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.
ObjsetPhys
A parsed objset_phys_t.
SaAttrDesc
One SA attribute’s registration: its numeric id, its byte length, and its byteswap class — decoded from a REGISTRY ZAP 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.
VdevLabel
A parsed vdev label: its config nvlist and its active uberblock.
VdevTree
The P0 subset of the nested vdev_tree config.
ZplAttrs
Decoded ZPL file/directory metadata — the superset the SA layout carries (and the legacy znode_phys_t provides). Timestamps are (seconds, nanoseconds).

Enums§

DmuType
A DMU object type. Use DmuType::raw for the on-disk numeric value (e.g. DmuType::Objset.raw() == 11); the data-carrying DmuType::Other variant 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 legacy znode_phys_t bonus.
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_MAXBLOCKSIZE with headroom). A blkptr claiming more is an allocation bomb.
MAX_INDIRECT_LEVELS
Maximum indirect-block-tree depth to follow (dn_nlevels never 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 LAYOUTS entry name (→ the attribute-layouts ZAP).
SA_MAGIC
SA_MAGIC — the sa_hdr_phys_t.sa_magic value.
SA_REGISTRY_NAME
The SA master object’s REGISTRY entry 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 is max(1 KiB, 2^ashift), so a ashift == 12 pool 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’s zap_block_type.
ZBT_LEAF
ZBT_LEAF — a fat-ZAP leaf block’s l_block_type.
ZBT_MICRO
ZBT_MICRO — a micro-ZAP block’s mz_block_type.
ZFS_MAXPATHLEN
MAXPATHLEN on Linux (include/os/linux/spl/sys/sysmacros.h): zfs_symlink refuses a longer target with ENAMETOOLONG.
ZNODE_PHYS_SIZE
The size of the legacy znode_phys_t bonus.
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 txg and its slot index, or None if no slot holds a valid uberblock.
decode_sa_bonus
Decode a DMU_OT_SA bonus into ZplAttrs, resolving attribute sizes/ids via the registry and the packed order via the layout.
decode_znode_phys
Decode a legacy znode_phys_t bonus (bonustype DMU_OT_ZNODE = 17) into ZplAttrs. Returns None if the bonus is shorter than the 264-byte struct.
detect_blkptr_endian
Detect the byte order to decode a blkptr with, from its blk_prop byteorder 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_bp block 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, or 0 when 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_size bytes.
mos_dnode
Resolve object_id to its dnode_phys_t within objset.
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 an SaLayouts. 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 an SaRegistry. 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 bp points at from the raw vdev image.
read_dnode_data
Read logical block blkid of the object described by dnode, following the dn_nlevels indirect-block tree.
read_zap_object
Read a ZAP object’s entire logical data by concatenating every L0 block of dnode (blocks 0..=dn_maxblkid), so a multi-block fat-ZAP is presented as one contiguous buffer to zap_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 None for a slot that is not a live uberblock. Convenience re-export of uberblock::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 as read_zap_object returns). 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 a u64.
zap_lookup
Look up name in 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 into ZplAttrs, dispatching on the dnode’s bonus type: DMU_OT_SA (44) → SA decode via registry/layouts; DMU_OT_ZNODE (17) → legacy znode_phys_t. Returns None if 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_id within objset zpl as (name, object_id) pairs, masking the ZFS_DIRENT_TYPE bits off each value.
zpl_lookup
Resolve an absolute path (/dir/sub/file) within a ZPL objset to its target object id and ZplAttrs, 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) ROOT entry. Returns None if the master node or the ROOT entry is absent.
zpl_objset
Resolve a dataset’s ZPL objset_phys_t from 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 blocks 0..=dn_maxblkid and truncate to the object’s logical size.
zpl_read_path
Resolve path (see zpl_lookup) and read the target file’s content.
zpl_read_symlink
Read the target of symlink object object_id where OpenZFS keeps it.
zpl_root_dir
The root directory’s dnode within a ZPL objset (the object named ROOT by the master node). Returns None if the master node, the ROOT entry, or the root object cannot be resolved.
zpl_sa_context
Build the SA decoding context for a ZPL objset: parse the REGISTRY and LAYOUTS ZAPs reachable from the master node’s SA_ATTRS entry.