NFS Exports with Multiple IP Restrictions and User Mappings

IN THIS ARTICLE

Outlines how to create NFS Exports with multiple IP restrictions and user mappings

REQUIREMENTS

• Cluster running Qumulo Core version 2.0 and above for user mapping to local Qumulo user accounts
• Cluster running Qumulo Core version 2.7.8 and above for user mapping to discretionary UID & GID numbers
• Command line (CLI) tools installed via API & Tools tab

GLOSSARY

UID: User Identity Number (uidNumber) used to identify NFS users

GID: Group Identity Number (gidNumber) used to identify NFS user groups

Host: The IP address of the system running the NFS client software connecting to the Qumulo File System

Subnet: A network segment encompassing multiple hosts

Export: An NFS access mount point to the Qumulo File System as defined by the Qumulo administrator

DETAILS

IP RESTRICTIONS

IP restrictions allow access control to a particular NFS export to only the IP addresses of the hosts on an access list. A range of IP addresses or entire subnets can be specified in the access list and any connection attempts coming from an IP address not covered in the access list will be denied access.

The IP restrictions will be enforced in the order they are written from top to bottom. Once a condition is met then that rule is applied. Be aware of this behavior as you create your list of rules. To prevent unintended results, list IP-specific rules at the top of the list and Subnet-wide rules at the bottom.

USER MAPPING

User Mapping (or User Squashing) is the process of converting the incoming UID of an NFS user into the UID Number specified in the NFS export's settings. When NFS operations are performed on an export with User Mapping enabled, those operations will be performed as the UID/GID specified in the export's settings. 

User Mapping is possible for two types of users:

• Root or UID 0
• All other users / UIDs

Note that Root or UID 0 is the only individual user to whom specific rules can be applied. Every other non-Root UID will be handled by the All set of rules. Using the All value in the user_mapping key, all non-root incoming UID values will be remapped to the desired UID/GID value to ensure consistent file ownership.

User Mapping will require the creation on a local user account via the API or the Web UI and the assignment of a UID value for that user. 

To create a user via the API: 

qq auth_add_user --name (User Name) --uid (UID number) --primary-group ( Qumulo local group ID number) -p (Password)

• example: qq auth_add_user --name Joe --uid 2011 --primary-group 513 -p (Note: Leaving a blank value after -p prompts for a password after the command is run.)

To list available groups or to create a new group via the API, use the commands below.

• qq auth_list_groups
• qq auth_add_group --name --gid

Reference the QQ CLI: Admins, Users and Groups article for additional details.

IMPORTANT: User Mapping options vary depending on the version of Qumulo Core. For clusters running versions 2.0 through 2.7.0 of Qumulo Core, User Mapping is only available to local Qumulo accounts. Qumulo Core 2.7.8 and above supports User Mapping to local Qumulo accounts or any discretionary UID/GID value.

ROOT SQUASHING

Whenever an NFS user is logged in as local Root or performs a file operation as a sudoer, UID 0 is sent over NFS as the user identity. This would normally grant the NFS user the same rights as the local Qumulo Admin including the ability to read, delete and modify any object in the File System.

Root Squashing is enabled via the root or 0 value in the user_mapping key. With Root Squashing, this UID is remapped to the desired value to prevent unauthorized root access to an NFS Export, to specific Hosts and Subnets or to ensure consistent file ownership.

Through using IP restrictions, it is possible to create a list that allows specific Hosts to act as Root/Sudoers while restricting all other Hosts.

QQ COMMANDS

The following QQ commands are available to manage NFS exports via the Qumulo API: 

qq nfs_add_export

qq nfs_delete_export

qq nfs_get_export

qq nfs_list_exports

qq nfs_mod_export

qq nfs_mod_share

NOTE: NFS exports with multiple IP and user restrictions applied can only be deleted using the nfs_delete_export --id command.

JSON RESTRICTIONS FILE

The application of IP restrictions and User mapping rules requires the creation of a JSON file including the following keys to be referenced by the qq nfs_mod_share (2.7.7 and below) or qq nfs_mod_export (2.7.8 and above) command.

read_only: Input True or false value to determine whether the NFS export is writeable or read-only

host_restrictions: List of IPs and Subnets (individual IPs before subnets) that are allowed access to the export

• IPs not covered in any host_restrictions key in the JSON file will be denied access

user_mapping: List of incoming UIDs to be remapped 

• root - Intercepts only incoming UID 0 and remaps it
• all - Every incoming UID will be remapped
• none - No UIDs are remapped and only Host restrictions are enforced. If the key value "none" is selected then it is not necessary to add a map_to_user_id key.

map_to_user_id: Select what Local User (case sensitive) that incoming UIDs covered in the user_mapping key will be remapped to. 

Please note that multiple JSON objects (Groups of complete restriction rules) need to be separated by a comma after the object’s closing curly brace as outlined in the example below.

