# filesystem.setacl

Set ACL of a given path. Takes the following parameters: path full path to directory or file.

dacl ACL entries. Formatting depends on the underlying acltype. NFS4ACL requires NFSv4 entries. POSIX1e requires POSIX1e entries.

uid the desired UID of the file user. If set to None (the default), then user is not changed.

user the desired username for the file user. If set to None, then user is not changed.

Note about interaction between uid and user: One and only one of these parameters should be set, and _only_ if the API consumer wishes to change the owner on the file / directory.

gid the desired GID of the file group. If set to None (the default), then group is not changed.

group the desired groupname for the file group. If set to None (the default), then group is not changed.

Note about interaction between gid and group: One and only one of these parameters should be set, and _only_ if the API consumer wishes to change the owner on the file / 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.

recursive apply the ACL recursively

traverse traverse filestem boundaries (ZFS datasets)

strip convert ACL to trivial. ACL is trivial if it can be expressed as a file mode without losing any access rules.

canonicalize reorder ACL entries so that they are in concanical form as described in the Microsoft documentation MS-DTYP 2.4.5 (ACL). This only applies to NFSv4 ACLs.

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

Notes about NFSv4 ACL entry fields:

tag refers to the type of principal to whom the ACL entries applies. USER and GROUP have conventional meanings. owner@ refers to the owning user of the file, group@ refers to the owning group of the file, and everyone@ refers to ALL users (including the owning user and group)..

id refers to the numeric user id or group id associatiated with USER or GROUP entries.

who a user or group name may be specified in lieu of numeric ID for USER or GROUP entries

type may be ALLOW or DENY. Deny entries take precedence over allow when the ACL is evaluated.

perms permissions allowed or denied by the entry. May be set as a simlified BASIC type or more complex type detailing specific permissions.

flags inheritance flags determine how this entry will be presented (if at all) on newly-created files or directories within the specified path. Only valid for directories.

Notes about posix1e ACL entry fields:

default the ACL entry is in the posix default ACL (will be copied to new files and directories) created within the directory where it is set. These are _NOT_ evaluated when determining access for the file on which they’re set. If default is false then the entry applies to the posix access ACL, which is used to determine access to the directory, but is not inherited on new files / directories.

tag the type of principal to whom the ACL entry apples. USER and GROUP have conventional meanings USER_OBJ refers to the owning user of the file and is also denoted by “user” in conventional POSIX UGO permissions. GROUP_OBJ refers to the owning group of the file and is denoted by “group” in the same. OTHER refers to POSIX other, which applies to all users and groups who are not USER_OBJ or GROUP_OBJ. MASK sets maximum permissions granted to all USER and GROUP entries. A valid POSIX1 ACL entry contains precisely one USER_OBJ, GROUP_OBJ, OTHER, and MASK entry for the default and access list.

id refers to the numeric user id or group id associatiated with USER or GROUP entries.

who a user or group name may be specified in lieu of numeric ID for USER or GROUP entries

perms - object containing posix permissions.

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

Must be at least `1` characters long

##

#### Dacl

## Any of

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)

##### Must be one of:

- "owner@"
- "group@"
- "everyone@"
- "USER"
- "GROUP"

##

#### Type

Type: enum (of string)

##### Must be one of:

- "ALLOW"
- "DENY"

##

#### Perms

## Any of

#### NFS4ACE_AdvancedPerms

Type: object
No Additional Properties

##

#### Read Data

Type: boolean Default: false

##

#### Write Data

Type: boolean Default: false

##

#### Append Data

Type: boolean Default: false

##

#### Read Named Attrs

Type: boolean Default: false

##

#### Write Named Attrs

Type: boolean Default: false

##

#### Execute

Type: boolean Default: false

##

#### Delete

Type: boolean Default: false

##

#### Delete Child

Type: boolean Default: false

##

#### Read Attributes

Type: boolean Default: false

##

#### Write Attributes

Type: boolean Default: false

##

#### Read Acl

Type: boolean Default: false

##

#### Write Acl

Type: boolean Default: false

##

#### Write Owner

Type: boolean Default: false

##

#### Synchronize

Type: boolean Default: false

#### NFS4ACE_BasicPerms

Type: object
No Additional Properties

##

#### Basic

Type: enum (of string)

##### Must be one of:

- "FULL_CONTROL"
- "MODIFY"
- "READ"
- "TRAVERSE"

##

#### Flags

## Any of

#### NFS4ACE_AdvancedFlags

Type: object
No Additional Properties

##

#### File Inherit

Type: boolean Default: false

##

#### Directory Inherit

Type: boolean Default: false

##

#### No Propagate Inherit

Type: boolean Default: false

##

#### Inherit Only

Type: boolean Default: false

##

#### Inherited

Type: boolean Default: false

#### NFS4ACE_BasicFlags

Type: object
No Additional Properties

##

#### Basic

Type: enum (of string)

##### Must be one of:

- "INHERIT"
- "NOINHERIT"

##

#### Id

Default: null

## Any of

Type: integer

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

Type: null

##

#### Who

Default: null

## Any of

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)

##### Must be one of:

- "USER_OBJ"
- "GROUP_OBJ"
- "OTHER"
- "MASK"
- "USER"
- "GROUP"

##

#### POSIXACE_Perms

Type: object
No Additional Properties

##

#### Read

Type: boolean

##

#### Write

