ZFS ACL Mapping for SMB: Avoiding Permission Nightmares

A mental model that stops the bleeding

You’re juggling three different permission languages:
Windows ACLs (SMB clients), Samba’s interpretation, and ZFS’s on-disk ACL model. If they disagree, users don’t get a polite warning; they get
Access denied and then your ticket queue becomes a crime scene.

Here’s the sane mental model:

• ZFS stores NFSv4-style ACLs (also called “NFS4 ACLs”) when acltype=nfsv4. These can represent Windows-like ACEs:
  allow/deny, inheritance flags, and rich permissions. This is the best match for SMB.
• POSIX mode bits still exist (rwxrwxrwx), but depending on properties like aclmode and aclinherit,
  they’re either a meaningful gate or a decorative sticker.
• Samba maps SIDs to UNIX IDs. If that mapping changes, the ACL entries still point at the old identity. The ACL didn’t “break”;
  your identity layer did.
• “Share permissions” vs “file permissions”: Samba has share-level restrictions and filesystem-level ACLs. The effective permission is
  the intersection. You can be generous in one and strict in the other, but if you’re strict in both you’ll invent new forms of suffering.

Treat your environment as an identity system first, an ACL system second, and a storage system third. That ordering isn’t philosophical—it’s the
sequence of failures you’ll see in production.

One paraphrased idea from W. Edwards Deming applies: paraphrased idea: a bad system will defeat good people every time. In permissions work,
the “system” is your mapping layer and your inheritance strategy.

Interesting facts & historical context

Some context helps because half of today’s pain is yesterday’s compromise.

1. Windows NT introduced ACLs in the early 1990s with allow/deny semantics and inheritance. The model predates modern Samba
   deployments by decades, which is why Windows clients have strong opinions.
2. POSIX mode bits are older and simpler: user/group/other with rwx. They can’t express “deny,” can’t express per-user exceptions,
   and inheritance is not native.
3. NFSv4 ACLs were designed to be richer than POSIX and closer to Windows semantics, which is why ZFS leans on them for SMB-friendly ACLs.
4. Samba has long used pluggable VFS modules; the ZFS-focused ones exist because generic POSIX ACL handling can’t fully capture ZFS NFSv4 ACL
   semantics without translation.
5. Solaris-era ZFS carried NFSv4 ACLs as a first-class feature. This design choice echoes in OpenZFS today: the ACL model is not an add-on.
6. “Rich ACLs” are not free: they increase metadata work, and operations like recursive inheritance fixes can be expensive. When permissions
   issues happen at scale, it’s rarely one file—it’s the million-file tree behind it.
7. Identity mapping is the hidden dependency: SMB speaks SID; UNIX speaks UID/GID. The SID→UID layer is where “it worked yesterday” is born.
8. ZFS has properties that influence ACL behavior (aclmode, aclinherit, xattr). They are not cosmetic toggles.
   They change what chmod does and whether inheritance behaves like Windows expects.

How ZFS ACLs map to SMB (and where it goes wrong)

1) The two big compatibility choices: POSIX ACLs vs NFSv4 ACLs

If you’re serving SMB to Windows clients and you want Windows-style ACL editing, you want acltype=nfsv4 on the dataset. That gives ZFS an ACL
vocabulary that can represent Windows concepts: inheritance flags, “deny” entries, and fine-grained permissions.

POSIX ACLs (acltype=posixacl) can work for Linux-first environments, but mapping to Windows semantics becomes “approximate.” Approximate is a
polite word. It’s like measuring a data center with a tape measure you printed from memory.

2) Samba’s job: translate Windows security descriptors to filesystem ACLs

A Windows client sends a security descriptor (SDDL-ish under the hood). Samba evaluates whether the client is allowed to set it, then translates it to
filesystem ACL entries. With ZFS NFSv4 ACLs, this translation can be close to direct.

When translation is lossy—because the filesystem can’t represent some Windows flag—Samba does its best and you get “mostly works” until you hit edge cases:
inherited denies, CREATOR OWNER semantics, or weird group membership evaluation.

3) ZFS properties that decide whether you wake up at night

