DirectoryServices plan: document account tools (§5.4) and Mac home-path translation (§5.5)

§5.4: split-by-store disposition of the FreeBSD account tools (keep pw/vipw/
pwd_mkdb/chpass/passwd for system accounts; remove adduser/rmuser; dscli for
directory users). §5.5: NFSHomeDirectory is a path not a protocol; the /Local
convention doesn't survive to a Mac, so the LDAP bridge rewrites the home into
macOS's namespace per client.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pkgdemon

nextbsd-directoryservices-plan.html

@@ -319,6 +319,31 @@ <h3>5.2 Name service — nsswitch, not Apple libinfo</h3>
 <h3>5.3 Kerberos: MIT (shipped) vs Heimdal (Apple)</h3>
 <p>NextBSD ships <strong>MIT krb5 1.22.1</strong>; Apple's directory-Kerberos stack is <strong>Heimdal</strong>-coupled (LKDC, <code>hdb</code>, the Password Server replica protocol). Impact: <strong>non-issue for <code>;ShadowHash;</code> local login</strong> (no KDC involved — the whole v0.1 case); <strong>fine for plain <code>;Kerberosv5;</code></strong> against any RFC-4120 KDC (link MIT <code>libkrb5</code>, call <code>krb5_get_init_creds_password</code>); <strong>a hard blocker only for Apple LKDC / Password Server SSO</strong> (Heimdal-only) — which is deferred anyway. If ever needed, add FreeBSD's Heimdal port <em>beside</em> MIT for the daemon only (keep MIT's SONAME for curl/git).</p>
 
+<h3>5.4 FreeBSD account-management tools</h3>
+<p>The principle is <strong>split by store</strong>: system/service accounts stay in <code>/etc/master.passwd</code> (the flat-file fallback), while directory/human accounts live in the directory (plists), managed by <code>dscli</code>/<code>directoryservicesd</code>. So each base account tool is keep / remove / route depending on which store it writes. The actual <em>removals</em> are narrow — only the human-account convenience layer (<code>adduser</code>/<code>rmuser</code>). The low-level flat-file tools stay, because system/service accounts still live in <code>master.passwd</code> and the base + ports depend on them.</p>
+<div class="tbl"><table>
+<tr><th>Tool</th><th>Disposition</th><th>Why</th></tr>
+<tr><td><code>pw</code></td><td><strong>KEEP</strong></td><td>Load-bearing — pkg/ports install scripts create service accounts with <code>pw useradd -n _foo</code>. Remove it and package installs break. Writes <code>/etc/master.passwd</code> (system/service accounts = correct target). Just not the tool for human users.</td></tr>
+<tr><td><code>adduser</code> / <code>rmuser</code></td><td><strong>REMOVE</strong></td><td>Interactive wrappers around <code>pw</code> that create human accounts in the flat file — the wrong store in this model, and a confusing second path. Replaced by <code>dscli user add</code> / <code>dscli user delete</code>.</td></tr>
+<tr><td><code>/etc/adduser.conf</code>, <code>/etc/adduser.msg</code></td><td><strong>REMOVE</strong></td><td>Config for <code>adduser</code>; goes with it.</td></tr>
+<tr><td><code>chpass</code> / <code>chfn</code> / <code>chsh</code></td><td><strong>KEEP</strong> (system) / route (directory)</td><td>Edit <code>master.passwd</code> gecos/shell for system accounts. A directory user changes those via <code>dscli edit</code>, not these.</td></tr>
+<tr><td><code>passwd</code>(1)</td><td><strong>KEEP</strong> (system) / route (directory)</td><td>For system accounts, stock <code>passwd</code> → <code>master.passwd</code>. For a directory user it must hit the daemon — either <code>dscli passwd</code>, or the <code>pam.d/passwd</code> stack routes them through <code>pam_directoryservices</code>.</td></tr>
+<tr><td><code>vipw</code>, <code>pwd_mkdb</code></td><td><strong>KEEP</strong></td><td>Low-level <code>master.passwd</code> edit / db rebuild — system accounts only.</td></tr>
+</table></div>
+<div class="note warn"><span class="lbl">Do not remove</span> <code>pw</code> — it is the single most load-bearing account tool for a FreeBSD-derived base; every service account a package creates goes through it.</div>
+<p class="sub" style="margin-top:10px">These tools come from the FreeBSD base closure via <code>nextbsd-freebsd-compat</code>; the exact in-closure set and the ports <code>USES=</code> that depend on <code>pw</code> should be verified against the live srclist before the removals land. <code>dscli</code> vs the Apple <code>dscl</code> naming is an open unification question.</p>
+
+<h3>5.5 Serving macOS clients — home-path translation</h3>
+<p>If a Mac binds to the (future, deferred) LDAP front-end, it <em>authenticates</em> fine, but its home must be presented in <strong>macOS's namespace</strong>, not NextBSD's <code>/Local</code> convention. A Mac is not a NextBSD client: it has <strong>no <code>/Local</code> domain</strong>, doesn't run <code>directoryservicesd</code>, and doesn't NFS-mount <code>/Local</code> as <code>/Network</code>. Hand a Mac <code>NFSHomeDirectory: /Local/Users/jmaloney</code> and it logs in with a <strong>broken/missing home</strong> — the path is meaningless there. So the plist→LDAP bridge must <strong>rewrite</strong> the home per client; the raw <code>/Local</code> path never reaches a Mac.</p>
+<div class="note warn"><span class="lbl">Gotcha — <code>NFSHomeDirectory</code> is a path, not a protocol</span> Despite the name, <code>NFSHomeDirectory</code> (native <code>homeDirectory</code>) is just the local POSIX home <em>path</em> (what <code>$HOME</code>/<code>pw_dir</code> becomes) — the "NFS" is vestigial. The mount <strong>protocol</strong> comes from the separate <code>HomeDirectory</code> attribute (native <code>apple-user-homeurl</code>), whose URL scheme selects the transport: <code>afp://</code> / <code>nfs://</code> / <code>smb://</code>. <strong>No URL at all → local home, nothing mounts.</strong> So a home can sit at an <code>NFSHomeDirectory</code> path yet mount over AFP, or not mount at all.</div>
+<div class="tbl"><table>
+<tr><th>Client</th><th><code>NFSHomeDirectory</code> (path)</th><th><code>HomeDirectory</code> URL (protocol)</th><th>Result</th></tr>
+<tr><td><strong>NextBSD</strong> (<code>directoryservicesd</code>)</td><td><code>/Local/Users/jmaloney</code> (→ <code>/Network/Users/…</code> on a client)</td><td>—</td><td>Gershwin four-domain convention</td></tr>
+<tr><td><strong>Modern Mac</strong> (recommended)</td><td><code>/Users/jmaloney</code></td><td><em>none</em></td><td><strong>Local home</strong> — centralized login, no network home (the realistic modern pattern)</td></tr>
+<tr><td><strong>Vintage Mac</strong> (network home)</td><td><code>/Network/Servers/nextbsdserver/Users/jmaloney</code></td><td><code>afp://nextbsdserver/Users</code> (or <code>nfs://</code>)</td><td>autofs mounts AFP/NFS home there</td></tr>
+</table></div>
+<p><strong>uid must match:</strong> a network home over NFS/AFP uses AUTH_SYS ownership — if <code>jmaloney</code> is uid 5001 on NextBSD, the Mac must act as uid 5001 (it will, from the directory) or it gets permission-denied on its own home. <span class="u">This section describes the deferred Mac-facing LDAP front-end; it does not affect the NextBSD/Linux plist path.</span></p>
+
 <hr class="sec">
 <h2 id="auth"><span class="num">6</span>AuthenticationAuthority dispatch</h2>
 <p class="sub">The daemon reads each record's authority attribute and routes the credential — the PAM/NSS clients never see this</p>