auristorfs_acls - AuriStor File System Access Control Lists (ACLs)



The AuriStor File System is an AFS3-compatible distributed file system also known as the /afs file namespace. The /afs file namespace is protected by access control lists (ACLs). ACLs can be applied to directories, files, mount points, symlinks and volumes.

AuriStorFS File access control model defines seven access permissions:

This document describes the permissions and the access that is granted when they are included in an access control entry (ACE) on each of the file system object types.

The AuriStor File System Access Control Permissions

Shorthand Notation for Sets of Permissions

You can combine the seven permissions in any way in an ACL entry, but certain combinations are more useful than others. Four of the more common combinations have corresponding shorthand forms. When using the fs setacl command to define ACL entries, you can provide either one or more of the individual letters that represent the permissions, or one of the following shorthand forms:

Using Normal and Negative Permissions

ACLs enable you to both grant and deny access to file system objects. To grant access, use the fs_setacl(1) command to create an access control entry (ACE) that associates a set of permissions with a set of users or groups. When the fs_listacl(1) command displays an ACL, such entries appear underneath the Normal rights header.

There are two ways to deny access:

The recommended method is simply to omit an entry for the user or group from the ACL, or to omit the appropriate permissions from the entry. Use the fs_setacl(1) command to remove or edit an existing entry. In most circumstances, this method is enough to prevent access of certain kinds or by certain users. You must take care, however, not to grant the undesired permissions to any groups to which such users belong.

The more explicit method for denying access is to use the -negative flag to the fs_setacl(1) command to create an entry that associates negative permissions with the user or group. The output from the fs_setacl(1) command lists negative entries underneath the Negative rights header.

When determining what type of access to grant to a user, the File Server first compiles a set of permissions by examining all of the entries in the Normal rights section of the ACL. It then subtracts any permissions associated with the user (or with groups to which the user belongs) on the Negative rights section of the ACL. Therefore, negative permissions always cancel out normal permissions.

Using negative permissions reverses the usual semantics of the fs_setacl(1) command, introducing the potential for confusion. In particular, combining the none shorthand and the -negative flag constitutes a double negative: by removing an entry from the Negative rights section of the ACL, you enable a user once again to obtain permissions via entries in the Normal rights section. Combining the all shorthand with the -negative flag explicitly denies all permissions.

Note also that it is pointless to create an entry in the Negative rights section if an entry in the Normal rights section grants the denied permissions to the system:anyuser group. In this case, users might obtain the permissions simply by using the unlog(1) command to discard their tokens. When they do so, the File Server recognizes them as the anonymous user, who belongs to the system:anyuser group but does not match the entries on the Negative rights section of the ACL. Further note that a negative entry for the anonymous user can be added to the ACL.

Using Groups on ACLs

As previously mentioned, placing a group entry on an ACL enables you to control access for many users at once. You can grant a new user access to many files and directories simply by adding the user to a group that appears on the relevant ACLs. On directories where they have the a (admin) permission on the ACL, users can define their own groups and can create ACL entries for any groups, not just groups that they create or own themselves using the pts_creategroup(1) command.

AuriStorFS also defines the following two system groups, which can be very useful on ACLs because they potentially represent a large group of people.

It is particularly useful to grant the l (lookup) permission to the system:anyuser group on the ACL of most directories in the file system, especially at the upper levels. This permission enables users only to learn the names of files and subdirectories in a directory, but without it they cannot traverse their way through the directories in the path to a target file.

A slightly more restrictive alternative is to grant the l (lookup) permission to the system:authuser group. If that is still not restrictive enough, you can grant the l (lookup) to specific users or groups.

Another reason to grant certain permissions to the system:anyuser group is to enable the correct operation of processes that provide services such as printing and mail delivery. For example, in addition to the l (lookup) permission, a print process possibly needs the r (read) permission in order to access the contents of files, and a mail delivery process possibly requires the i (insert) permission to deliver new pieces of mail.

The ACL on the root directory of every newly created volume grants all permissions to the system:administrators group. You can remove this entry if you wish, but members of the system:administrators group always implicitly have the a (administer), and by default also the l (lookup), permission on every directory's ACL. The a (admin) permission enables them to grant themselves other permissions explicitly when necessary.

Using ACLs on Files, Symlinks and Mount Points