{
 "restrictions": [
 {
 "read_only": true,
 "host_restrictions": [ "10.120.252.12", "10.120.253.0/24" ],
 "user_mapping": "all",
 "map_to_user_id": "admin"
 },
 {
 "read_only": false,
 "host_restrictions": [ "10.120.250.0/24" ],
 "user_mapping": "root",
 "map_to_user_id": "guest"
 }
 ]
}

This sample JSON file indicates the following:

• UIDs coming from Host 10.120.252.12 and Subnet 10.120.253.0/24 should be remapped to Local User admin
• UID 0 coming in via Subnet 10.120.250.0/24 will be remapped to Local Built-In User Guest, effectively preventing the use of a Root account or sudo actions from any user in this Subnet inside of this Export
• This JSON file also indicates that a Host coming from any IP or Subnet not covered in one of the two host_restrictions keys will be denied access to this Export

MANAGING NFS EXPORTS WITH QUMULO CORE VERSION 2.7.8 AND ABOVE

Qumulo Core Version 2.7.8 introduces the ability to directly remap incoming UIDs to discretionary UIDs and GIDs without the requirement of creating a Local User in advance.

Qumulo Core version 2.7.8 introduces a new method for mapping incoming UID and GIDs directly to another UID and GID without the need of creating a Local User account:

• map_to_user: {"id_type": "NFS_UID", "id_value": "###"}
• map_to_group: {"id_type": "NFS_GID", "id_value": "###"}

{
 "restrictions": [
 {
 "host_restrictions": ["10.120.252.10"],
 "read_only": false, 
 "user_mapping": "all",
 "map_to_user": {"id_type": "LOCAL_USER", "id_value": "guest"}
 },
 {
 "host_restrictions": ["10.120.253.20","10.120.253.21"],
 "read_only": false,
 "user_mapping": "none"
 },
 {
 "host_restrictions": ["10.120.253.0/24"],
 "read_only": false,
 "user_mapping": "root",
 "map_to_user": {"id_type": "NFS_UID", "id_value": "994"},
 "map_to_group": {"id_type": "NFS_GID", "id_value": "994"}
 }
 ]
}

This sample JSON file indicates that:

• Host 10.120.252.10 will have any incoming UID mapped to Local User guest
• Host 10.120.253.20 will not be subjected to any UID remapping and use the UID as provided by the NFS client
• Subnet 10.20.253.0/24 will have any incoming UID 0 users remapped to UID 994 and GID 994

APPLY THE RESTRICTIONS

Implementing the restrictions to the NFS export(s) can be done in multiple ways. To create an NFS export with restrictions via the API, use the command below.

qq nfs_add_export --export-path / --fs-path / --restrictions /path/to/restrictions.json

To apply a list of restrictions to an existing NFS export, first retrieve the share ID from the list of exports using the following command:

qq nfs_list_exports

Modify the NFS export using the ID and path to the restricitons.json:

qq nfs_mod_export --id 5 --restrictions /path/to/restrictions.json

The application of a restrictions JSON file requires the use of the qq nfs_mod_export command for 2.7.8 and above. For version 2.7.7 and below, use qq nfs_mod_share to apply the NFS restrictions.

Once the rules have been applied, the JSON file is no longer required and can be deleted or saved elsewhere for your own documentation.

VERIFY NFS RESTRICTIONS

To verify the restriction from an NFS client, use the showmount command below:

showmount -e ip.of.qumulo.node (Or FQDN of cluster)

Example output:

showmount -e 10.120.249.58
Exports list on 10.120.249.58:
/ Everyone
/admin_files 10.220.246.80 10.0.0.0/10
/files Everyone
/replicate 10.120.253.21 10.120.253.0/24

VERIFY NFS RESTRICTIONS FROM THE QUMULO API 

To verify restriction from the Qumulo API, use the following qq command:

qq nfs_list_exports

Example output:

qq nfs_list_exports
[
    {
       "description": "",
       "export_path": "/",
       "fs_path": "/",
       "id": "1",
       "restrictions": [
           {
               "host_restrictions": [],
               "map_to_user_id": "0",
               "read_only": false,
               "user_mapping": "NFS_MAP_NONE"
           }
       ]
    },
    {
       "description": "",
       "export_path": "/Home",
       "fs_path": "/users/Home",
       "id": "7",
       "restrictions": [
           {
              "host_restrictions": [],
              "map_to_user_id": "0",
              "read_only": false,
              "user_mapping": "NFS_MAP_NONE"
           }
       ]
     }

RESOLUTION

You should now be able successfully create NFS Exports with multiple IP restrictions and user mappings

ADDITIONAL RESOURCES

QQ CLI: NFS Exports

QQ CLI: Admins, Users and Groups

Like what you see? Share this article with your network!