• aclmode: controls how chmod interacts with ACLs. In SMB environments, you often want chmod not to strip ACL intent.
• aclinherit: controls how ACLs are inherited and whether they get rewritten. If this doesn’t align with Windows expectations,
  you’ll see “new files don’t match the folder permissions.”
• xattr: controls how extended attributes are stored (on, sa). This can affect performance and behavior for
  ACL-heavy workloads because ACLs and SMB metadata use xattrs.
• casesensitivity: Windows is case-insensitive by default. Mismatches here cause “ghost duplicates” or confusing access checks.

4) The identity layer: SIDs, UIDs, and the art of not changing them

Windows uses SIDs. ZFS on a UNIX-like system ultimately enforces access using UIDs/GIDs. Samba bridges this via idmap. If your idmap configuration changes
(or your domain trust changes), the same user SID might map to a different UID, or not map at all. Your ACL entries still reference identities, but they no
longer line up with the user on the wire.

This is where “permissions randomly broke” is born. Nothing random happened. You moved the ruler.

Joke #1: Permissions bugs are like glitter—once they’re in the organization, you’ll keep finding them in places nobody remembers touching.

5) “Deny” entries and ordering: why Windows admins can brick access instantly

Windows ACL evaluation includes explicit deny semantics. NFSv4 ACLs can express deny entries too. But you still need to be careful with inherited denies
and “who owns the file” rules. If a folder has a deny on a broad group, inheritance can deliver that deny to files in ways that surprise people who are used
to “we’ll just add an allow.”

Teach your admins: avoid deny unless you’re actively blocking something and you can explain the evaluation order. Most deny entries are policy expressed as
sabotage.

Pick your permission strategy (and commit)

Strategy A: Windows-first (recommended for SMB-heavy environments)

Use ZFS acltype=nfsv4. Manage permissions from Windows (Explorer, icacls) and let Samba write the ACLs. Keep Linux-side chmod/chown away from
datasets that are “Windows-owned,” or at least constrain them to controlled automation that respects ACL properties.

You still need a UNIX owner/group for POSIX compatibility, but treat mode bits as a compatibility view, not the source of truth.

Strategy B: UNIX-first with SMB access (works, but you’ll be translating)

If most administration happens on Linux and Windows clients are consumers, POSIX ACLs can be fine. But you must accept: Windows UI edits may not behave
intuitively. You’ll handle more “why can’t I set this permission” conversations.

Strategy C: Mixed admin from both sides (avoid)

This is how you get permission drift. A Windows admin sets a complex inherited ACL. A Linux admin runs a recursive chmod because “it looked wrong.”
Now you have a dataset full of half-preserved intent and lots of new tickets.

Fast diagnosis playbook

When someone reports “SMB permission denied” or “access changed,” don’t start by clicking around in Explorer. Start with a short sequence that isolates
where the failure is: identity, share restrictions, filesystem ACLs, or inheritance drift.

First: identity and mapping (most common, most catastrophic)

1. Confirm the user’s SID is mapping to the expected UID/GID on the server.
2. Confirm group membership is visible to Samba (token has the right groups).
3. Confirm idmap backend and range haven’t changed.

Second: SMB layer restrictions

1. Check share config: valid users, read only, write list, inherit permissions, veto files, etc.
2. Check whether the client is connecting with the expected account (cached creds are a classic).

Third: filesystem ACL + ZFS properties

1. Inspect the ZFS dataset properties: acltype, aclmode, aclinherit, xattr, casesensitivity.
2. Inspect the file/directory ACL from the server, not just from Windows.
3. Check for explicit deny entries and broken inheritance flags.

Fourth: the “someone ran chmod” investigation

1. Look for recent changes: snapshot diffs, audit logs if enabled, ZFS snapshots, or filesystem mtime patterns.
2. Identify whether ACLs were stripped or rewritten by chmod/chown or by a migration tool.

Practical tasks: commands, outputs, decisions

These are the tasks I actually run when debugging ZFS + SMB ACL mapping. Each task includes a realistic command, an example of what “good” or “bad”
looks like, and the decision you make next.

Task 1: Identify dataset and mountpoint

cr0x@server:~$ zfs list -o name,mountpoint,acltype,aclmode,aclinherit,xattr,casesensitivity tank/share
NAME        MOUNTPOINT    ACLTYPE  ACLMODE    ACLINHERIT  XATTR  CASESENSITIVITY
tank/share  /tank/share   nfsv4    restricted passthrough sa     insensitive

What it means: You’re on NFSv4 ACLs, chmod is restricted from clobbering ACLs, inheritance passes through, xattrs stored in SA, Windows-like case behavior.

Decision: This dataset is plausibly configured for SMB-first ACLs. Proceed to identity and effective ACL checks rather than changing properties.

Task 2: Confirm Samba share definition actually points here

cr0x@server:~$ testparm -s | sed -n '/^\[share\]/,/^\[/{p}'
[share]
	path = /tank/share
	read only = No
	vfs objects = zfsacl streams_xattr
	inherit acls = Yes
	store dos attributes = Yes

What it means: Share path matches the dataset mountpoint. ZFS ACL-aware VFS module is enabled. DOS attributes are stored as xattrs.

Decision: If vfs objects doesn’t include zfsacl (or your platform’s equivalent), mapping may be degraded. Fix Samba config before touching ACLs.

Task 3: See what user Samba thinks you are (and your groups)

cr0x@server:~$ wbinfo --user-sid 'EXAMPLE\alice'
S-1-5-21-111111111-222222222-333333333-1107

What it means: The domain user resolves to a SID. If this fails, you don’t have an ACL problem—you have a directory services problem.

Decision: If this fails, stop and fix domain join / winbind / trust before doing anything else.

Task 4: Map SID to UNIX ID and verify it is stable

cr0x@server:~$ wbinfo --sid-to-uid S-1-5-21-111111111-222222222-333333333-1107
2001107

What it means: Samba maps the SID to UID 2001107. This UID is what filesystem ACL enforcement ultimately cares about.

Decision: If the mapping changed recently, ACL entries referencing the old UID will no longer match. Investigate idmap backend/ranges and whether a different server is issuing different mappings.

Task 5: Check idmap configuration from Samba’s perspective

cr0x@server:~$ testparm -s | grep -E '^idmap config|^security|^realm'
security = ADS
realm = EXAMPLE.COM
idmap config * : backend = tdb
idmap config * : range = 3000-7999
idmap config EXAMPLE : backend = rid
idmap config EXAMPLE : range = 2000000-2999999

What it means: Domain EXAMPLE uses RID mapping into a specific UID range. This tends to be stable if you keep the range consistent across servers.

Decision: Ensure every SMB server accessing the same ZFS dataset uses the same idmap backend and ranges. If not, you’re guaranteed mismatches in on-disk ACL identities.

Task 6: Validate the user token includes expected groups

cr0x@server:~$ wbinfo --user-groups 'EXAMPLE\alice' | head
S-1-5-21-111111111-222222222-333333333-513
S-1-5-21-111111111-222222222-333333333-2201
S-1-5-21-111111111-222222222-333333333-2209

What it means: These are group SIDs in the user’s membership list.

Decision: If a permission should come from a group but the group SID isn’t present, you’re looking at directory group membership, token refresh, nested group visibility, or winbind caching—not ZFS.

Task 7: Inspect ACL on a directory from the server (NFSv4 style)

cr0x@server:~$ ls -V /tank/share/Projects
drwxrwx---+  15 root  domain_users  15 Dec 26 10:12 /tank/share/Projects
                owner@:rwxpDdaARWcCos:fd-----:allow
                group@:rwxpDdaARWcCos:fd-----:allow
             everyone@:------a-R-c--s:fd-----:allow

What it means: The + indicates an ACL beyond mode bits. Inheritance flags (f, d) are present for files/dirs. This looks like a controlled baseline.

Decision: If you don’t see inheritance flags on directories where you expect them, you likely have an inheritance configuration issue or an ACL reset was performed.

Task 8: Confirm the Windows view matches (from Samba tooling)

cr0x@server:~$ smbcacls //localhost/share Projects -U 'EXAMPLE\alice'
REVISION:1
CONTROL:SR|DP
OWNER:EXAMPLE\Administrator
GROUP:EXAMPLE\Domain Users
ACL:EXAMPLE\Domain Admins:ALLOWED/0x0/FULL
ACL:EXAMPLE\Project Team:ALLOWED/0x0/CHANGE
ACL:EXAMPLE\Domain Users:ALLOWED/0x0/READ

What it means: Samba can present a coherent Windows ACL to clients.

Decision: If this differs wildly from ls -V, mapping may be degraded, or you’re looking at different objects (path mismatch), or your VFS module isn’t active.

Task 9: Check effective access for a specific identity (server-side)

cr0x@server:~$ id EXAMPLE\\alice
uid=2001107(alice) gid=2000513(domain_users) groups=2000513(domain_users),2002201(project_team)

cr0x@server:~$ sudo -u '#2001107' test -w /tank/share/Projects && echo WRITABLE || echo NOT_WRITABLE
WRITABLE

What it means: The server believes Alice can write. This isolates “filesystem says yes” from “SMB says no.”

Decision: If filesystem says WRITABLE but SMB clients get denied, look at share-level restrictions, Samba config, oplocks, vetoes, or client auth/cached credentials.

Task 10: Detect whether POSIX mode bits are being used as a gate

cr0x@server:~$ stat -c '%A %a %U %G %n' /tank/share/Projects
drwxrwx--- 770 root domain_users /tank/share/Projects

What it means: Mode bits are 770. If your ACL intends broader access but “other” is 0, some tools may still be constrained depending on ACL settings and evaluation path.

Decision: If Windows users are denied and the mode bits are too restrictive, confirm aclmode and aclinherit behavior and ensure the ACL includes the needed allow entries. Don’t blindly chmod 777.

Task 11: Verify dataset ACL behavior knobs (the ones people forget exist)

cr0x@server:~$ zfs get -H -o property,value acltype,aclmode,aclinherit,xattr tank/share
acltype	nfsv4
aclmode	restricted
aclinherit	passthrough
xattr	sa

What it means: This combo generally preserves Windows intent. restricted prevents chmod from stripping ACLs. passthrough keeps ACEs as-is for inheritance.

Decision: If you see aclmode=discard or aclinherit=discard on an SMB dataset, that’s a permission time bomb. Fix properties, then repair ACLs.

Task 12: Find explicit deny entries that block everything

cr0x@server:~$ ls -V /tank/share/Projects/Quarterly
drwxrwx---+  10 root  domain_users  10 Dec 26 10:18 /tank/share/Projects/Quarterly
                owner@:rwxpDdaARWcCos:fd-----:allow
                group@:rwxpDdaARWcCos:fd-----:allow
        project_team@:------a-R-c--s:fd-----:deny

What it means: There’s an explicit deny for project_team@. If your writers are in that group, they’re blocked regardless of other allows.

Decision: Remove or narrow the deny entry. In most corporate trees, denies are used as “policy,” and policy belongs in group membership, not in an inherited deny grenade.

Task 13: Prove inheritance is (or isn’t) happening for new files

cr0x@server:~$ sudo -u '#2001107' touch /tank/share/Projects/inheritance_test.txt

cr0x@server:~$ ls -V /tank/share/Projects/inheritance_test.txt
-rw-rw----+  1 alice  domain_users  0 Dec 26 10:20 /tank/share/Projects/inheritance_test.txt
                owner@:rw-p--aARWcCos:------:allow
                group@:rw-p--aARWcCos:------:allow
             everyone@:------a-R-c--s:------:allow

What it means: The file inherited a sensible ACL template. If it didn’t, you’d see missing entries or different flags.

Decision: If new files have “wrong” ACLs, check aclinherit, Samba’s inherit acls, and whether Windows is applying a different parent ACL than you think.

Task 14: Detect xattr storage mode and whether you’re paying metadata tax

cr0x@server:~$ zfs get -H -o property,value xattr tank/share
xattr	sa

What it means: xattr=sa stores small xattrs in the dnode “system attributes” area, reducing separate I/O for metadata-heavy SMB workloads.

Decision: If you see poor metadata performance and xattr=on, consider switching to sa for new datasets (changing it on existing datasets may have implications; plan carefully).

Task 15: Validate Samba sees the ZFS ACL module loaded

cr0x@server:~$ smbstatus -b | head -n 15
Samba version 4.19.5
PID     Username     Group        Machine
-------------------------------------------------------------------
4123    alice        domain_users  10.20.30.40 (ipv4:10.20.30.40:52514)

Service      pid     Machine       Connected at
-------------------------------------------------------
share        4123    10.20.30.40    Wed Dec 26 10:21:14 2025

Locked files:
No locked files

What it means: A live SMB session exists; you can correlate client behavior with server logs and filesystem checks.

Decision: If there are no sessions, your issue might be authentication/connectivity, not file permissions. Don’t “fix” ACLs for a login problem.

Task 16: Correlate a client denial with Samba logs (surgical logging)

cr0x@server:~$ sudo smbcontrol all debug 3

cr0x@server:~$ sudo tail -n 30 /var/log/samba/log.smbd
[2025/12/26 10:22:03.114820,  3] smbd/open.c:5963(open_file)
  open_file: unable to open file Projects/Quarterly/report.xlsx. Error was NT_STATUS_ACCESS_DENIED

What it means: Samba is denying at open time. That pushes you toward filesystem ACL evaluation or share restrictions.

Decision: If the denial is consistent for one path, inspect that path’s ACL for explicit deny or ownership issues, and confirm the user token groups.

Three corporate mini-stories from the permission trenches

Mini-story #1: The incident caused by a wrong assumption

A mid-size company migrated from a Windows file server to a shiny ZFS-backed SMB cluster. The plan sounded simple: copy data, keep permissions, cut over.
The project manager asked one question: “Will Windows ACLs just map?” The answer they got was “Yes, mostly.”

On cutover day, the helpdesk got flooded. Some teams could read but not write. Others could write but not rename. A few department heads discovered they
were “owner” on random folders they didn’t recognize, which is a great way to make people nervous about the audit they didn’t request.

The root cause wasn’t ZFS being weird. It was the assumption that identity mapping was universal across servers. The old Windows server had stable SIDs.
The new Samba setup used a different idmap backend on one node than on the others. Same domain, same users, different UID/GID assignments depending on
which SMB node handled the request.

The kicker: the ACLs on disk were “correct” from the perspective of the node that wrote them. They were nonsense from the perspective of the other node.
It looked like random permission failure because it depended on connection placement.

They fixed it by standardizing idmap backend and ranges across the cluster, then rewriting ACL ownership to match stable mappings. Downtime was measured
in hours. The cleanup took weeks because trust was the real casualty.

Mini-story #2: The optimization that backfired

Another org had a performance complaint: listing directories over SMB felt slow during peak hours. Someone looked at graphs, saw metadata pressure, and
decided to “simplify” permissions. The idea: reduce ACL complexity by collapsing many ACEs into broad groups, remove inheritance “noise,” and set
aclinherit=discard to avoid writing extra inherited entries.

For about two days, everyone was delighted. New files were created quickly. Directory listings got snappier. The person who suggested it got a quiet nod
from management, which in corporate life is basically a parade.

Then project teams noticed something: new files weren’t inheriting expected access for cross-functional groups. People fell back to emailing documents
because “the share is broken.” That’s how you know you’re losing: when users invent a workaround that also ruins governance.

The backfire was subtle. By discarding inheritance, they forced permissions to rely on default modes and whatever Samba chose at create-time. The result
was inconsistent ACLs depending on the client app and how it created files. Some applications created temp files with different security descriptors than
final files. Without inheritance to correct them, the oddities stayed.

The fix was not glamorous: revert to inheritance passthrough, use a clean baseline ACL on roots, and improve performance by addressing metadata properly
(xattr strategy, recordsize choices, and not doing recursive ACL surgery at 9 a.m.).

Mini-story #3: The boring but correct practice that saved the day

A large company ran an SMB service over ZFS for years with minimal drama. Their secret wasn’t a magical config. It was discipline: a single “ACL root”
per share, standardized group naming, and a rule that only Windows tools set ACLs on production shares. Linux automation could create directories, but it
was not allowed to chmod recursively. Ever.

One day, a domain restructure happened. New groups, retired groups, nested membership changes. This is the sort of change that usually turns file shares
into abstract art. They expected tickets.

Tickets didn’t arrive. Why? They had a nightly job that validated identity mapping consistency and flagged “unknown SID” entries before humans noticed.
They also snapshot the datasets aggressively and could diff ACL changes when something smelled off.

During the restructure, their monitoring flagged that a subset of group SIDs stopped resolving on one SMB node. They drained connections from that node,
fixed winbind connectivity, and brought it back. Most users never felt it.

It was boring work. The best kind. When someone asked why they bother with “permission health checks,” the answer was simple: because the alternative is
learning about ACLs during an outage, which is like learning to swim during a flood.

Joke #2: The only thing more persistent than a stale SID mapping is the person insisting “permissions are easy” because they once ran chmod -R.

Common mistakes: symptoms → root cause → fix

1) Symptom: “Works on one SMB node, fails on another”

Root cause: Inconsistent idmap backend/ranges across nodes; SID→UID differs per node.

Fix: Standardize idmap config everywhere. Validate with wbinfo --sid-to-uid on each node. Only then consider ACL repair.

2) Symptom: “New files don’t inherit folder permissions”

Root cause: aclinherit=discard/restricted mismatch, or Samba inheritance settings disabled, or parent ACL missing inheritance flags.

Fix: Use aclinherit=passthrough (or your chosen consistent policy), ensure inherit acls = yes, and reset the parent ACL to include proper inheritance flags.

3) Symptom: “Linux chmod fixed it… and then everything broke later”

Root cause: chmod/chown interacted with ACLs via aclmode and stripped or rewritten entries. Or it changed ownership and invalidated the intended ACE targeting.

Fix: Set aclmode=restricted for SMB-first datasets. Stop using recursive chmod on production shares. Reapply ACL baseline from a known-good template.

4) Symptom: “Everyone has read access, but writers can’t rename/delete”

Root cause: Missing directory permissions like delete/rename (or their NFSv4 equivalents). On Windows, delete semantics involve permissions on the parent directory.

Fix: Ensure the writing group has modify/change rights on the directory, not just file write. Validate by testing create, rename, delete from SMB and server-side.

5) Symptom: “Owner shows as an unknown SID in Windows”

Root cause: SID no longer resolves (group deleted/renamed without SID persistence), or server cannot contact domain controllers, or idmap cache is stale/broken.

Fix: Restore directory service connectivity, clear/refresh winbind caches carefully, and avoid rewriting ACLs until identities resolve again.

6) Symptom: “A subset of users get Access Denied after domain changes”

Root cause: Group membership changes not reflected due to token caching, nested group evaluation limits, or winbind not seeing updated memberships.

Fix: Validate group SIDs in the token with wbinfo --user-groups. Adjust directory/Samba settings for nested groups if needed; ask users to reconnect/log off to refresh tokens.

7) Symptom: “Windows says I have Full Control but still denied”

Root cause: Share-level restrictions (valid users, write list), or filesystem path mismatch (symlinks, bind mounts), or an explicit deny higher in the tree.

Fix: Check share config with testparm. Confirm the exact path. Inspect parent directory ACLs and look for deny entries.

8) Symptom: “After data migration, permissions look flattened”

Root cause: Migration tool didn’t preserve ACLs (or translated to POSIX mode bits), or copied as root without preserving xattrs/ACLs.

Fix: Re-migrate with an ACL-preserving method appropriate to your platform, or restore from snapshot. Then lock the strategy so it doesn’t happen again.

Checklists / step-by-step plan

Checklist 1: Build a new SMB share on ZFS without future regrets

1. Create a dedicated dataset per share. Don’t dump everything into one dataset and hope for the best.
2. Set dataset properties explicitly: acltype=nfsv4, a deliberate aclmode, deliberate aclinherit, and a case-sensitivity choice aligned with Windows clients.
3. Pick an idmap strategy and standardize it across every SMB node that touches the data.
4. Configure Samba with ZFS ACL-aware VFS modules and enable ACL inheritance behavior you actually want.
5. Define one root folder ACL in Windows, validate inheritance by creating test files from multiple client apps.
6. Snapshot before giving it to real users. You want an escape hatch before “creative permissioning” starts.

Checklist 2: Permission incident response (30–60 minutes)

1. Identify the exact path and one affected user. Not “a bunch of people.” One identity. One object.
2. Confirm the user’s SID→UID mapping is correct on the SMB node handling the session.
3. Check share-level restrictions in Samba and confirm the user is connecting with the expected account.
4. Inspect server-side ACL on the directory and file; look for explicit denies and missing inheritance flags.
5. Test server-side effective write with sudo -u '#UID' test -w.
6. If needed, increase Samba debug briefly and correlate an NT_STATUS_ACCESS_DENIED event with the path.
7. Fix the smallest thing that restores correctness (often identity mapping or a single bad ACE), then roll back debug logging.

Checklist 3: Prevent permission drift (ongoing)

1. Declare a single source of truth for ACL changes (Windows-side tooling for SMB-first datasets).
2. Ban recursive chmod on production shares; enforce via automation guardrails and peer review.
3. Standardize idmap backend/ranges across nodes; treat changes as a migration project, not a tweak.
4. Snapshot regularly; keep at least one “known-good ACL baseline” snapshot for quick rollback/diff.
5. Monitor for unmapped SIDs and failed SID→UID translations; alert early.

FAQ

1) Should I use acltype=nfsv4 for SMB shares?

Yes, for Windows-centric SMB shares. It matches Windows ACL semantics far better than POSIX ACLs and reduces “translation surprises.”

2) Why do I see mode bits (770) if ACLs are the real control?

Because UNIX still has a mode field, and many tools display it. Depending on aclmode, chmod may or may not rewrite ACLs to match. Treat mode bits
as compatibility metadata unless you’ve intentionally chosen a mode-centric policy.

3) What’s the difference between aclmode=restricted and aclmode=discard?

restricted tends to preserve ACL intent when chmod is used. discard can remove ACLs when mode bits change. For SMB datasets, discard
is how you accidentally convert a nuanced permission model into rubble.

4) Why do permissions change depending on which SMB server I hit?

Almost always inconsistent idmap configuration. The same SID maps to different UIDs on different nodes, so the on-disk ACL entries match on one node and not another.

5) Can I safely run chown -R on an SMB dataset?

“Safely” is doing a lot of work there. Recursive ownership changes can invalidate ACL semantics (especially owner@ and group@ entries) and surprise Windows.
If you must, snapshot first, test on a clone, and understand your ACL model.

6) Do I need vfs_zfsacl (or equivalent) in Samba?

If you want correct NFSv4/ZFS ACL behavior exposed to Windows clients, yes. Without it, Samba may fall back to generic ACL handling and you’ll see missing
flags, broken inheritance, or Windows UI weirdness.

7) Why can a user create a file but not delete it?

Delete is often controlled by permissions on the parent directory (and Windows delete semantics are nuanced). Ensure the user/group has modify rights on the
directory, not just file write.

8) Why do I see “unknown SID” entries in ACLs?

The server can’t resolve that SID to a name, typically due to directory connectivity issues, deleted principals, trust problems, or idmap cache trouble.
Fix identity resolution before you rewrite ACLs, or you’ll bake in the wrong identities.

9) Is xattr=sa always better for SMB?

Often better for metadata-heavy SMB workloads because it reduces separate xattr I/O. But it’s a design choice—validate on your platform, and be cautious
about changing it on existing datasets without a plan.

10) What’s the simplest way to keep permissions sane?

One dataset per share, acltype=nfsv4, consistent idmap everywhere, manage ACLs from Windows, and keep Linux chmod away from the tree. Boring wins.

Next steps you can do this week

If your SMB-on-ZFS permissions feel haunted, don’t chase ghosts. Pick a clean model, then enforce it with configuration and habit.

1. Inventory your SMB datasets: record acltype, aclmode, aclinherit, xattr, and case sensitivity. Fix the obvious time bombs first.
2. Standardize idmap across every SMB node that touches the same storage. Treat changes as migrations. “Just tweaking it” is how ACLs become historical fiction.
3. Define an ACL baseline at the root of each share, validate inheritance with real client apps, and snapshot the baseline.
4. Put the Fast diagnosis playbook somewhere your on-call can find it at 2 a.m. Future-you will be tired and not interested in re-learning identity mapping.

Permission nightmares aren’t caused by a single bad checkbox. They’re caused by an inconsistent worldview. Make it consistent—and suddenly your file server
becomes boring again. That’s the goal.