filesystem.setacl

Set the ACL of a given path.

The dacl entry formatting depends on the underlying acltype: an NFS4 ACL requires NFSv4 entries, while a POSIX1E ACL requires POSIX1e entries. When stripacl is set, the ACL is converted to a trivial ACL; an ACL is trivial if it can be expressed as a file mode without losing any access rules.

Note

For each owner change, set one and only one of uid or user (and likewise one of gid or group), and only if the caller wishes to change the owning user or group of the file or directory.

Warning

If user, uid, group, or gid is specified in a recursive operation, then the owning user, group, or both for all files will be changed.

The following notes about ACL entries are necessarily terse. If more detail is required, please consult relevant TrueNAS documentation.

NFSv4 ACL entry semantics

The tag identifies the principal to whom the entry applies. USER and GROUP have conventional meanings: owner@ refers to the owning user of the file, group@ to the owning group, and everyone@ to all users (including the owning user and group). The type may be ALLOW or DENY, and DENY entries take precedence over ALLOW when the ACL is evaluated. The flags inheritance flags determine how an entry is presented (if at all) on newly-created files or directories within the specified path and are only valid for directories.

POSIX1e ACL entry semantics

When default is true, the entry belongs to the POSIX default ACL and is copied to new files and directories created within the directory where it is set; default entries are not evaluated when determining access to the file on which they are set. When default is false, the entry applies to the POSIX access ACL which is used to determine access to the directory but is not inherited.

For the tag, USER_OBJ refers to the owning user (denoted “user” in conventional POSIX UGO permissions), GROUP_OBJ refers to the owning group (denoted “group”), and OTHER applies to all users and groups who are not USER_OBJ or GROUP_OBJ. MASK sets the maximum permissions granted to all USER and GROUP entries. A valid POSIX1e ACL contains precisely one USER_OBJ, GROUP_OBJ, OTHER, and MASK entry for each of the default and access lists.

This method is a job.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: filesystem_acl

filesystem_acl

Type: object

FilesystemSetaclArgs parameters.

 No Additional Properties

Path

Type: string

Absolute filesystem path to set ACL on.

Must be at least 1 characters long

Dacl


Array of Access Control Entries to apply to the filesystem object.

Type: array of object
No Additional Items
Each item of this array must be:

NFS4ACE

Type: object
No Additional Properties

Tag

Type: enum (of string)

Subject type for this ACE.

  • owner@: File/directory owner
  • group@: File/directory primary group
  • everyone@: All users
  • USER: Specific user account
  • GROUP: Specific group
Must be one of:
  • "owner@"
  • "group@"
  • "everyone@"
  • "USER"
  • "GROUP"

Type

Type: enum (of string)

Access control type.

  • ALLOW: Grant the specified permissions
  • DENY: Explicitly deny the specified permissions
Must be one of:
  • "ALLOW"
  • "DENY"

Perms


Permissions granted or denied by this ACE.

NFS4ACE_AdvancedPerms

Type: object
No Additional Properties

Read Data

Type: boolean Default: false

Permission to read file data or list directory contents.

Write Data

Type: boolean Default: false

Permission to write file data or create files in directory.

Append Data

Type: boolean Default: false

Permission to append data to files or create subdirectories.

Read Named Attrs

Type: boolean Default: false

Permission to read named attributes (extended attributes).

Write Named Attrs

Type: boolean Default: false

Permission to write named attributes (extended attributes).

Execute

Type: boolean Default: false

Permission to execute files or traverse directories.

Delete

Type: boolean Default: false

Permission to delete the file or directory.

Delete Child

Type: boolean Default: false

Permission to delete child files within a directory.

Read Attributes

Type: boolean Default: false

Permission to read basic file attributes (size, timestamps, etc.).

Write Attributes

Type: boolean Default: false

Permission to write basic file attributes.

Read Acl

Type: boolean Default: false

Permission to read the Access Control List.

Write Acl

Type: boolean Default: false

Permission to modify the Access Control List.

Write Owner