Access Control Lists are optional for files, symlinks and mount points. When an ACL is unassigned, the parent directory's ACL is inherited by the object. The (riwka) permissions apply to files and the (lwka) permissions apply to symlinks and mount points. For symlinks and mount points the l (lookup) permission permits reading the target and status information.

When a cross-directory hard link is created to a file that inherits the directory ACL, the directory ACL will be cloned and assigned to the file. This ensures that identical access permissions will be used when accessing the file regardless of which directory is used.

Non-directory ACLs can be removed using the fs_removeacl(1) provided there are no hard links present. After removal the directory ACL is inherited.

Protecting Data with Volume Maximum ACLs

The AuriStorFS Volume is a policy container for the directory tree that exists within it. The Volume Maximum ACL (MaxACL) is a policy attribute that restricts the rights that can be effectively granted by ACLs assigned to individual objects (directories, files, symlinks and mount points). Instead the MaxACL contrains the rights that can be granted by ACLs assigned to file objects. All file object access must be permitted by both the MaxACL and the ACL that applies to the request file object.

  Effective rights := ACL(Normal & ~Negative) & MaxACL(Normal & ~Negative)

The MaxACL can only be set using the vos_setmaxacl(1) by a user listed in the /etc/yfs/server/UserListExt file or by an account capable of reading the /etc/yfs/server/KeyFileExt file. Normal users and members of the system:administrators group cannot alter the MaxACL. The maximum rights granted on a Volume with no MaxACL assignment are equivalent to the MaxACL with the ACE:

  system:anyuser all

which results in the Effective Rights to be equal to those granted by the file object ACL.

The AuriStorFS User-centric, Constrained Elevation Authorization Model

AuriStorFS implements a User-centric, Constrained Elevation Authorization Model that leverages Combined Identity Authentication and Multi-factor Access Control Lists. This model combined with Volume Security Policies can be used to create Volumes that enforce data classification policies as defined by the deploying organization.

Understanding Combined Identity Tokens

AuriStorFS authentication tokens are used to securely authenticate a user, process or machine to any AuriStorFS service. An AuriStorFS authentication token is similar to a Kerberos v5 service ticket that uses a shared secret to prove mutual authentication between two peers. This token traditionally authenticates a single entity which can be a user, process, service, container, or machine. When a user acquires a token using the aklog(1) command, that token contains an identity sequence of length one.

For example, if a Kerberos v5 realm "YOUR-CELL-NAME.COM" is used to authenticate a cell "" and the user's name is "user", the the acquired token will contain an identity sequence of length one.


The AuriStor File System supports a concept referred to as Combined Identity authentication. A Combined Identity is sequence of entity names which can represent users, services, machines, and other objects that can authenticate to the AuriStor File System by name.

When the yfs-rxgk security class is enabled the Cache Manager can request a Combined Identity Token which securely combines the identity of the user with the identity of the Cache Manager. The Cache Manager identity is typically the identity of the machine. A Combined Identity Token is an authentication token that asserts authentication of an identity sequence.

When an AuriStorFS Cache Manager is installed on a Windows domain joined computer a Combined Identity Token will be acquired. If the domain name is "AD.YOUR-CELL-NAME.COM", the computer's name is "desktop", and the domain user's name is "user", then the token's identity sequence will be.



One benefit of the use of a Combined Identity Token is that the Cache Manager is protected against cache poisoning attacks. In addition, the AuriStorFS services can log all of the authenticated identities.

When the user has not acquired a token, the Cache Manager will acquire a Combined Identity Token for the anonymous user and the cache manager identity. This token permits the cache manager to obtain integrity protection and wire privacy for the otherwise anonymous communication. Using the prior Windows domain as an example, the resulting identity sequence would be:



The "WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS" identity is recognized by the Protection Service as the local cell user "anonymous" that is assigned the AuriStorFS User Number (AUN) 37266.

The first identity in the sequence is the identity used by an AuriStorFS service when evaluating membership in the UserListExt(5) and ReaderList(5) or super user status or file object ownership.

AuriStorFS cache managers installed on UNIX hosts can be assigned an authenticated identity using the keytab option of afsd(8).