Type: boolean

##

#### Execute

Type: boolean

##

#### Default

Type: boolean

##

#### Id

Default: null

## Any of

Type: integer

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

Type: null

##

#### Who

Default: null

## Any of

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 }
No Additional Properties

##

#### Stripacl

Type: boolean Default: false

##

#### Recursive

Type: boolean Default: false

##

#### Traverse

Type: boolean Default: false

##

#### Canonicalize

Type: boolean Default: true

##

#### Validate Effective Acl

Type: boolean Default: true

##

#### NFS4ACL_Flags

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

##

#### Autoinherit

Type: boolean Default: false

##

#### Protected

Type: boolean Default: false

##

#### Defaulted

Type: boolean Default: false

##

#### Uid

Default: -1

## Any of

Type: integer

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

Type: null

##

#### User

Default: null

## Any of

Type: string
Type: null

##

#### Gid

Default: -1

## Any of

Type: integer

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

Type: null

##

#### Group

Default: null

## Any of

Type: string
Type: null

##

#### Acltype

Default: null

## Any of

Type: enum (of string)

##### Must be one of:

- "NFS4"
- "POSIX1E"

Type: null

##

#### Result

## Any of

#### NFS4ACLResult

Type: object
No Additional Properties

##

#### Path

Type: string

Must be at least `1` characters long

##

#### User

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Uid

## Any of

Type: integer

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

Type: null

##

#### Gid

## Any of

Type: integer

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

Type: null

##

#### Acltype

Type: const
Specific value: `"NFS4"`

##

#### Acl

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)

##### Must be one of:

- "owner@"
- "group@"
- "everyone@"
- "USER"
- "GROUP"

##

#### Type

Type: enum (of string)

##### Must be one of:

- "ALLOW"
- "DENY"

##

#### Perms

## Any of

#### NFS4ACE_AdvancedPerms

Type: object
No Additional Properties

##

#### Read Data

Type: boolean Default: false

##

#### Write Data

Type: boolean Default: false

##

#### Append Data

Type: boolean Default: false

##

#### Read Named Attrs

Type: boolean Default: false

##

#### Write Named Attrs

Type: boolean Default: false

##

#### Execute

Type: boolean Default: false

##

#### Delete

Type: boolean Default: false

##

#### Delete Child

Type: boolean Default: false

##

#### Read Attributes

Type: boolean Default: false

##

#### Write Attributes

Type: boolean Default: false

##

#### Read Acl

Type: boolean Default: false

##

#### Write Acl

Type: boolean Default: false

##

#### Write Owner

Type: boolean Default: false

##

#### Synchronize

Type: boolean Default: false

#### NFS4ACE_BasicPerms

Type: object
No Additional Properties

##

#### Basic

Type: enum (of string)

##### Must be one of:

- "FULL_CONTROL"
- "MODIFY"
- "READ"
- "TRAVERSE"

##

#### Flags

## Any of

#### NFS4ACE_AdvancedFlags

Type: object
No Additional Properties

##

#### File Inherit

Type: boolean Default: false

##

#### Directory Inherit

Type: boolean Default: false

##

#### No Propagate Inherit

Type: boolean Default: false

##

#### Inherit Only

Type: boolean Default: false

##

#### Inherited

Type: boolean Default: false

#### NFS4ACE_BasicFlags

Type: object
No Additional Properties

##

#### Basic

Type: enum (of string)

##### Must be one of:

- "INHERIT"
- "NOINHERIT"

##

#### Id

Default: null

## Any of

Type: integer

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

Type: null

##

#### Who

Default: null

## Any of

Type: string
Type: string

Must be at least `1` characters long

Type: null

##

#### NFS4ACL_Flags

Type: object
No Additional Properties

##

#### Autoinherit

Type: boolean Default: false

##

#### Protected

Type: boolean Default: false

##

#### Defaulted

Type: boolean Default: false

##

#### Trivial

Type: boolean

#### POSIXACLResult

Type: object
No Additional Properties

##

#### Path

Type: string

Must be at least `1` characters long

##

#### User

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Uid

## Any of

Type: integer

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

Type: null

##

#### Gid

## Any of

Type: integer

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

Type: null

##

#### Acltype

Type: const
Specific value: `"POSIX1E"`

##

#### Acl

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)

##### Must be one of:

- "USER_OBJ"
- "GROUP_OBJ"
- "OTHER"
- "MASK"
- "USER"
- "GROUP"

##

#### POSIXACE_Perms

Type: object
No Additional Properties

##

#### Read

Type: boolean

##

#### Write

Type: boolean

##

#### Execute

Type: boolean

##

#### Default

Type: boolean

##

#### Id

Default: null

## Any of

Type: integer

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

Type: null

##

#### Who

Default: null

## Any of

Type: string
Type: string

Must be at least `1` characters long

Type: null

##

#### Trivial

Type: boolean

#### DISABLED_ACLResult

Type: object
No Additional Properties

##

#### Path

Type: string

Must be at least `1` characters long

##

#### User

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Group

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Uid

## Any of

Type: integer

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

Type: null

##

#### Gid

## Any of

Type: integer

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

Type: null

##

#### Acltype

Type: const
Specific value: `"DISABLED"`

##

#### Acl

Type: null

##

#### Trivial

Type: const
Specific value: `true`

Required roles: FILESYSTEM_ATTRS_WRITE