Cross-Protocol (XPP) Explain Permissions Tools

REQUIREMENTS

Qumulo Core 2.11.4 or later
Cross-Protocol Permissions (XPP) enabled

For an in-depth look at this new feature, check out the Cross-Protocol Permissions (XPP) article.

PROCESS

Explain Permissions Tools is a suite of utilities which can examine a given file or directory, and break down how permissions sets were derived. The tool performs an annotated ACE-by-ACE ACL evaluation and mode evaluation.

There are three QQ CLI commands available with this tool that can help you identify how your file permissions have been determined.

Explain POSIX Mode Permissions

To determine how Qumulo produced the displayed POSIX mode from a file's ACL, you can use the following command with the file ID or path:

qq fs_acl_explain_posix_mode --path /PATH
qq fs_acl_explain_posix_mode --file id ID

In doing so, it breaks down the ACL, annotating each entry and showing how it contributes to the final POSIX mode assigned.

Reference the example below to see how the command enables you to review the derived permissions for the root folder:

admin@qumulo-1:~$ qq fs_acl_explain_posix_mode --path /
Permissions Mode: Cross protocol
Owner: admin
Group: Users

==== ACL ====
Control: Present
Posix Special Permissions: None

Permissions:
ID Trustee Type Flags Rights
== ================ ======= ===== =====================================================
1 File Owner Allowed Delete child, Execute/Traverse, Read, Write directory
2 File Group Owner Allowed Delete child, Execute/Traverse, Read, Write directory
3 Everyone Allowed Delete child, Execute/Traverse, Read, Write directory

Mode derivation from ACL for "/":

==== 1 ====
Allowed File Owner Delete child, Execute/Traverse, Read, Write directory
 Matched: OWNER
 Cumulative rights allowed:
 Owner: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Group: None
 Other: None
 Mode Bit Contribution: rwx------

==== 2 ====
Allowed File Group Owner Delete child, Execute/Traverse, Read, Write directory
 Matched: GROUP
 Potentially affects rights for: OWNER
 Cumulative rights allowed:
 Owner: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Group: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Other: None
 Mode Bit Contribution: rwxrwx---

==== 3 ====
Allowed Everyone Delete child, Execute/Traverse, Read, Write directory
 Matched: EVERYONE
 Cumulative rights allowed:
 Owner: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Group: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Other: Delete child, Execute/Traverse, Read, Synchronize, Write directory
 Mode Bit Contribution: rwxrwxrwx

Final Derived Mode: drwxrwxrwx

Explain CHMOD Permissions

Use the following command to run a ‘what-if’ simulation of the effects of setting a POSIX mode (a chmod) on the ACL of a given file:

qq fs_acl_explain_chmod --path /PATH --mode MODE
qq fs_acl_explain_chmod --file id ID --mode MODE

The command takes the desired POSIX mode, then produces a step-by-step explanation of how the file’s ACL would be affected by the chmod. Running this command provides a preview and does not actually change the permissions of the file in question.

The example shown below indicates what would happen if you attempted to modify the permissions in the specified path to Mode 0644 (mode can be specified as either a numeric entry or manually via specifying in a string) as shown here:

admin@qumulo-1:~$ qq fs_acl_explain_chmod --path / --mode rw-r--r--
Permissions Mode: Cross protocol
Owner: admin
Group: Users

==== ACL ====
Control: Present
Posix Special Permissions: None

Permissions:
ID Trustee Type Flags Rights
== ================ ======= ===== =====================================================
1 File Owner Allowed Delete child, Execute/Traverse, Read, Write directory
2 File Group Owner Allowed Delete child, Execute/Traverse, Read, Write directory
3 Everyone Allowed Delete child, Execute/Traverse, Read, Write directory

Mode 0644 translates to rights:
 owner: Read, Synchronize, Write EA, Write attr
 group: Read, Synchronize
 other: Read, Synchronize

Steps for applying mode 0644 to original permissions:
==== 1 ====
Action: Insert entry
New entry: Allowed local:admin Read, Write EA, Write attr
Reason: Add rights granted by requested mode.

==== 2 ====
Action: Insert entry
New entry: Allowed local:Users Read
Reason: Add rights granted by requested mode.

==== 3 ====
Action: Insert entry
New entry: Allowed Everyone Read
Reason: Add rights granted by requested mode.

==== 4 ====
Action: Remove entry
Source entry: Allowed File Owner Delete child, Execute/Traverse, Read, Write directory
Trustee match: 'File Owner' matches POSIX owner
Reason: Remove old POSIX trustee ACE to replace with rights from the requested mode.

==== 5 ====
Action: Remove entry
Source entry: Allowed File Group Owner Delete child, Execute/Traverse, Read, Write directory
Trustee match: 'File Group Owner' matches POSIX group owner
Reason: Remove old POSIX trustee ACE to replace with rights from the requested mode.

==== 6 ====
Action: Remove entry
Source entry: Allowed Everyone Delete child, Execute/Traverse, Read, Write directory
Trustee match: 'Everyone' matches POSIX others
Reason: Remove old POSIX trustee ACE to replace with rights from the requested mode.

==== Resulting ACL ====
Control: Present
Posix Special Permissions: None

Permissions:
ID Trustee Type Flags Rights
== =========== ======= ===== ==========================
1 local:admin Allowed Read, Write EA, Write attr
2 local:Users Allowed Read
3 Everyone Allowed Read

Explain User Rights

To review how the rights are granted to a given user for a specified file, you can run the following command:

qq fs_acl_explain_rights --path /PATH -u USER -p PRIMARY GROUP  
qq fs_acl_explain_rights --file ID ID -u USER -p PRIMARY GROUP

The command takes a file ID or path and a user/group identifier (user, primary group), then breaks down the ACL, explaining how each ACE affects the rights of the user/group in question. See the example below:

admin@qumulo-1:~$ qq fs_acl_explain_rights --path / -u admin -p admin
File Owner: admin
File Group Owner: Users

ACL evaluation steps for 'admin':
==== 1 ====
 Entry: Allowed 'File Owner' Delete child, Execute/Traverse, Read, Write directory
 Trustee Matches: True
 Allowed so far: Delete child, Execute/Traverse, Read, Synchronize, Write directory
==== 2 ====
 Entry: Allowed 'File Group Owner' Delete child, Execute/Traverse, Read, Write directory
 Trustee Matches: False
==== 3 ====
 Entry: Allowed 'Everyone' Delete child, Execute/Traverse, Read, Write directory
 Trustee Matches: True
 Allowed so far: Delete child, Execute/Traverse, Read, Synchronize, Write directory

Implicit Rights for 'admin':
 Administrator rights: All
 File Owner rights: Read, Write ACL, Write file, Write group
 Parent Directory rights: None

Rights that would be granted to 'admin':
 Read contents (Read file data or list directory)
 Read EA (Read extended attributes)
 Read attr (Read attributes)
 Read ACL (Read access control list)
 Write EA (Write extended attributes)
 Write attr (Write attributes)
 Write ACL (Write access control list)
 Change owner (Change file owner)
 Write group (Change file group-owner)
 Delete (Delete this object)
 Execute/Traverse (Execute file or traverse directory)
 Write data (Modify file data)
 Extend file (Append to file)
 Add file (Add file to directory)
 Add subdir (Add directory to directory)
 Delete child (Delete any of a directory's immediate children)
 Synchronize (Meaningless, exists for compatibility)

NOTE: This command does not discover the user's groups and related identities when computing rights. To provide this information, use one of the group arguments (-g).

For additional details on any of the commands above, include -h after the command to access the qq CLI help menu.