Combined Identity Tokens can contain an identity sequence longer than two. As an example, many organizations deploy HTTP or SFTP proxy access to the /afs file namespace. Some organizations might wish to distinguish access via the proxy service which requires the transmission of the user's name and password over a TLS protected channel from access where the user obtains an authentication token directly. A web service such as Filedrawers might be assigned the Kerberos service name "HTTP/" and the service might be running on a machine with a host service principal of "host/" which is used by the cache manager. The Filedrawers service uses an Apache module mod_waklog to acquire tokens for the requesting user. The acquired token can be combined with the Filedrawers service identity before handing the token off to the Cache Manager. The resulting identity sequence could be:


  2. HTTP/

  3. host/

Each of these identities would be written to the audit logs.

As the concept of Container Identity evolves the use of Combined Identity Tokens can be extended to support container deployment and execution.

Using Multi-factor Access Control Entries

A simple or single-factor Access Control Entry (ACE) consists of a single name representing a single entity or a group and a granted set of access permissions.

For example:

  john                          rlw
  system:anyuser                l

The AuriStor File System leverages the Combined Identity authentication to produce a richer set of access control semantics; a user centric, constrained elevation access control model. Each additional identity appended to a Combined Identity sequence can:

An AuriStor File System ACE is specified as an unordered list of user or group names rather than a single name.

For example:

  anonymous,machine-identity            l
  system:authuser,machine-identity      lrk
  group-of-users,group-of-machines      lrw

The a user centric, constrained elevation access control model's ACL evaluation rules are as follows:

  1. The rights granted by an ACL are the sum of the rights granted by the Normal ACEs minus the sum of the rights revoked by the Negative ACEs.

  2. If an ACE matches the Combined Identity sequence then the rights it grants or revokes are added to the appropriate summation.

An ACE matches a Combined Identity sequence when each of the following rules are satisfied by a prefix substring of the Combined Identity sequence:

  1. Every user in the ACE must be present in the prefix substring and every group in the ACE must have a member in the prefix substring.

  2. All of the identities within the prefix substring must contribute to the match. That is, each identity in the prefix substring must match (either by user, or by group) an element of the ACE.

An ACE match is evaluated for each prefix substring of the Combined Identity sequence. That is, start with the prefix substring that is just the primary identity. Then evaluate the prefix substring consisting of the primary and secondary identities. Then the prefix substring consisting of the primary, secondary and tertiary identities, and so on. If an prefix substring matches the ACE, its rights are added to the Normal or Negative summation and the evaluation of the next ACE begins.


What follows are examples of how the user centric, constrained elevation access control model can be used to grant and constrain rights for combined identities.


  Identities and their memberships:
     anonymous          anyuser
     george             anyuser authuser
     jane               anyuser authuser
     john               anyuser authuser admin hr
     pc                 anyuser devices
     ipad               anyuser devices
     ny-net             anyuser networks
     tn-net             anyuser networks
     uk-net             anyuser networks
     ca-net             anyuser networks

    Normal entries:
     authuser           l
     george             lrkwid
     george,pc          lrkwida
     jane               lr
     jane,pc            lrka
     jane,ipad          lrk
     pc                 lrk
     anyuser,devices    l

    Negative entries:
     anyuser,ca-net     lrkwida

  Rights granted to Combined Identity sequences:
     anonymous          none
     george             lrkwid
     jane               lr
     john               l
     pc                 lrk
     ipad               none
     anonymous,pc       l
     george,pc          lrkwida
     jane,pc            lrka
     john,pc            l
     anonymous,ipad     l
     george,ipad        lrkwid
     jane,ipad          lrk
     john,ipad          l

The user centric, constrained elevation model ACL evaluation rules compute the rights for the Combined Identity sequence <jane pc ny-net> by determining the rights granted to each prefix substring and adding them to the appropriate summation.

  Normal entries
  jane (primary)        lr
  jane,pc               lrka
  jane,pc ny-net        none
  Total Positive rights lrka

  Negative entries
  jane (primary)        none
  jane,pc               none
  jane,pc ny-net        none
  Total Negative rights none

  Total rights (lrka & ~none) = "lrka"

If a new Normal ACE is added to the ACL:

     jane,pc,networks   wida

Then the rights granted to each prefix substring become:

  Normal entries
  jane (primary)        lr
  jane,pc               lrka
  jane,pc,ny-net        wida
  Total Positive rights lrkwida

  Total Negative rights none

  Total rights = "lrkwida".

For the Combined Identity seqence <jane ca-net>, the granted rights will be:

  Normal entries
  jane (primary)        lr
  jane,ca-net           none
  Total positive rights lr

  Total egative rights  none

  Total rights = "lr"

