Skip to content

Commit 154e80c

Browse files
s-sajid-alis-sajid-ali
authored
Merge pull request #248 from NYU-RTS/nfsv4-facl
NFSv4 ACE/ACLs
2 parents 6583107 + de1f9f1 commit 154e80c

File tree

1 file changed

+40
-149
lines changed

1 file changed

+40
-149
lines changed

‎docs/hpc/03_storage/08_sharing_data_on_hpc.md‎

Lines changed: 40 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,59 @@
11
# Sharing Data on HPC
22

33
## Introduction
4-
To share files on the cluster with other users, we recommend using file access control lists (FACL) for a user to share access to their data with others. FACL mechanism allows a fine-grained control access to any files by any users or groups of users. We discourage users from setting `777` permissions with `chmod`, because this can lead to data loss (by a malicious user or unintentionally, by accident). Linux commands `getfacl` and `setfacl` are used to view and set access.
4+
To share files on the cluster with other users, we recommend using NFSv4 Access Control Lists (ACL) for a user to share access to their data with others. NFSv4 ACL mechanism allows for fine-grained control access to any files by any users or groups of users. We discourage users from setting `777` permissions with `chmod`, because this can lead to data loss (by a malicious user or unintentionally, by accident).
55

6-
ACL mechanism, just like regular Linux POSIX, allows three different levels of access control:
7-
8-
- Read (r) - the permission to see the contents of a file
9-
- Write (w) - the permission to edit a file
10-
- eXecute (X) - the permission to call a file or run it (in this case we use X instead of x because the X permission uses inherited executable permissions and not all files need execution)
11-
12-
This level of access can be granted to
13-
14-
- user (owner of the file)
15-
- group (owner group)
16-
- other (everyone else)
17-
18-
ACL allows to grant the same type access without modifying file ownership and without changing POSIX permissions.
19-
20-
## Viewing ACL
21-
Use `getfacl` to retrieve access permissions for a file.
22-
```sh
23-
$ getfacl myfile.txt
24-
# file: myfile.txt
25-
# owner: ab123
26-
# group: users
27-
user::rw-
28-
group::---
29-
other::---
30-
```
31-
The example above illustrates that in most cases ACL looks just like the chmod-based permissions: owner of the file has read and write permission, members of the group and everyone else have no permissions at all.
32-
33-
34-
## Setting ACL
35-
Modify access permissions
36-
Use setfacl:
37-
38-
```sh
39-
# general syntax:
40-
$ setfacl [option] [action/specification] file
41-
42-
# most important options are
43-
# -m to modify ACL
44-
# -x to remove ACL
45-
# -R to apply the action recursively (apply to everything inside the directory)
46-
47-
# To set permissions for a user (user is either the user name or ID):
48-
$ setfacl -m "u:user:permissions" <file/dir>
49-
50-
## To set permissions for a group (group is either the group name or ID):
51-
$ setfacl -m "g:group:permissions" <file/dir>
52-
53-
# To set permissions for others:
54-
$ setfacl -m "other:permissions" <file/dir>
55-
56-
# To allow all newly created files or directories to inherit entries from the parent directory (this will not affect files which will be copied into the directory afterwards):
57-
$ setfacl -dm "entry" <dir>
58-
59-
# To remove a specific entry:
60-
$ setfacl -x "entry" <file/dir>
61-
62-
# To remove the default entries:
63-
$ setfacl -k <file/dir>
64-
65-
# To remove all entries (entries of the owner, group and others are retained):
66-
$ setfacl -b <file/dir>
67-
```
68-
69-
:::tip
70-
Give Access to Parent Directories in the Path
71-
When you would like to set ACL to say `/a/b/c/example.out`, you also need to set appropriate ACLs to all the parent directories in the path. If you want to give read/write/execute permissions for the file `/a/b/c/example.out`, you would also need to give at least r-x permissions to the directories: `/a`, `/a/b`, and `/a/b/c`.
6+
:::info
7+
Torch supports NFSv4 ACLs rather than the POSIX ACLs supported by Greene! NFSv4 ACLs allow for more fine grained control when compared to POSIX ACLs.
728
:::
739

