# 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).

![NaxOS OpenZFS Storage Management](../images/storage-management.jpg)

### 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:
```nix
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.