.. _nfsv4_guide:

#########################
Managing NFSv4 ACLs
#########################

An ACL is a list of permissions associated with a file or directory and consists one or more Access Control Entries (ACEs). Each ACE may contain a type, flags, principal and permissions. 

.. image:: images/ACLs.jpg
   :align: center


In some cases the flags are completely optional, and in other cases certain flags are required (e.g. when setting permissions for a group).


ACE Type
---------------

The ACE type defines the type of access granted to users and groups. By default, any permission that is not explicitly allowed is denied.


+------+--------+-------------------------------------------------------------------+
| Type | Name   | Description                                                       |
+------+--------+-------------------------------------------------------------------+
| A    | Access | Allow a user or group to perform actions requiring permissions.   |
+------+--------+-------------------------------------------------------------------+
| D    | Deny   | Prevent a user or group to perform actions requiring permissions. |
+------+--------+-------------------------------------------------------------------+

ACE Flags
-------------

Each ACE may (but not necessarily) contain flags that define special behavior for the entry.

+------+----------------------+-----------------------------------------------------------------------------------------------+
| Flag | Name                 | Description                                                                                   |
+------+----------------------+-----------------------------------------------------------------------------------------------+
| g    | Group                | Indicates that the principal represents a group, not a user.                                  |
+------+----------------------+-----------------------------------------------------------------------------------------------+
| d    | Directory-inherit    | New subdirectories will inherit the ACE                                                       |
+------+----------------------+-----------------------------------------------------------------------------------------------+
| f    | File-inherit         | New files will inherit the ACE except for the d/n/i flags                                     |
+------+----------------------+-----------------------------------------------------------------------------------------------+
| n    | No-propogate inherit | New subdirectories will inherit the ACE except the d/n/i flags                                |
+------+----------------------+-----------------------------------------------------------------------------------------------+
| i    | Inherit-only         | New files and subdirectories will have this ACE but without the permission inheritance flags. |
+------+----------------------+-----------------------------------------------------------------------------------------------+

For example, to define an Access Control Entry for a directory that is inherited by new files and subdirectories within this directory, you may want to use the df flags, e.g.:

.. code-block:: shell

    A:df:netid@crc.nd.edu:rxtncy


ACE Principal
-------------------

The principal defines the people that the entry is allowing access to. The principal can be a user, group or special principal:

* **User:** netid@crc.nd.edu

* **Group:** ndgroup-1@crc.nd.edu

* **Special principals:**
    * OWNER@
    * GROUP@
    * EVERYONE@

.. warning::

    When the principal is a group, the g flag for the entry needs to be used, e.g.: ``A:g:ndgroup-1@crc.nd.edu:rxtncy``


ACE Permissions
---------------------

NFSv4 ACLs provides many different permission types to define permissions for files and directories. These permission types can be used in any combination. 

In this documentation we are only focusing on the Read, Write and Execute permissions. The R, W and X aliases can be used to provide read, write and execute permissions, respectively. These are also a combination of the different permission types.

+-------+---------+--------------------------------------------+
| Alias | Name    | Expansion                                  |
+-------+---------+--------------------------------------------+
| R     | Read    | rntcy                                      |
+-------+---------+--------------------------------------------+
| W     | Write   | watTNcCy (with D added to directory ACE's) |
+-------+---------+--------------------------------------------+
| X     | Execute | xtcy                                       |
+-------+---------+--------------------------------------------+

Checking the ACLs
----------------------

The ACLs can be checked using the **nfs4_getfacl**.


.. code-block:: shell

    $ nfs4_getfacl /groups/ndgroup/
    # file: /groups/ndgroup/
    A:fdg:ndgroup-1@crc.nd.edu:rwaDxtTnNcCy
    A:fdg:ndgroup-2@crc.nd.edu:rxtncy
    A:fdg:crcsupport@crc.nd.edu:rxtncy

In this example ndgroup-1 has Read, Write and eXecute, and the ndgroup-2 and crcsupport has Read and eXecute permissions.


.. warning::

    Please note that only the owner of the file/directory and system administrators can add, remove and change the ACLs of a file or directory.


Setting ACLs on files and directories
-----------------------------------------

The NFSv4 ACLs can be set for directories or files by using the **nfs4_setfacl** command. 

.. code-block:: shell

    # Give ndgroup-1 read and execute permissions recursively to the folder /groups/ndgroup/shared:
    nfs4_setfacl -R -a A:dfg:ndgroup-1@crc.nd.edu:RX /groups/ndgroup/shared

    # Give ndgroup read, write and execute permissions recursively to the folder /groups/ndgroup/shared:
    nfs4_setfacl -R -a A:dfg:ndgroup-1@crc.nd.edu:RWX /groups/ndgroup/shared

    # Give nduser read and execute permissions recursively to the folder /groups/ndgroup/shared:
    
    nfs4_setfacl -R -a A:df:nduser@crc.nd.edu:RX /groups/ndgroup/shared
    
    # Give nduser read, write, write and execute permissions recursively to the folder /groups/ndgroup/shared:
    
    nfs4_setfacl -R -a A:df:nduser@crc.nd.edu:RWX /groups/ndgroup/shared

    # Revoke nduser's read, write, write and execute permissions recursively to the folder /groups/ndgroup/shared:

    nfs4_setfacl -R -x A:df:nduser@crc.nd.edu:RWX /groups/ndgroup/shared 

The nfs4_setfacl command provides other useful options to change the ACLs:

+--------------------+-----------------------------------------------------------+
| **Option**         | **Function**                                              |
+--------------------+-----------------------------------------------------------+
| -i index           | use the entry-at-index from ACL (only for add and remove) |
+--------------------+-----------------------------------------------------------+
| -e directory/file  | edit ACL in $EDITOR (DEFAULT: vi)                         |
+--------------------+-----------------------------------------------------------+
| -A directory/file  | read ACL entries to add from file                         |
+--------------------+-----------------------------------------------------------+
| -X directory/file  | read ACL entries to remove from file                      |
+--------------------+-----------------------------------------------------------+
| -s acl_spec        | set ACL to acl_spec (replaces existing ACL)               |
+--------------------+-----------------------------------------------------------+
| -S directory/file  | read ACL entries to set from file                         |
+--------------------+-----------------------------------------------------------+
| -m from_ace to_ace | modify in-place: replace 'from_ace' with 'to_ace'         |
+--------------------+-----------------------------------------------------------+