74-
### Remove All ACL Entries
75-
```sh
76-
$ setfacl -b abc
10+
### Anatomy of an Access Control Entry
11+
An Access Control List is composed of Access Control Entries, each of which has the following structure:
7712
```
78-
79-
### Check ACLs
80-
```sh
81-
$ getfacl abc
82-
# file: abc
83-
# owner: someone
84-
# group: someone
85-
user::rw-
86-
group::r--
87-
other::r--
88-
```
89-
90-
You can see with `ls -l` if a file has extended permissions set with setfacl: the `+` in the last column of the permissions field indicates that this file has detailed access permissions via ACLs:
91-
```sh
92-
$ ls -la
93-
total 304
94-
drwxr-x---+ 18 ab123 users 4096 Apr 3 14:32 .
95-
drwxr-xr-x 1361 root root 0 Apr 3 09:35 ..
96-
-rw------- 1 ab123 users 4502 Mar 28 22:27 my_private_file
97-
-rw-r-xr--+ 1 ab123 users 29 Feb 11 23:18 dummy.txt
13+
[type]:[flags]:[principal]:[permissions]
9814
```
9915

100-
### Flags
101-
Please read `man setfacl` for possible flags. For example:
16+
| Property | Description |
17+
| :------- | :---------- |
18+
| *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. |
19+
| *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 |
20+
| *principal* | The user (identified by `NetID`) or group to apply the ACE to, with the following special principals:<br/>- **`OWNER`**<br/>- **`GROUP`**<br/>- **`EVERYONE`** |
21+
| *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).|
10222

103-
- '-m' - modify
104-
- '-x' - remove
105-
- '-R' - recursive (apply ACL to all content inside a directory)
106-
- '-d' - default (set given settings as default - useful for a directory - all the new content inside in the future will have given ACL)
10723

108-
## Examples
109-
### File ACL Example
110-
Set read, write, and execute (rwX) permissions for user johnny to file named abc:
111-
```sh
112-
$ setfacl -m "u:johnny:rwX" abc
113-
```
114-
115-
:::note
116-
We recommend for the permissions using a capital 'X' as using a lowercase 'x' will make all files executable, so we reommcned this:
24+
### Creating and Applying ACLs
25+
The following commands are available:
26+
- `nfs4_setfacl` to set ACEs
27+
- `nfs4_editfacl` to edit ACEs
28+
- `nfs4_getfacl` to view ACLs
29+
with the usage described in the following examples.
11730

118-
Check permissions:
31+
#### Give someone access to read a particular file
32+
Append the ACL for that file by adding an ACE via
11933
```sh
120-
$ getfacl abc
121-
# file: abc
122-
# owner: someone
123-
# group: someone
124-
user::rw-
125-
user:johnny:rwX
126-
group::r--
127-
mask::rwX
128-
other::r--
34+
nfs4_setfacl -a "A::NetID:R" filename
12935
```
36+
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.
13037

131-
Change permissions for user johnny:
132-
```sh
133-
$ setfacl -m "u:johnny:r-X" abc
134-
```
38+
#### Show current access properties
13539

136-
Check permissions:
40+
Create an empty file and view the default ACEs it:
13741
```sh
138-
$ getfacl abc
139-
# file: abc
140-
# owner: someone
141-
# group: someone
142-
user::rw-
143-
user:johnny:r-X
144-
group::r--
145-
mask::r-X
146-
other::r--
147-
```
148-
:::
149-
150-
### Directory ACL Example
151-
Let's say alice123 wants to share directory `/scratch/alice123/shared/researchGroup/group1` with user `bob123`
42+
~> touch temp
43+
~> nfs4_getfacl temp
44+
# file: temp
45+
A::OWNER@:rwatTnNcy
46+
A:g:GROUP@:rtncy
47+
A::EVERYONE@:rtncy
48+
```
49+
View changes after granting a collaborator read permissions:
15250
```sh
153-
## Read/execute access to /scratch/alice123
154-
setfacl -m u:bob123:r-X /scratch/alice123
155-
## Read/execute access to /scratch/alice123/shared
156-
setfacl -m u:bob123:r-X /scratch/alice123/shared
157-
## Read/execute access to /scratch/alice123/shared/researchGroup
158-
setfacl -m u:bob123:r-X /scratch/alice123/shared/researchGroup
159-
## Now I can finally can give access to directory /scratch/alice123/shared/researchGroup/group1
160-
setfacl -Rm u:bob123:rwX /scratch/alice123/shared/researchGroup/group1
51+
~> nfs4_setfacl -a "A::collaborator-netid:R" temp
52+
~> nfs4_getfacl temp
53+
# file: temp
54+
A::[email protected]:rtncy
55+
A::OWNER@:rwatTnNcy
56+
A:g:GROUP@:rtncy
57+
A::EVERYONE@:rtncy
16158
```
162-
:::note
163-
user bob123 will be able to see content of the following directories
164-
165-
- `/scratch/alise123/`
166-
- `/scratch/alise123/shared`
167-
- `/scratch/alise123/shared/researchGroup/`
168-
- `/scratch/alise123/shared/researchGroup/group1`
59+
where `collaborator-netid` refers to the `NetID` of your collaborator.

0 commit comments

Comments
 (0)