nfsv4 aces/acls

Author: s-sajid-ali

docs/hpc/03_storage/08_sharing_data_on_hpc.md

@@ -17,7 +17,7 @@ An Access Control List is composed of Access Control Entries, each of which has
 | :------- | :---------- |
 | *type*   | Kind of ACE entry, we recommend only using A (access). Deny type entries make the ACE more complex to reason about when compared to using only access type entries for the same configuration. |
 | *flags*  | Inheritance flags which apply to directories and control how ACEs are inherited:<br/>- **`f`**: files inherit ACEs, but inheritance flags are not set on the files<br/>- **`d`**: directories inherit both the ACE and the inheritance flags<br/>- **`i`**: only inherit the inheritance flags, ACEs do not apply to this directory<br/>- **`n`**: directories only inherit ACEs, not the inheritance flags<br/>- **`g`**: only used when the principal is a group |
-| *principal* | The user or group to apply the ACE to, with the following special principals:<br/>- **`OWNER`**<br/>- **`GROUP`**<br/>- **`EVERYONE`** |
+| *principal* | The user (identified by `NetID`) or group to apply the ACE to, with the following special principals:<br/>- **`OWNER`**<br/>- **`GROUP`**<br/>- **`EVERYONE`** |
 | *permissions* | The level of access to grant. Aliases for most common uses include: the full set of permission entry types are listed below for reference, with the most commonly used options being:<br/>- **`R`**: Read, alias for `rntcy`<br/>- **`W`**: Write, alias for `watTNcCy`<br/>- **`X`**: Execute, alias for `watTNcCy` <br/> The full list of available options can be found [here](https://man7.org/linux/man-pages/man5/nfs4_acl.5.html).|
 
 
@@ -26,3 +26,34 @@ The following commands are available:
 -   `nfs4_setfacl` to set ACEs
 -   `nfs4_editfacl` to edit ACEs
 -   `nfs4_getfacl` to view ACLs
+with the usage described in the following examples.
+
+#### Give someone access to read a particular file
+Append the ACL for that file by adding an ACE via 
+```sh
+nfs4_setfacl -a "A::NetID:R" filename
+```
+where the `-a` flag signifies "append". Since inheritance flags are only applicable to directories and the principal is not a group, no flags are needed.
+
+#### Show current access properties
+
+Create an empty file and viwe the default ACEs it:
+```sh
+~> touch temp
+~> nfs4_getfacl temp 
+# file: temp
+A::OWNER@:rwatTnNcy
+A:g:GROUP@:rtncy
+A::EVERYONE@:rtncy
+``` 
+View changes after granting a collaborator read permissions:
+```sh
+~> nfs4_setfacl -a "A::collaborator-netid:R" temp 
+~> nfs4_getfacl temp
+# file: temp
+A::collaborator-netid@hpc.nyu.edu:rtncy
+A::OWNER@:rwatTnNcy
+A:g:GROUP@:rtncy
+A::EVERYONE@:rtncy
+```
+where `collaborator-netid` refers to the `NetID` of your collaborator.