Type: boolean Default: false

Permission to change the file owner.

Synchronize

Type: boolean Default: false

Permission to use the file/directory as a synchronization primitive.

NFS4ACE_BasicPerms

Type: object
No Additional Properties

Basic

Type: enum (of string)

Basic permission level for NFS4 ACE.

  • FULL_CONTROL: Full read, write, execute, and administrative permissions
  • MODIFY: Read, write, and execute permissions
  • READ: Read-only permissions
  • TRAVERSE: Execute/traverse permissions only
Must be one of:
  • "FULL_CONTROL"
  • "MODIFY"
  • "READ"
  • "TRAVERSE"

Flags


Inheritance and other behavioral flags for this ACE.

NFS4ACE_AdvancedFlags

Type: object
No Additional Properties

File Inherit

Type: boolean Default: false

Apply this ACE to files within directories.

Directory Inherit

Type: boolean Default: false

Apply this ACE to subdirectories within directories.

No Propagate Inherit

Type: boolean Default: false

Do not propagate inheritance beyond immediate children.

Inherit Only

Type: boolean Default: false

This ACE only affects inheritance, not the object itself.

Inherited

Type: boolean Default: false

This ACE was inherited from a parent directory.

NFS4ACE_BasicFlags

Type: object
No Additional Properties

Basic

Type: enum (of string)

Basic inheritance behavior for NFS4 ACE.

  • INHERIT: Apply to child files and directories
  • NOINHERIT: Do not apply to child objects
Must be one of:
  • "INHERIT"
  • "NOINHERIT"

Id

Default: null

UID or GID when tag is "USER" or "GROUP". null for special entries.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Who

Default: null

Username or group name when tag is "USER" or "GROUP". null for special entries.

Type: string
Type: string

Must be at least 1 characters long

Type: null
Type: array of object
No Additional Items
Each item of this array must be:

POSIXACE

Type: object
No Additional Properties

Tag

Type: enum (of string)

Subject type for this POSIX ACE.

  • USER_OBJ: File/directory owner
  • GROUP_OBJ: File/directory primary group
  • OTHER: All other users
  • MASK: Maximum permissions for named users and groups
  • USER: Specific user account
  • GROUP: Specific group
Must be one of:
  • "USER_OBJ"
  • "GROUP_OBJ"
  • "OTHER"
  • "MASK"
  • "USER"
  • "GROUP"

POSIXACE_Perms

Type: object

Read, write, and execute permissions for this ACE.

 No Additional Properties

Read

Type: boolean

Permission to read file contents or list directory contents.

Write

Type: boolean

Permission to write file contents or create/delete files in directory.

Execute

Type: boolean

Permission to execute files or traverse directories.

Default

Type: boolean

Whether this is a default ACE that applies to newly created child objects.

Id

Default: null

Numeric user or group ID when tag is USER or GROUP. null for object entries.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Who

Default: null

Username or group name when tag is USER or GROUP. null for object entries.

Type: string
Type: string

Must be at least 1 characters long

Type: null

FilesystemSetAclOptions

Type: object
Default:
{ "stripacl": false, "recursive": false, "traverse": false, "canonicalize": true, "validate_effective_acl": true }

Configuration options for ACL setting behavior.

 No Additional Properties

Stripacl

Type: boolean Default: false

Whether to remove the ACL entirely and revert to basic POSIX permissions.

Recursive

Type: boolean Default: false

Whether to apply ACL changes recursively to all child files and directories.

Traverse

Type: boolean Default: false

Whether to traverse filesystem boundaries during recursive operations.

Canonicalize

Type: boolean Default: true

Whether to reorder ACL entries in Windows canonical order.

Validate Effective Acl

Type: boolean Default: true

Whether to validate that the users/groups granted access in the ACL can actually access the path or parent path.

NFS4ACL_Flags

Type: object
Default:
{ "autoinherit": false, "protected": false, "defaulted": false }

NFS4 ACL flags for inheritance and protection behavior.

 No Additional Properties

Autoinherit

