Australian cloud for business software — built and run in Sydney since 2003

+61 2 8282 5656
support@netleverage.com
Talk to an engineer
Talk to an engineer
NetLeverage
NetLeverage

NFSv4 ACLs on Linux and NAS: where POSIX translation loses permissions during a restore

Technical article
Backup & Recovery

Originally published:

About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.

Most Linux administrators know two permission systems: the owner, group and other bits, and POSIX ACLs, which add named users and groups. A third is common on file servers and NAS devices: NFSv4 access control lists.

NFSv4 ACLs look more like Windows permissions than like Linux ones. They have allow and deny entries, separate rights for deleting, changing permissions and taking ownership, and detailed inheritance rules. The everyday Linux backup tools were designed around the simpler POSIX model, so their familiar ACL options do not by themselves establish support for the full NFSv4 model on a particular platform. A restore can therefore bring back every file with access that differs from the original, sometimes looser, sometimes tighter, unless capability, diagnostics and effective permissions are verified.

This guide explains the NFSv4 ACL model from the standard, how servers store and translate it, what the common tools do, and how to plan a restore that keeps access correct. The NAS backup overview covers NDMP and SMB with Windows-style ACLs; this article examines NFSv4 ACL semantics and translation.

Why it matters

Access lists on a shared folder usually encode business decisions: who may see payroll, who may change a contract, who may only read. When a restore loses them, the folder may fall back to the owner, group and other bits, which can open data to people who should not see it, or block the people who need it.

Because nothing fails outright, the loss often surfaces days later as a complaint or, worse, as an audit finding.

How it works

The model

The nfs4_acl(5) manual page describes the structure: "An ACL is a list of permissions associated with a file or directory and consists of one or more Access Control Entries (ACEs)." It compares the model to the alternatives: NFSv4 ACLs "provide finer granularity than typical POSIX read/write/execute permissions and are similar to CIFS ACLs."

Each entry has a type, flags, a principal and permissions. The page lists four types: allow, deny, audit and alarm. It lists 13 permissions for files and 14 for directories, including separate rights to read and write the ACL itself and to change ownership.

The principal is a named user or group, or one of three special principals: OWNER@, GROUP@ and EVERYONE@. The page stresses a difference from Linux bits: EVERYONE@ always matches, and that "is different from the" other class "used in mode bits or POSIX ACLs, which does not match the file's owner or group." The standard, RFC 8881, makes the same point: EVERYONE@ "means literally everyone, including the owner or owning group."

Named principals are strings, not numbers. Our reading: a named user in an NFSv4 ACL depends on the same name-to-number mapping as file ownership over NFSv4, so a restored server with a different ID-mapping domain can show ACL entries for users it cannot resolve.

Order matters

In POSIX ACLs the order of entries does not change the result. In NFSv4 ACLs it does. RFC 8881 says that "the server processes each nfsace4 entry in order." Once a permission bit has been allowed, "it is no longer considered in the processing of later ACEs." If a matching deny entry intersects requested permission bits that have not already been allowed, "the request is denied." An unrelated deny permission does not automatically deny the whole request. Anything not settled by the end is refused: "access is denied."

nfs4_acl(5) gives practical advice: "Deny ACEs should be avoided whenever possible." Its practical point is that NFSv4 ACE order affects evaluation. Do not infer from that comparison that ordering is irrelevant to Windows ACLs; this article does not analyse the Windows model.

Our reading: a restore that keeps every entry but changes their order can change who has access. A tool must preserve the intended effective permissions. Exact order is useful evidence, but servers may legitimately normalise an ACL within the constraints discussed below.

Inheritance

Directories can carry entries meant for their children. nfs4_acl(5) explains that "ACEs are inherited from the parent directory's ACL at the time a file or subdirectory is created." It describes file-inherit, directory-inherit, no-propagate-inherit and inherit-only flags, and notes that some servers, including the Linux kernel server, split an inherited entry into an effective copy and a heritable copy.

Our reading: when files are restored into a directory that has inheritable entries, each new file receives those entries at creation. If the restore then sets the original ACL, the inherited ones are replaced. If it does not, the restored files carry the destination folder's rules instead of their own.

Servers may return something different

The NFSv4 ACL a client reads is not always the one it set. nfs4_acl(5) says: "NFSv4 servers may return an ACL slightly different than one you set." A server might silently turn on a permission it always grants, combine rights it cannot separate, or "In extreme cases the server may also reorder or combine ACEs." The page adds that servers "will attempt to ensure that the ACLs they return are no more permissive than the ones you set."

RFC 8881 explains why: some platforms cannot store the full model, so "the server may support the acl attributes by mapping between its ACL model and the NFSv4.1 ACL model." The rule is that "Servers must ensure that the ACL they actually store or enforce is at least as strict as the NFSv4 ACL that was set."

Support is also optional. The RFC states: "Support for any of the ACL attributes is optional (albeit RECOMMENDED)." A server asked to store an entry type it cannot store "MUST reject the request with NFS4ERR_ATTRNOTSUPP."

Where the ACL actually lives

This is the heart of the backup problem. An NFSv4 ACL seen by a client may be stored on the server in one of two ways.

Natively. Some file systems store NFSv4-style ACLs directly. The OpenZFS zfsprops(7) page (master branch, read 13 November 2026) describes an acltype property with an nfsv4 value, "default on FreeBSD", meaning "NFSv4-style ZFS ACLs should be used." The same page says: "The nfsv4 ZFS ACL type is not yet supported on Linux." On Linux the default is off, and the posix value "indicates POSIX ACLs should be used." Check the documentation for the installed release because the master branch tracks development.

Translated. A conventional Linux kernel NFS server exporting an ext4 or XFS filesystem can translate from its POSIX ACL model. Other NFS servers, filesystem features and NAS implementations need their own assessment. The IETF draft Mapping Between NFSv4 and Posix Draft ACLs, a 2006 draft, expired since February 2007, by the authors of the Linux tools, describes the method and its limit: "Since NFSv4 ACLs are more fine-grained than POSIX ACLs, it is not possible in general to map an arbitrary NFSv4 ACL to a POSIX ACL with the same semantics." Mapping the other way is easier: "it is possible to map any POSIX ACL to a NFSv4 ACL with nearly identical semantics". The example algorithm for a server "errs on the side of making the ACL more restrictive."

Our reading: on a Linux NFS server using POSIX ACLs underneath, the NFSv4 ACL is a view. The real data is the POSIX ACL, which POSIX tools can back up. On a native NFSv4 ACL store, such as ZFS with acltype set to nfsv4 on FreeBSD-based systems, the real data is the NFSv4 ACL, and the chosen tool must explicitly support that stored ACL model. Neither an archive option nor a successful file copy proves it does.

Mode bits and ACLs change each other

RFC 8881 requires a server that supports both to keep them in step: it "must take care to synchronize" the owner, group and other bits "with the ACEs that have respective who fields of" OWNER@, GROUP@ and EVERYONE@.

That has a restore consequence. When the mode is set without an ACL, the ACL "must be modified in accordance with the updated value of those bits." The RFC adds: "the requirement may be met by discarding the acl and dacl, in favor of an ACL that represents the mode and only the mode." It calls this permitted but not preferred.

OpenZFS makes the behaviour configurable. Its aclmode property controls how an ACL is changed by a permission change, and the default on the page reads "discard default, deletes all ACEs except for those representing the mode of the file or directory requested by chmod(2)."

When both are set in one operation, the RFC sets the order: "mode (or mode_set_masked), then ACL."

Our reading: a restore that sets the ACL first and the permission bits second may wipe the ACL it just restored. Set permission bits first, then the ACL.

What the common tools do

GNU tar. The GNU tar manual describes --acls as "Enable POSIX ACLs support." It does not mention NFSv4 ACLs in the pages read.

