naxos-docs/docs/architecture/storage-engine.md

OpenZFS Storage Engine & Migration Architecture

OpenZFS Primitives in NaxOS

NaxOS leverages upstream OpenZFS on Linux with specific architectural choices optimized for mixed workloads (streaming media, small-file databases, photo indexing, and Apple Time Machine backups).

1. Default Pool Parameters

When creating pools through NaxOS, the engine enforces optimal pool attributes:

• ashift=12: 4096-byte sector alignment to eliminate write amplification on modern Advanced Format HDDs and NVMe SSDs.
• xattr=sa: System-attribute storage for extended attributes, drastically improving Samba and POSIX ACL performance.
• acltype=posixacl: POSIX Access Control Lists enabling granular multi-user permissions.
• compression=lz4: Ultra-low overhead, transparent compression enabled globally on pools, with dataset-level overrides for zstd on cold backups and photo datasets.

2. Record Size Strategy

NaxOS tunes dataset record sizes based on application type:

• Media Datasets (tank/media): recordsize=1M (maximizing sequential read throughput and reducing metadata overhead).
• General Storage (tank/backup): recordsize=128K (default ZFS balance).
• Databases & Containers (tank/container): recordsize=16K or 128K.

3. ZFS ARC Max Management

To prevent OpenZFS from consuming all host RAM and starving machine learning workloads (such as Immich facial recognition models), NaxOS enforces a declarative ARC limit:

boot.kernelParams = [ "zfs.zfs_arc_max=4294967296" ]; # 4 GiB

---

Safe Foreign Pool Import Architecture

A key tenet of NaxOS is zero data loss:

When importing pools from existing setups (e.g. TrueNAS or nixos-lukas):

1. The pool is initially inspected with zpool import -N -f <pool> (-N instructs ZFS not to mount any datasets).
2. The dataset tree is scanned and properties are parsed without modifying data.
3. Datasets are adopted declaratively into services.naxos.storage.importExistingPools.
4. Original permissions and POSIX ACLs are preserved.