Type: boolean Default: false

Whether inheritance is automatically applied from parent directories.

Protected

Type: boolean Default: false

Whether the ACL is protected from inheritance modifications.

Defaulted

Type: boolean Default: false

Whether this ACL was created by default rules rather than explicit configuration.

Uid

Default: -1

Numeric user ID to set as owner or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

User

Default: null

Username to set as owner or null to preserve existing.

Type: string
Type: null

Gid

Default: -1

Numeric group ID to set as group or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Group

Default: null

Group name to set as group or null to preserve existing.

Type: string
Type: null

Acltype

Default: null

ACL type to use or null to auto-detect from filesystem capabilities.

Type: enum (of string)
Must be one of:
  • "NFS4"
  • "POSIX1E"
Type: null

Result


ACL information for the requested filesystem path.

NFS4ACLResult

Type: object
No Additional Properties

Path

Type: string

Absolute filesystem path this ACL information applies to.

Must be at least 1 characters long

User


Username of the file/directory owner or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Group


Group name of the file/directory group or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Uid


Numeric user ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Gid


Numeric group ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Acltype

Type: const

ACL type identifier for NFS4 access control lists.

Specific value: "NFS4"

Acl

Type: array of object

Array of NFS4 Access Control Entries defining permissions.

 No Additional Items
Each item of this array must be:

NFS4ACE

Type: object
No Additional Properties

Tag

Type: enum (of string)

Subject type for this ACE.

  • owner@: File/directory owner
  • group@: File/directory primary group
  • everyone@: All users
  • USER: Specific user account
  • GROUP: Specific group
Must be one of:
  • "owner@"
  • "group@"
  • "everyone@"
  • "USER"
  • "GROUP"

Type

Type: enum (of string)

Access control type.

  • ALLOW: Grant the specified permissions
  • DENY: Explicitly deny the specified permissions
Must be one of:
  • "ALLOW"
  • "DENY"

Perms


Permissions granted or denied by this ACE.

NFS4ACE_AdvancedPerms

Type: object
No Additional Properties

Read Data

Type: boolean Default: false

Permission to read file data or list directory contents.

Write Data

Type: boolean Default: false

Permission to write file data or create files in directory.

Append Data

Type: boolean Default: false

Permission to append data to files or create subdirectories.

Read Named Attrs

Type: boolean Default: false

Permission to read named attributes (extended attributes).

Write Named Attrs

Type: boolean Default: false

Permission to write named attributes (extended attributes).

Execute

Type: boolean Default: false

Permission to execute files or traverse directories.

Delete

Type: boolean Default: false

Permission to delete the file or directory.

Delete Child

Type: boolean Default: false

Permission to delete child files within a directory.

Read Attributes

Type: boolean Default: false

Permission to read basic file attributes (size, timestamps, etc.).

Write Attributes

Type: boolean Default: false

Permission to write basic file attributes.

Read Acl

Type: boolean Default: false

Permission to read the Access Control List.

Write Acl

Type: boolean Default: false

Permission to modify the Access Control List.

Write Owner

Type: boolean Default: false

Permission to change the file owner.

Synchronize

Type: boolean Default: false

Permission to use the file/directory as a synchronization primitive.

NFS4ACE_BasicPerms

Type: object
No Additional Properties

Basic

Type: enum (of string)

Basic permission level for NFS4 ACE.

  • FULL_CONTROL: Full read, write, execute, and administrative permissions
  • MODIFY: Read, write, and execute permissions
  • READ: Read-only permissions
  • TRAVERSE: Execute/traverse permissions only
Must be one of:
  • "FULL_CONTROL"
  • "MODIFY"
  • "READ"
  • "TRAVERSE"

Flags


Inheritance and other behavioral flags for this ACE.

NFS4ACE_AdvancedFlags

Type: object
No Additional Properties

File Inherit

Type: boolean Default: false

Apply this ACE to files within directories.

Directory Inherit

Type: boolean Default: false

Apply this ACE to subdirectories within directories.

No Propagate Inherit