rsync. The rsync manual says -A updates "the destination ACLs to be the same as the source ACLs", but "The source and destination systems must have compatible ACL entries for this option to work properly." For extended attributes, a super-user copy covers "all namespaces except system.*".

cp. The GNU coreutils upstream Texinfo cp manual is explicit: "ACLs are not necessarily translated when the source and destination are on file systems with different ACL formats (e.g., NFSv4 versus POSIX formats)."

The NFSv4 ACL tools. On a Linux NFS client, nfs4_getfacl(1) displays the ACL "provided they are on mounted NFSv4 filesystems which support ACLs", and has a recursive option. nfs4_setfacl(1) can set an ACL from a file, and has a --test option to "display results of COMMAND, but do not save changes."

The cited tool pages do not establish universal full NFSv4 ACL preservation through a Linux NFS client. Build options, operating-system ACL APIs, client/server behaviour and mappings matter. Treat preservation as unproven until the exact path has been checked, rather than claiming every implementation must lose every ACL. A backup taken on a Linux server that stores POSIX ACLs can carry them as POSIX ACLs, with the precision limits of the translation. A backup of a native NFSv4 ACL store needs a tool that reads that store's own format, usually the NAS's own replication or snapshot method.

A worked example

This illustration applies the documented rules to an imagined case; it was not run.

A finance share lives on a FreeBSD-based NAS using ZFS with NFSv4 ACLs. Its top folder permits the finance group to read and modify files, reserves ACL changes for a manager, and has a contractor deny entry before an applicable group allow. The example assumes the source platform supports those entries; audit and alarm support must be checked separately.

The share is backed up nightly by a Linux host that mounts it over NFS and copies it with rsync in archive mode with ACLs. The NAS fails and the share is restored to a Linux server on XFS.

  • If this particular backup path records only POSIX permissions, the full original NFSv4 policy is not preserved. The actual archive must be inspected; the command name alone does not establish what survived.
  • The restored folder's access is whatever those bits allow. The manager-specific permission and contractor restriction may be lost or transformed, changing effective access.
  • A saved ACL text record would preserve evidence for comparison, but would not make the target capable of enforcing every entry. The server may reject unsupported ACLs or translate them conservatively. Select a compatible target or redesign the access policy explicitly instead of silently accepting the loss of special rights.

A planning checklist

These are our recommendations, drawn from the sources above.

  1. Find out where the ACLs really live. Native NFSv4 store, or POSIX ACLs behind an NFSv4 view. The answer decides which tool can back them up.
  2. Back up at the layer that holds them. For POSIX-backed Linux servers, back up on the server with POSIX ACL support. For native NFSv4 stores, use the platform's own method that keeps its ACLs.
  3. Keep a text record of NFSv4 ACLs for important folders, taken with the NFSv4 tools, alongside each backup. It is small and readable during an incident.
  4. Restore identities and the ID-mapping domain first, so named principals resolve.
  5. Set permission bits before ACLs, never after.
  6. Preview before applying. The test option displays a proposed list; it does not prove the server can store or enforce it. Read back the accepted ACL and check effective access on an isolated representative restore.
  7. Plan for rejection or restrictive translation on an incompatible target. Review special rights and inheritance explicitly; an expired mapping draft is not proof of the current server implementation.
  8. Check order and inheritance on a sample of restored folders against the record.

Risks and limits

  • POSIX-oriented options do not prove full NFSv4 ACL preservation. Verify the actual build, platform and storage path.
  • Translation is lossy. An arbitrary NFSv4 ACL cannot in general be expressed as a POSIX ACL.
  • Order changes meaning. Reordered entries can change access.
  • A permission change can discard an ACL, depending on the server and its settings.
  • Servers may adjust ACLs they are given, within the rule that the result is no more permissive.
  • The mapping draft expired in 2007; it is cited for method, not as current Linux server documentation.
  • Nothing here was run. Behaviour is quoted from the documentation for planning; rehearse on a non-production system.

Sources

This article was originally published on .