In the user centric, constrained elevation model the Combined Identities are a sequence; not an unordered set. Therefore, the position of each identity in the sequence matters. If an organization wishes to provide a group of users enhanced rights when accessing data from the uk-net group of networks as long as the access was from an authenticated device, then it could add the ACE:

     anyuser,devices,uk-net     lrkw

Granting rights to authenticated users on uk-net from an unauthenticated device is:

     authuser,uk-net            lrk

An ACE can also represent a set of groups. For example, the ACE

     admin,hr                   lrkwida

when specifed grants john the full set of permissions because he is a member of both the admin and hr groups.

Negative ACEs in general are discouraged because they can add confusion especially when the group memberships of the primary identity are hard to determine. That being said, negative ACEs are a good fit for the user centric, constrained elevation model when used to deny rights based upon the supplemental identities and their memberships.

For example, a Negative ACE can be added to deny all users connecting through a web service the delete right.

  Negative entries
  anyuser,web-servers   d


If an accessing user has the l (lookup) and i (insert) permissions on a directory, but not the w (write) and/or r (read) permissions, the user is implicitly granted the ability to write and/or read any file they create in that directory, until they close the file. This is to allow "dropbox"-style directories to exist, where users can deposit files, but cannot modify them later nor can they modify or read any files deposited in the directory by other users.

Note, however, that the dropbox functionality is not perfect. The fileserver does not have knowledge of when a file is opened or closed on the client, and so the fileserver always allows an accessing user to read or write to a file in a "dropbox" directory if they own the file. While the client prevents the user from reading or modifying their deposited file later, this is not enforced on the fileserver, and so should not be relied on for security.

Additionally, if "dropbox" permissions are granted to system:anyuser, unauthenticated users may deposit files in the directory. If an unauthenticated user deposits a file in the directory, the new file will be owned by the unauthenticated Auristor User Number (AUN), and is thus potentially modifiable by anyone.

In an effort to try and reduce accidentally publicizing private data, the fileserver may refuse read requests for "dropbox" files from unauthenticated users. As a result, depositing files as an unauthenticated user may arbitrarily fail if system:anyuser has been granted dropbox permissions. While this should be rare, it is not completely preventable, and so for this reason relying on unauthenticated users to be able to deposit files in a dropbox is NOT RECOMMENDED.

IBM AFS and OpenAFS Limitations

IBM AFS and OpenAFS clients and servers are unable to perform Combined Identity authentication. When IBM AFS or OpenAFS clients authenticate to an AuriStor File System server only the primary identity can be asserted.

IBM AFS and OpenAFS servers are unable to store volumes that contain Access Control Lists that cannot be stored as an AFS3 ACL. The AFS3 ACL restrictions are:

IBM AFS and OpenAFS servers are unable to store volumes that have Volume Maximum ACLs assigned to them.

The IBM AFS and OpenAFS vos(1) command do not support Volume Maximum ACL operations.

The IBM AFS and OpenAFS fs(1) command do not support multi-component ACEs nor do they support the assignment of rights to the anonymous identity.


ACLs on Directories, Files, Symlinks and Mount Points

The issuer of the fs_setacl(1) command must have the a (administer) permission on the file object's ACL, be a member of the system:administrators group, or, as a special case, must be the UID owner of the top-level directory of the volume containing the file object. The last provision allows the UID owner of a volume to repair accidental ACL errors without requiring intervention by a member of system:administrators.

Volume Maximum ACLs

The issuer of the vos_setmaxacl(1) command must be listed in the /etc/yfs/server/UserListExt file on the File Server in order to set, modify or remove a Volume Maximum ACL.

The issuer of the vos_listmaxacl(1) command must be listed in the /etc/yfs/server/UserListExt file or the /etc/yfs/server/ReaderList file on the File Server in order to examine a Volume Maximum ACL.


KeyFileExt(5), ReaderList(5), UserListExt(5), afsd(8), fs_getcalleraccess(1), fs_cleanacl(1), fs_copyacl(1), fs_listacl(1), fs_lsmount(1), fs_removeacl(1), fs_setacl(1), pts_creategroup(1), unlog(1), vos_listmaxacl(1), vos_setmaxacl(1)


Copyright AuriStor, Inc. 2014-2021. All Rights Reserved.


"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.