Type: boolean Default: false

Do not propagate inheritance beyond immediate children.

Inherit Only

Type: boolean Default: false

This ACE only affects inheritance, not the object itself.

Inherited

Type: boolean Default: false

This ACE was inherited from a parent directory.

NFS4ACE_BasicFlags

Type: object
No Additional Properties

Basic

Type: enum (of string)

Basic inheritance behavior for NFS4 ACE.

  • INHERIT: Apply to child files and directories
  • NOINHERIT: Do not apply to child objects
Must be one of:
  • "INHERIT"
  • "NOINHERIT"

Id

Default: null

UID or GID when tag is "USER" or "GROUP". null for special entries.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Who

Default: null

Username or group name when tag is "USER" or "GROUP". null for special entries.

Type: string
Type: string

Must be at least 1 characters long

Type: null

NFS4ACL_Flags

Type: object

NFS4 ACL behavioral flags for inheritance and protection.

 No Additional Properties

Autoinherit

Type: boolean Default: false

Whether inheritance is automatically applied from parent directories.

Protected

Type: boolean Default: false

Whether the ACL is protected from inheritance modifications.

Defaulted

Type: boolean Default: false

Whether this ACL was created by default rules rather than explicit configuration.

Trivial

Type: boolean

Whether this ACL is a simple/trivial ACL equivalent to POSIX permissions.

POSIXACLResult

Type: object
No Additional Properties

Path

Type: string

Absolute filesystem path this ACL information applies to.

Must be at least 1 characters long

User


Username of the file/directory owner or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Group


Group name of the file/directory group or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Uid


Numeric user ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Gid


Numeric group ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Acltype

Type: const

ACL type identifier for POSIX.1e access control lists.

Specific value: "POSIX1E"

Acl

Type: array of object

Array of POSIX Access Control Entries defining permissions.

 No Additional Items
Each item of this array must be:

POSIXACE

Type: object
No Additional Properties

Tag

Type: enum (of string)

Subject type for this POSIX ACE.

  • USER_OBJ: File/directory owner
  • GROUP_OBJ: File/directory primary group
  • OTHER: All other users
  • MASK: Maximum permissions for named users and groups
  • USER: Specific user account
  • GROUP: Specific group
Must be one of:
  • "USER_OBJ"
  • "GROUP_OBJ"
  • "OTHER"
  • "MASK"
  • "USER"
  • "GROUP"

POSIXACE_Perms

Type: object

Read, write, and execute permissions for this ACE.

 No Additional Properties

Read

Type: boolean

Permission to read file contents or list directory contents.

Write

Type: boolean

Permission to write file contents or create/delete files in directory.

Execute

Type: boolean

Permission to execute files or traverse directories.

Default

Type: boolean

Whether this is a default ACE that applies to newly created child objects.

Id

Default: null

Numeric user or group ID when tag is USER or GROUP. null for object entries.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Who

Default: null

Username or group name when tag is USER or GROUP. null for object entries.

Type: string
Type: string

Must be at least 1 characters long

Type: null

Trivial

Type: boolean

Whether this ACL is a simple/trivial ACL equivalent to standard POSIX permissions.

DISABLED_ACLResult

Type: object
No Additional Properties

Path

Type: string

Absolute filesystem path this ACL information applies to.

Must be at least 1 characters long

User


Username of the file/directory owner or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Group


Group name of the file/directory group or null if unresolved.

Type: string

Must be at least 1 characters long

Type: null

Uid


Numeric user ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Gid


Numeric group ID for file/directory ownership or null to preserve existing.

Type: integer

Value must be greater or equal to -1 and lesser or equal to 2147483647

Type: null

Acltype

Type: const

ACL type identifier indicating access control lists are disabled.

Specific value: "DISABLED"

Acl

Type: null

Always null when ACLs are disabled on the filesystem.

Trivial

Type: const

Always true when ACLs are disabled - only basic POSIX permissions apply.

Specific value: true


Required roles: FILESYSTEM_ATTRS_WRITE