docs: record NSS provider capability direction
This commit is contained in:
OpenAI
Mario Fetka
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user