From 2f75b77dedf36de15ed6fa9aff0f1f42503af81c Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 08:06:32 +0000 Subject: [PATCH] docs: document config password recovery redesign --- REDESIGN.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 5 deletions(-) diff --git a/REDESIGN.md b/REDESIGN.md index 57195eb..bb32afa 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -986,6 +986,61 @@ Examples of setup-owned work: the local bootstrap path should avoid requiring a running LDAP server and should not make LDAP the canonical internal representation. +### Admin, Supervisor, and directory password bootstrap/recovery + +The future typed INI must not carry reusable plaintext passwords for Admin, +Supervisor, LDAP, NDS, Bindery, or provider IPC credentials. The old legacy +pattern of placing a cleartext Supervisor password in the config and restarting +the server so the password is reset should be treated as a compatibility behavior +for old Bindery-only setups, not as the NetWare 4.x/directory design. + +Initial password creation belongs to `nwsetup`: + +```text +first setup: + nwsetup asks interactively for the initial Admin/Supervisor password + nwsetup calls libdirectory authentication primitives + libdirectory stores only password verifiers/hashes in the libflaim-backed store + nw.ini records object names, tree/context, and paths, but not the password +``` + +Planned password changes should also be explicit setup/admin operations, for +example conceptually: + +```text +nwsetup passwd supervisor +nwsetup directory set-password cn=admin,o=mars +``` + +Those commands can authenticate using the current password, local root/admin +rights, or a documented recovery mode. They should update the directory store +directly through `libdirectory`, not by writing a plaintext key into the INI and +waiting for a daemon restart. + +Emergency recovery must be possible, but it should be one-shot and local. The +safe design is an explicit recovery command or recovery token/file, with strict +permissions and exclusive store access: + +```text +nwsetup recovery reset-admin-password + requires local root or the configured mars-nwe admin user + requires the server to be stopped or the store to be exclusively locked + updates password verifier/hash through libdirectory + logs the recovery event without logging the new secret + consumes or removes any one-shot recovery token/file +``` + +If a recovery file mechanism is added, it should live outside the main admin INI, +be root-owned, mode `0600`, and be deleted or renamed after successful use. The +main INI may point to a recovery directory or policy, but it should not contain a +standing plaintext reset password. + +Legacy compatibility can remain explicit and deprecated, for example as a +Bindery-only option whose comments warn that it is not used by directory/NDS +mode. Migration tools should warn when they find old cleartext reset settings +and should convert them into an interactive `nwsetup` password operation rather +than copying the secret into the new documented INI. + Kerberos should not be part of this initial design. Classic NetWare 4.x/NDS compatibility should focus on native NDS-style authentication and directory semantics. If a later eDirectory/NMAS compatibility effort ever needs Kerberos, @@ -1118,11 +1173,31 @@ The migration path should be: 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. +configuration editor. The writer should be schema-driven and should write +atomically, but the generated INI is also administrator documentation. It must +not be rewritten into an undocumented minimal key/value dump. + +The shipped default file should be a documented INI, not only a machine config. +Comments should explain the section purpose, defaults, safe values, compatibility +notes, and examples. `nwsetup` should therefore prefer one of these strategies: + +```text +comment-preserving edit: + read existing file as text + replace only known key value lines + preserve surrounding comments, unknown keys, and unknown sections + insert missing keys near their documented section when possible + +or template regeneration: + regenerate from a full documented template/schema + include the explanatory comments again + preserve local overrides through the typed NwConfig model +``` + +Do not choose a writer that discards all comments unless `nwsetup` regenerates +from a complete documented template. Losing the documentation comments would be +a regression because the INI is expected to be the primary admin-facing reference +for normal deployments. Practical library guidance: