docs: document typed ini configuration redesign
This commit is contained in:
Mario Fetka
136
REDESIGN.md
136
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,
|
||||
|
||||
Reference in New Issue
Block a user