39 lines
2.1 KiB
Markdown
39 lines
2.1 KiB
Markdown
# 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:
|
|
```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.
|