mars-nwe/doc/NSS_USERSPACE_ADAPTATION.md

NSS userspace adaptation boundary

The NSS import is a source and behaviour reference for Mars NWE. The goal is not to recreate the Novell NSS filesystem or its Linux kernel modules in userspace. The goal is to reuse the useful NSS semantics as libraries that Mars NWE can call.

Target semantics

The useful exported behaviour is primarily:

• namespace handling for DOS, LONG/OS2 and later MAC/UNIX/DataStream/EA;
• trustee and rights-management semantics;
• effective-rights calculation;
• extended-attribute and metadata semantics;
• the _ADMIN/AdminVolume view as a Mars-provided in-memory/config-backed userspace volume;
• salvage/compression/repair-related helpers where they expose useful NetWare semantics.

These pieces should become library code owned by Mars NWE integration points, not a standalone NSS volume implementation.

Storage and persistence boundary

NSS code may contain logic for writing metadata, names, trustees or xattrs into an NSS volume. In Mars NWE, that storage backend is different:

• metadata and xattrs should be mapped to the underlying host filesystem, using the existing or future Mars/NWFS xattr layer;
• AdminVolume data should be generated from Mars configuration/runtime state, not stored in a fake NSS disk format;
• namespace and rights functions should operate on Mars volume/file abstractions once the dependency chain is available;
• no Linux kernel module, NSS disk format or hidden NSS volume should become a runtime requirement.

During initial imports, keep NSS files as close to original as practical so the real dependencies are visible. Later integration patches may replace NSS storage hooks with Mars userspace hooks, but those replacements should be explicit and well documented.

Makefile and module-list audit

The NSS Makefile, *Modules.mk and buildtool files are useful as dependency maps. They should be used to identify which sources belong to features such as AdminVolume, namespace, common Beast objects, LSA, cache/runtime support and rights handling.

They are not a build target for Mars NWE. Mars should import only the source files and headers required to expose the desired library behaviour, then wire those pieces into the CMake library targets.

Import strategy

1. Import bottom-up runtime dependencies with original filenames and directory shape where practical.
2. Prefer real NSS implementation files over invented wrappers.
3. Keep public include roots as include/core and include/nwfs; keep NSS subdirectories in include names.
4. Add small CTests for each imported runtime group.
5. When NSS code reaches filesystem persistence, replace that boundary with Mars userspace adapters instead of carrying NSS kernel/disk assumptions forward.
6. Audit already-imported or rewritten Mars files, especially nwfs/lsa, before building higher-level namespace/AdminVolume features on top of them.

AdminVolume direction

_ADMIN should be represented as a Mars NWE userspace/admin service view, not as an NSS disk volume. The NSS sources provide the semantics, object layout and dependency map. Mars provides the backing data and the NCP-facing integration.

The intended runtime shape is:

• nwadminvol owns the generated _ADMIN tree and its Mars/NSS-adapted AdminVolume logic;
• nwconn talks to nwadminvol over IPC when NCP clients access _ADMIN;
• normal Mars/NWFS volumes continue to use the host filesystem plus Mars metadata/xattr adapters;
• _ADMIN is generated from Mars configuration and runtime state, with any required persistence stored in Mars-owned state files, not in an NSS volume image.

The initial integration should keep _ADMIN internal and not expose it over NCP until namespace, metadata, rights and generated-file behaviour are reliable.

Volume numbering is a fixed Novell compatibility rule, not a configuration choice:

• SYS = 0
• _ADMIN = 1
• further configured volumes start at 2

Volume ID 1 is therefore reserved even if _ADMIN is generated in memory by nwadminvol.

Xattr and metadata adaptation

NSS xattr and metadata functions are useful because they encode NetWare/NSS semantics. Their storage backend must be replaced at the Mars boundary.

For normal volumes:

• NSS namespace, rights, effective-rights and metadata code should operate on Mars/NWFS objects;
• xattrs and metadata should be persisted through the host filesystem xattr layer where possible;
• data that does not map cleanly to host xattrs should go through an explicit Mars sidecar/state adapter;
• no hidden NSS volume, NSS disk layout or kernel object should be required.

For _ADMIN:

• files and directories are virtual/generated AdminVolume objects;
• reads should be served from Mars configuration/runtime state;
• writes, if supported, should update Mars configuration/state through explicit handlers;
• the AdminVolume implementation should be usable as a library/service by nwadminvol, not as a mounted filesystem.