From be98bf0a4c9cd7537f549b1bee14decc527ab523 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 07:52:44 +0000 Subject: [PATCH] docs: document typed ini configuration redesign --- REDESIGN.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/REDESIGN.md b/REDESIGN.md index f0b6350..57195eb 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -1012,6 +1012,142 @@ This keeps the future NetWare 4.x work aligned with the provider/process split: `nwdirectory`, `nwnds`, and `nwbind` may be separate processes or modules, but they should not be separate sources of truth for identity and directory data. +## Configuration redesign and future typed INI files + +The current `nw.ini`/`nwserv.conf` format is historically user-editable, but it +is not an INI file in the usual named-section/key-value sense. It is a numbered +record format: + +```text +1 SYS /var/local/nwe/SYS kt 711 600 +2 MARS +3 auto +51 1 +52 .recycle .salvage +``` + +`opt/nw.ini.hook.cmake` is an install-time template for that legacy format. The +SMARTHOOK comments make selected numeric sections replaceable by tooling, but the +runtime parser still reads numbered records through helpers such as +`get_ini_entry()` and `get_ini_int()`. That format should remain supported for +compatibility, but it should not be the long-term administrator-facing format for +NetWare 4.x, directory, TLS, transport, and provider settings. + +The future configuration direction should be a real named INI file, backed by a +schema. JSON is useful for machine metadata, but it is not a good primary +administrator-facing configuration format for mars-nwe. A named INI layout is +closer to the existing text configuration style while making new subsystems much +clearer: + +```ini +[server] +name = MARS +compatibility = netware3 +internal_network = auto + +[volume.SYS] +path = /var/local/nwe/SYS +flags = kt +umask_dir = 0711 +umask_file = 0600 + +[transport.ipx] +enabled = true +internal_network = auto + +[transport.tcp] +enabled = false +listen = 0.0.0.0:524 + +[bindery] +enabled = true +backend = legacy + +[directory] +enabled = false +store = libflaim +path = /var/lib/mars-nwe/directory + +[ldap] +enabled = false +listen = 0.0.0.0:389 +ldaps_listen = 0.0.0.0:636 + +[ldap.tls] +enabled = false +provider = wolfssl +cert = /etc/mars-nwe/ldap.crt +key = /etc/mars-nwe/ldap.key + +[nds] +enabled = false +provider = nwnds + +[provider-ipc] +mode = local +local_dir = /run/mars-nwe +``` + +The exact keys are placeholders, but the grouping is important: + +- server identity and compatibility mode belong under `[server]`; +- volumes become repeatable named sections such as `[volume.SYS]`; +- transport settings are separate from NCP provider settings; +- Bindery, Directory, LDAP, and NDS configuration are distinct layers; +- TLS settings are attached to the protocol edge that uses them; +- internal provider IPC settings stay separate from client-facing transport. + +For NetWare 4.x this is especially important. Do not overload old numeric +sections with directory, NDS, LDAP, TLS, libflaim, and provider-IPC options. A +numbered line such as `83 ...` gives no useful hint to an administrator and makes +future `nwsetup` edits fragile. New 4.x-era features should be designed in the +named INI schema first and only mapped to legacy numeric entries where backwards +compatibility requires it. + +The migration path should be: + +1. keep reading the legacy numbered config as today; +2. add a typed config model in code (`NwConfig`) whose fields are not tied to + either file syntax; +3. load legacy numbered config into that model; +4. load the new named INI format into the same model; +5. make `nwsetup` write the new named INI format atomically; +6. optionally provide import/export from legacy numeric config to named INI; +7. only later consider generating legacy numeric sections from the typed model + for older tools. + +The parser/writer choice should be made with write support in mind. A read-only +INI library is enough for daemons, but not enough for `nwsetup` or a future web +configuration editor. The writer should be schema-driven and should write a +canonical file atomically rather than trying to preserve every arbitrary comment +in-place. Comments and examples can come from the schema/template, similar in +spirit to the current `nw.ini.hook.cmake`, but with named keys instead of numeric +records. + +Practical library guidance: + +- a read-only parser may be acceptable for runtime processes; +- `nwsetup` needs read/write/delete or a small project-owned writer; +- comment-preserving round trips should not be required for correctness; +- generated files should use stable ordering so diffs are readable; +- secrets must not be emitted accidentally into world-readable configs; +- writes should use temporary files plus rename, with restrictive permissions. + +Candidate approaches: + +```text +runtime read path: + nw_config_load() -> parse legacy numeric and/or named INI -> NwConfig + +setup/write path: + nwsetup -> NwConfig -> schema-driven canonical INI writer -> atomic rename +``` + +This keeps the old `nw.ini` compatibility path alive while giving NetWare 4.x, +`nwdirectory`, `nwnds`, libflaim-backed storage, wolfSSL TLS, and future +transport settings a configuration format that can be understood and edited by a +human. + ## Transport split for future TCP/IP support Future TCP/IP support should be introduced as a transport code/library split,