Skip to main content

zfs_core/
lib.rs

1//! `zfs-core` — a pure-Rust, from-scratch ZFS on-disk reader.
2//!
3//! P0 parses the ZFS bootstrap: the four **vdev labels**, the XDR-encoded
4//! **nvlist config** (pool `version`/`name`/`pool_guid`/`txg` and the nested
5//! `vdev_tree` `ashift`/`asize`), and the **endian-adaptive uberblock array**
6//! (active = highest valid `txg`), exposing the active uberblock's `ub_rootbp`
7//! block pointer to the MOS. Later phases resolve the block-pointer tree,
8//! dnodes, objsets, ZAP, and datasets.
9//!
10//! Import path is `zfs_core` (the bare `zfs` and `zfs-core` crate names are both
11//! taken on crates.io — see the repo README), e.g. `use zfs_core::VdevLabel;`.
12//!
13//! # Safety and robustness
14//!
15//! This crate parses untrusted, attacker-controllable disk images. It is
16//! `#![forbid(unsafe_code)]` and every integer is read through bounds-checked,
17//! endian-adaptive helpers ([`bytes`]) that yield `0`/`None` out of range rather
18//! than panic (the Paranoid Gatekeeper standard). nvlist length/count fields are
19//! capped against allocation bombs.
20
21#![forbid(unsafe_code)]
22#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
23
24mod blkptr;
25pub mod bytes;
26pub mod checksum;
27pub mod compress;
28mod dmu;
29mod dnode;
30mod dsl;
31mod error;
32mod label;
33mod nvlist;
34mod objset;
35mod read;
36mod sa;
37mod uberblock;
38pub mod xattr;
39mod zap;
40mod zpl;
41pub use xattr::{has_unread_spill_xattrs, list_xattrs, Xattr};
42
43#[cfg(feature = "vfs")]
44pub mod vfs;
45
46pub use blkptr::{detect_blkptr_endian, Blkptr, Dva, BOOT_SKEW, BPE_PAYLOAD_SIZE};
47pub use bytes::{Endian, Reader};
48pub use checksum::ChecksumType;
49pub use compress::CompressType;
50pub use dmu::DmuType;
51pub use dnode::{Dnode, BLKPTR_SIZE, DNODE_CORE_SIZE, DNODE_SIZE};
52pub use dsl::{dsl_dataset_bp, dsl_dataset_prev_snap, dsl_dir_head_dataset};
53pub use error::ZfsError;
54pub use label::{
55    active_uberblock, label_offsets, VdevLabel, LABEL_SIZE, NVLIST_OFFSET, NVLIST_SIZE,
56    UBERBLOCK_RING_OFFSET, UBERBLOCK_RING_SIZE, VDEV_BOOT_HEADER_SIZE, VDEV_PAD_SIZE,
57};
58pub use nvlist::{NvList, NvValue, VdevTree};
59pub use objset::{ObjsetPhys, DMU_OST_META, DMU_OST_ZFS};
60pub use read::{
61    mos_dnode, read_block, read_dnode_data, Block, MAX_BLOCK_SIZE, MAX_INDIRECT_LEVELS,
62};
63pub use sa::{
64    decode_sa_bonus, decode_znode_phys, parse_sa_layouts, parse_sa_registry, sa_attr_bytes,
65    SaAttrDesc, SaLayouts, SaRegistry, ZplAttrs, SA_MAGIC, SA_TIME_SIZE, ZNODE_PHYS_SIZE,
66};
67pub use uberblock::{BlkptrSummary, Uberblock, UBERBLOCK_MAGIC, UBERBLOCK_MIN_SHIFT, UB_MMP_MAGIC};
68pub use zap::{
69    read_zap_object, zap_list, zap_list_arrays, zap_lookup, ZAP_LEAF_MAGIC, ZAP_MAGIC, ZBT_HEADER,
70    ZBT_LEAF, ZBT_MICRO,
71};
72pub use zpl::{
73    zpl_attrs, zpl_list_dir, zpl_lookup, zpl_master_root, zpl_objset, zpl_read_file,
74    zpl_read_file_with, zpl_read_path, zpl_read_symlink, zpl_root_dir, zpl_sa_context, DMU_OT_SA,
75    DMU_OT_ZNODE, SA_LAYOUTS_NAME, SA_REGISTRY_NAME, ZFS_MAXPATHLEN, ZPL_DIRENT_OBJ_MASK,
76    ZPL_MASTER_NODE_OBJ, ZPL_ROOT_NAME, ZPL_SA_ATTRS_NAME,
77};
78
79/// Parse a packed XDR nvlist config from a buffer beginning with the 4-byte
80/// packed header. Convenience re-export of the crate-private `nvlist::parse`.
81///
82/// # Errors
83///
84/// See `nvlist::parse` (crate-private).
85pub fn nvlist_parse(data: &[u8]) -> Result<NvList, ZfsError> {
86    nvlist::parse(data)
87}
88
89/// Parse a single uberblock slot, detecting byte order from the magic. Returns
90/// `None` for a slot that is not a live uberblock. Convenience re-export of
91/// [`uberblock::Uberblock::parse`].
92#[must_use]
93pub fn uberblock_parse(slot: &[u8]) -> Option<Uberblock> {
94    Uberblock::parse(slot)
95}