From b0ea5d2b094f4bfb89b7515fb77434995bc4b380 Mon Sep 17 00:00:00 2001 From: OpenAI Date: Fri, 19 Jun 2026 20:08:48 +0000 Subject: [PATCH] docs: record NSS provider capability direction --- doc/NSS_IMPORT_NOTES.md | 218 ++++++++++++++++++++++++++++++++++++++++ doc/quota/README.md | 22 ++++ tests/afp/README.md | 26 +++++ 3 files changed, 266 insertions(+) diff --git a/doc/NSS_IMPORT_NOTES.md b/doc/NSS_IMPORT_NOTES.md index 6c0b4cb..1eac0aa 100644 --- a/doc/NSS_IMPORT_NOTES.md +++ b/doc/NSS_IMPORT_NOTES.md @@ -101,6 +101,224 @@ choice: Volume ID `1` is therefore reserved even if `_ADMIN` is generated in memory by `nwadminvol`. + +### Current confirmed NSS import baseline + +The local integration baseline after the AFP/Mac import and Unicode userspace +boundary repair is: + +```text +ctest --output-on-failure +73 tests total +73 passed +0 failed +``` + +This includes the `nwnss.*` unit tests, the AFP and salvage ncpfs smokes, and +the live `nwfs.ncpfs.*` metadata, quota and salvage-related smokes. + +### Provider and backend capability model + +The userspace provider split is now a first-class NSS import boundary. The +first decision is only whether a path is backed by a real NSS volume or by an +OtherFS/HostFS tree. Feature-specific code still needs its own probes after +that first decision. + +```text +NSS_VOLUME + real NSS pool/volume/media semantics + future Linux VFS exposure through nwnssmount/FUSE + future block-I/O path through io_uring + NSS metadata/RVD/data-stream/quota/salvage/repair code paths + +OTHERFS_XATTR + normal host filesystem tree + Linux host xattrs and sidecars where required + Netatalk-compatible AFP EAs for AFP/Mac state + Linux quota or NWQUOTA metadata fallback for quota + host recycle/salvage mapping for salvage +``` + +FUSE and io_uring are not alternative providers. They are both part of the +future `NSS_VOLUME` implementation: FUSE is the Linux mount/frontend surface and +io_uring is the asynchronous block-I/O backend below `libnwnss`. + +Do not use provider names such as `FUSE` or `IO_URING` as feature selectors. +Use `NSS_VOLUME` versus `OTHERFS_XATTR`, then let the feature-specific provider +select the right backend. + +The generic NSS capability names should stay NSS-shaped even for OtherFS. A +host filesystem may later map comparable features such as Btrfs/ZFS snapshots +onto NSS snapshot semantics, but only when the behaviour is close enough. For +current XFS/ext4/HostFS work, the useful OtherFS capabilities are limited to +namespace, host xattrs, trustees, effective rights, quota, salvage/purge, +RVD-metadata mirroring where explicitly defined, and named streams where a +backend such as Netatalk EA provides one. + +Recommended provider capability vocabulary: + +```text +NSS_CAP_POOL +NSS_CAP_VOLUME +NSS_CAP_PARTITION +NSS_CAP_RAID +NSS_CAP_SNAPSHOT +NSS_CAP_ADMINFS +NSS_CAP_MANAGE_API +NSS_CAP_NAMESPACE +NSS_CAP_DATA_STREAMS +NSS_CAP_RVD_METADATA +NSS_CAP_EXTATTR +NSS_CAP_TRUSTEES +NSS_CAP_EFFECTIVE_RIGHTS +NSS_CAP_QUOTA +NSS_CAP_SALVAGE +NSS_CAP_PURGE +NSS_CAP_REPAIR_VERIFY +NSS_CAP_COMPRESSION +NSS_CAP_ENCRYPTION +``` + +For `NSS_VOLUME`, the eventual target is the full NSS stack: pools, volumes, +partitions, RAID, snapshots, AdminFS/manage APIs, namespaces, data streams, +RVD/extended metadata, trustees/effective rights, quota, salvage/purge, +repair/verify/RAV, compression and encryption flags. For `OTHERFS_XATTR`, set +only the subset that the concrete host backend can really emulate. + +The first NSS-volume path probe can use the original NSS LSA superblock magic +when a real Linux NSS filesystem is mounted: + +```text +statfs(path).f_type == LSA_MAGIC_SB -> NSS_VOLUME +otherwise -> OTHERFS_XATTR +``` + +This is only the coarse provider-kind probe. Quota still needs Linux +`quotactl()` capability probes, AFP still needs Netatalk-EA versus NSS +RVD/stream dispatch, salvage still needs NSS salvage versus host recycle +storage, and xattr still needs NSS extended metadata versus Linux host-xattr +storage. + +### AFP/Mac metadata provider boundary + +Original NSS does not store AFP/Mac state in a Linux host xattr and it does not +extend the LSA `netware.metadata` xattr for AFP. In NSS the Finder/Mac metadata +belongs to root variable data: + +```text +RVD_MAC_META_DATA + zMacInfo_s + PackedMacInfo_s + MACNS_PackRootVariableData() + MACNS_UnpackRootVariableData() +``` + +The resource fork is a named data stream with the NSS stream name: + +```text +MAC_RF +``` + +For a real `NSS_VOLUME`, AFP must therefore use NSS RVD metadata and the +`MAC_RF` stream. It must not read or write Netatalk EAs. + +For `OTHERFS_XATTR`, there is no NSS-on-disk-compatible host representation for +RVD metadata. The chosen compatibility backend is Netatalk `adouble:ea`, stored +on the same host object that owns the AFP state: + +```text +org.netatalk.Metadata +org.netatalk.ResourceFork +``` + +Do not invent `user.netware.afp.*` xattrs and do not pack AFP into the existing +`netware.metadata` mirror. The Netatalk EAs are an OtherFS provider +representation only. The library API should expose NSS semantics (`zMacInfo_s`, +`RVD_MAC_META_DATA`, `MAC_RF`) and dispatch through the provider. + +### NSS management and volume creation scope + +`NSS_VOLUME` also covers the management side of NSS, not only mounted file I/O. +The NSS sources include pool, volume and management paths that should guide +future `nwnssmu`, `nwnssmount`, and AdminFS work. + +Relevant source groups: + +```text +public_core/manage/ + managePool.c + manageVolume.c + managePartition.c + manageFile.c + manageAFP.c + manageLinux.c + manageServer.c + manageUserSpaceRestr.c + +public_core/zlss/ + zlssLogicalVolume.c + zfsPool.c + zfsVol.c + zfsSuperBlk.c + zlssDev.c + repair*.c + zlssIOPerformance.c + +public_core/lsa/ + lsaSuper.c + lsaSuperPool.c + lsaSuperVol.c + lsaXattr.c + lsaNSSKR.c + +public_core/nwraid/ + RAID 0/1/5 and device-manager integration references + +public_core/admindrv/ + Admin-driver/AdminFS reference plumbing +``` + +Pool creation exists in the Linux management layer, historically through +EVMS/NSSFS plugin paths such as `LNXPOOL_CreatePool()`. That path is a useful +semantic/dependency reference but should not become a runtime EVMS requirement. +Volume creation is closer to the real NSS/ZLSS core through management and +logical-volume functions such as `CreateVolumeInPool()` and the +`ZLSSVOL_LV_Create*()` family. Future `nwnssmu pool create` and +`nwnssmu volume create` should build on those NSS semantics while replacing the +old Linux/EVMS/block-device boundary with the planned io_uring storage boundary. + +Planned tool split: + +```text +nwnssmount + FUSE mount frontend for real NSS volumes. + Provides Linux VFS access to NSS namespace, files, xattrs, RVD metadata, + data streams including MAC_RF, trustees/effective rights, quota and salvage. + +nwnssmu + NSSMU-like management TUI/CLI for devices, partitions, pools, volumes, + RAID, snapshots, repair/verify and volume attributes. + +nwnssrights + RIGHTS-like trustee, inherited-rights and effective-rights tool. + +nwnssattrib + ATTRIB-like NSS file/directory attribute tool. + +nwnssquota + nssquota-like user, directory and volume quota management frontend. + +nwnssrav + RAVSUI/RAVVIEW-like repair/analyze/verify frontend. + +nwnsscon / AdminFS + NSSCON/setcmd/AdminFS-style runtime and management views. +``` + +OtherFS providers must report unavailable for native NSS pool/volume/RAID/AdminFS +management unless a future host filesystem backend deliberately maps a comparable +feature onto the NSS capability model. + ### Xattr and metadata adaptation NSS xattr and metadata functions are useful because they encode NetWare/NSS diff --git a/doc/quota/README.md b/doc/quota/README.md index 920e4eb..c534a01 100644 --- a/doc/quota/README.md +++ b/doc/quota/README.md @@ -70,6 +70,28 @@ Migration rule: - keep the later real NSS-volume quota provider inactive in default userspace until FUSE/io_uring storage boundaries exist. +## Provider boundary + +Quota follows the same provider rule as AFP, xattr and salvage. The first +provider decision is `NSS_VOLUME` versus `OTHERFS_XATTR`; quota-specific +capability probes happen afterwards. + +```text +NSS_VOLUME + future real NSS quota structures and volume quota views + +OTHERFS_XATTR + Linux USRQUOTA when available + Linux PRJQUOTA for directory quota when available + NWQUOTA metadata fallback when Linux quota is unavailable or only a restore + mirror is present +``` + +Do not mix SYS/NWQUOTA semantics with the QUOTA/Linux-quota semantics in the +server path. The live smokes deliberately keep them separate: SYS exercises +NWQUOTA/metadata quota, while the QUOTA test volume exercises Linux user/project +quota. + ## Backend model ### Linuxquota diff --git a/tests/afp/README.md b/tests/afp/README.md index 4e20208..8b80d79 100644 --- a/tests/afp/README.md +++ b/tests/afp/README.md @@ -25,6 +25,32 @@ AFP handlers must keep NetWare semantics on mars_nwe core paths: Resource forks remain unsupported. AFP resource-fork requests should return the documented completion code instead of inventing a parallel storage backend. +## libnwnss AFP provider direction + +The current AFP smoke tests document the legacy mars_nwe AFP compatibility +endpoints. They are not the long-term storage model for `libnwnss`. When AFP +state moves behind `libnwnss`, the provider split must be explicit: + +```text +NSS_VOLUME + Finder/Mac metadata: RVD_MAC_META_DATA / zMacInfo_s / PackedMacInfo_s + resource fork: NSS data stream MAC_RF + +OTHERFS_XATTR + Finder/Mac metadata: Netatalk adouble:ea xattr org.netatalk.Metadata + resource fork: Netatalk adouble:ea xattr org.netatalk.ResourceFork +``` + +Do not add a `user.netware.afp.*` xattr family and do not extend the existing +`netware.metadata` mirror with AFP state. The Netatalk EAs are an OtherFS +provider representation on the same file or directory whose AFP state is being +queried. A real NSS volume must use NSS RVD metadata and the `MAC_RF` stream +instead. + +Future `nwnss.afp` unit tests should therefore cover both sides separately: +constant/pack semantics for NSS (`RVD_MAC_META_DATA`, `zMacInfo_s`, `MAC_RF`) +and Netatalk-EA read/write semantics for the OtherFS provider. + ## Endpoint inventory The generated helper remains the source of truth for fresh checks: