Home / Troubleshooting / NFSv4 ACLs

NFSv4 ACLs on ONTAP: migrating from POSIX permissions

POSIX mode bits (owner/group/other) stop scaling once permissions get granular: "the sales group can read, but only three people can edit, and the subdirectory inherits something else." NFSv4 ACLs fix that with real per-user and per-group ACEs — but moving to them on ONTAP means understanding how they're stored (as NTFS ACLs), how identity gets mapped (NIS → AD/Kerberos), and what breaks mid-migration. This guide is the migration runbook.

POSIX vs NFSv4 ACLs: the model difference

Dimension	POSIX (mode bits + POSIX ACLs)	NFSv4 ACLs
Granularity	owner / group / other (+ limited ACL entries)	Unlimited ACEs: named users, named groups, inheritance flags
Rights	read / write / execute	Fine-grained: read_data, write_data, append, execute, delete, delete_child, read_attributes, write_attributes, read_acl, write_acl, read_named_attrs, write_named_attrs, synchronize
Inheritance	setgid/sticky hacks	Explicit inherit flags (file_inherit, dir_inherit, no_propagate, inherit_only)
Deny entries	No	Yes (deny ACEs, evaluated in order)
Who names the subject	UID/GID numbers	Strings: `user@domain` / `group@domain` — which forces identity mapping

NFSv4 ACLs are essentially the same object as Windows (NTFS) ACLs, which is why ONTAP can implement both with one mechanism. Linux clients need nfs4-acl-tools (nfs4_getfacl / nfs4_setfacl) to view and edit them.

How ONTAP stores NFSv4 ACLs (the fact that explains everything)

ONTAP implements NFSv4 ACLs as NTFS ACLs. The consequences are load-bearing:

Security style must be NTFS or mixed. On a UNIX-style volume, ONTAP honors POSIX semantics: mode bits are the truth and NFSv4 ACLs get flattened into them. NFSv4 ACLs only exist in full on volumes with NTFS (or mixed) security style. This is the #1 reason "I set an NFSv4 ACL and nothing happened."
Mixed-style volumes: the effective access for a file is decided per-file by which client touched it last (NTFS ACLs for Windows/SMB writers, POSIX for UNIX writers) — powerful but confusing; plan your security-style per volume deliberately.
Same ACL engine as SMB: because NFSv4 ACLs are NTFS ACLs, an NFSv4-granted ACE is visible to Windows clients and vice versa — dual-protocol shops get consistent permissions "for free" once mapping works. The SMB deep-dive covers the Windows side.

Identity mapping: the NIS → AD move

NFSv4 ACLs name subjects as name@domain. ONTAP has to resolve that to a UID/GID (for UNIX-style identity) and/or a Windows SID (for NTFS-style identity). Three knobs control it:

Name-service sources (vserver services name-service ns-switch): where ONTAP looks up users/groups — files, NIS, LDAP. Moving off NIS means pointing this at LDAP/AD (or files) instead.
Name mapping (vserver name-mapping): explicit rules translating between Windows names and UNIX names — e.g. map DOMAIN\jsmith ↔ jsmith, or DOMAIN\eng ↔ eng.
NFSv4 ID domain (vserver nfs modify -v4-id-domain): the @domain suffix ONTAP uses in NFSv4 owner strings, and the domain it maps back from. Inconsistent domains between clients and server = "no mapping" errors and anonymous ownership.

With Kerberos (sec-flavor krb5/krb5i/krb5p), the client identity is authenticated and mapped via Kerberos principal → UNIX/Windows identity. With AUTH_SYS, clients just send a UID/GID number — no real identity — which is why ACL migrations to granular, auditable permissions usually pair with a move to Kerberos.

Migration runbook (phased)

Inventory. Dump current permissions and identify the messy spots: nfs4_getfacl shows what clients currently see; getfacl (POSIX) shows mode bits. Decide the target model per volume: full NFSv4 ACLs (NTFS/mixed style) vs keep-POSIX (UNIX style).
Fix identity first. Point ns-switch at your AD/LDAP-backed sources, add name-mapping rules for your user and group names, and set a consistent v4-id-domain. Test with vserver name-mapping lookups before touching any ACL.
Switch the volume security style (or start with a test volume): convert UNIX → mixed or NTFS. Conversion preserves existing mode bits as a translated baseline ACL.
Apply ACLs. Use nfs4_setfacl on a Linux client, or ONTAP's own vserver security file-directory commands for programmatic control.
Verify and iterate on a pilot share, then roll out per volume with a rollback plan (restore from the pre-migration snapshot — take one before each volume conversion).

Commands that matter

# 1) Identity plumbing
vserver services name-service ns-switch show -vserver vs1
vserver services name-service ns-switch modify -vserver vs1 \
  -database passwd -sources ldap,files
vserver services name-service ns-switch modify -vserver vs1 \
  -database group  -sources ldap,files

vserver name-mapping create -vserver vs1 -direction win-unix \
  -position 1 -pattern "CORP\\*" -replacement "\\1"
vserver name-mapping show -vserver vs1 -direction win-unix

vserver nfs modify -vserver vs1 -v4-id-domain corp.example.com
vserver nfs show -vserver vs1 -fields v4-id-domain

# 2) Volume security style (converts data in place; snapshot first!)
volume modify -vserver vs1 -volume data -security-style ntfs
volume show -vserver vs1 -volume data -fields security-style

# 3) Apply / inspect ACLs — ONTAP side
vserver security file-directory show -vserver vs1 -volume data -path /project
vserver security file-directory ntfs create -vserver vs1 -volume data \
  -policy-name acl_policy \
  -ntfs-mode security \
  -apply-to /project

# 4) Apply / inspect ACLs — Linux client side
nfs4_getfacl /mnt/data/project
nfs4_setfacl -a A:g:eng@corp.example.com:rxtncy /mnt/data/project
nfs4_setfacl -a A:u:jsmith@corp.example.com:rwxtnc /mnt/data/reports.txt

ACE abbreviation cheat sheet: r=read_data, w=write_data, x=execute, a=append, d=delete, D=delete_child, t=read_attributes, T=write_attributes, n=read_acl, N=write_acl, c=read_named_attrs, C=write_named_attrs, y=synchronize. Common combos: rxtncy = read + traverse, rwxtnc = full modify without delete_child, rwxtncCy = full control minus ownership.

Failure signatures and fixes

Symptom	Likely cause	Check / fix
`nfs4_setfacl: Operation not supported`	Volume security style is UNIX, or client mounted NFSv3	`volume show -fields security-style`; mount with `nfsvers=4` (or 4.1/4.2)
ACL saved but files still show old POSIX perms	UNIX-style volume flattening NFSv4 ACLs to mode bits	Convert volume to mixed/NTFS security style
Files owned by `nobody` / `anonymous` after migration	ID domain mismatch, or name mapping missing for the owner	Compare `v4-id-domain` on client (mount option) and server; add `name-mapping` rules; check ns-switch sources
Group permissions ignored	ACE order: a deny ACE before an allow ACE wins	`nfs4_getfacl` and reorder; NFSv4 is first-match, not accumulate-then-deny
Permissions work over SMB but not NFS (or reverse)	Mixed-style volume: per-file effective style decided by last writer	Standardize security style per volume; check `vserver security file-directory show` per path
Slow access on metadata-heavy trees	Each ACE subject resolved via LDAP/AD; Kerberos adds lookups	Cache/tune name services, reduce ACE count, batch operations; verify LDAP server latency

Scale considerations (the "at scale" thread)

ACE resolution cost: every access check resolves ACE subjects against name services. Deep trees with thousands of named ACEs on hot directories measurably cost metadata performance — prefer group ACEs over user ACEs (fewer lookups, simpler audits).
Kerberos is the honest identity: AUTH_SYS UIDs are client-supplied numbers — any client can claim any UID. If the ACLs encode real policy (finance, HR), pair NFSv4 ACLs with krb5p exports; see the NFS troubleshooting page for export-policy sec-flavor setup.
Migration tooling: for large trees, script the migration with vserver security file-directory (REST/CLI) rather than client-side nfs4_setfacl walks — you get atomic policy application and no client dependency.
NFSv4.2: newer ONTAP releases support NFSv4.2 (reflink/clone, and improved ACL semantics) — mount with nfsvers=4.2 where the client supports it.