SMB Share Permissions

IN THIS ARTICLE 

This article explains how you can create, modify, and view SMB share permissions in Qumulo Core.

REQUIREMENTS

• A cluster running Qumulo Core 2.9.6 (or higher)
• Administrative privileges for the cluster

TIP: In Qumulo Core 2.11.1 (or higher), you can manage SMB Share permissions using the Web the UI. For more information, see Create an SMB Share.

DETAILS 

Qumulo Core 2.9.6 (or higher) supports SMB share-level permissions that provide an alternative method for managing access to items in an SMB share. Share-level permissions let administrators set access permissions on the SMB share itself. Administrators can specify users and groups and designate access for each from an Active Directory service, an LDAP server, or a local Qumulo user account by using the API.

IMPORTANT: When configured, actual access is determined by combining share and file permissions to enforce the most restrictive combination of the two. 

You can manage SMB shares using new API endpoints that let you create or modify shares and permissions. To create, modify, and view SMB share-level permissions, see the following qq CLI examples. 

NOTE: You can still use legacy REST APIs. However, these methods are limited to controlling only read-only and allow-guest-access modes.

TIP: To request JSON output, use the --json flag with any of the following commands.

To Create an SMB Share

1. To create a new share, specify the name, directory path from the root of the Qumulo file system, and explicit access permissions, for example:

   qq smb_add_share --name grumpquat --fs-path /grumpquat --all-access
   
   ID: 1663
   Name: grumpquat
   Path: /grumpquat
   Description:
   Access Based Enumeration: False
   Default File Create Mode: 0644
   Default Directory Create Mode: 0755
   
   Permissions:
   ID Trustee Type Rights
   == ======== ======= ===============================
   1 Everyone Allowed Read, Write, Change permissions

2. If the directory doesn't exist already, add --create-fs-path to the command, for example:

   qq smb_add_share --name grumpquat --fs-path /grumpquat --all-access --create-fs-path
   
   ID: 1661
   Name: grumpquat
   Path: /grumpquat
   Description:
   Access Based Enumeration: False
   Default File Create Mode: 0644
   Default Directory Create Mode: 0755
   
   Permissions:
   ID Trustee Type Rights
   == ======= ==== ======

   IMPORTANT: Before Qumulo Core 2.10.1, the default behavior is creating an empty access control list (ACL) that grants no access to anyone. In Qumulo Core 2.10.1 (and higher), you must specify explicit permissions when you create a new share. If you don't specify these permissions, the following error message appears.

   Command error: Must specify initial permissions (--no-access, --read-only, --all-access, --grant-read-access, etc.)

3. To grant full control to every role, including Guest, specify the name, directory path from the root of the Qumulo file system, and the role permissions for a new share, for example:

   qq smb_add_share --name grumpquat --fs-path /grumpquat --grant-all-access Everyone Guest
   
   ID: 1662
   Name: grumpquat
   Path: /grumpquat
   Description:
   Access Based Enumeration: False
   Default File Create Mode: 0644
   Default Directory Create Mode: 0755
   
   Permissions:
   ID Trustee Type Rights
   == ======== ======= ===============================
   1 Everyone Allowed Read, Write, Change permissions
   2 Guest Allowed Read, Write, Change permissions

Modifying an SMB Share's Permissions

To modify the permissions of an existing SMB share for a Qumulo Core 2.10.0 (or higher) cluster, use the --id or --name parameter with the smb_mod_share_permissions command.

TIPS:

• To verify the Qumulo ID of the SMB share that you want to modify, run the smb_list_shares command.
• In Qumulo Core 2.10.3 (and higher), you can preview changes to your SMB share before you modify the permissions. To display the result of any permission changes before you apply them, include the --dry-run flag with the add_entry or replace subcommands of the smb_mod_share_permissions command. 
• To view the optional arguments for each of the following commands, include the -h flag after the command.

Use the following commands to make changes to your SMB share.

Example: Add an Entry for a Local User or Group to the SMB Share's Permissions

qq smb_mod_share_permissions --id 579 add_entry --trustee Guest --type Allowed --rights All

New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Everyone Allowed Read, Write, Change permissions
2  Guest    Allowed Read, Write, Change permissions

Example: Add an Entry for a Local User or Group Using its Name

qq smb_mod_share_permissions --name David_SMB add_entry --trustee Joe --type Allowed --rights All

New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Guest    Denied  Read, Write, Change permissions
2  Everyone Allowed Read, Write, Change permissions
3  Joe      Allowed Read, Write, Change permissions

Example: Add an Entry for a Domain User or Group Using the Security Identifier (SID)

qq smb_mod_share_permissions --id 579 add_entry -t "sid:S-1-5-21-4205171193-792401538-2064352194-500" -y Allowed -r All

ID: 579
Name: testshare
Path: /
Description:
Access Based Enumeration: False
Default File Create Mode: 0644
Default Directory Create Mode: 0755

New Permissions:
ID Trustee                                      Type    Rights
== ============================================ ======= ===============================
1  Guest                                        Denied  Read, Write, Change permissions
2  Everyone                                     Allowed Read, Write, Change permissions
3  S-1-5-21-4205171193-792401538-2064352194-500 Allowed Read, Write, Change permissions

NOTES:

• You can add users or groups can using a UID, GID, or SID. In Qumulo Core 2.10.1 (and higher), you can add local users and groups by name; you can also add LDAP users and groups by UID or CN.
• In Qumulo Core 2.11.0 (and higher) you can specify Active Directory users and groups by name.

Example: Remove an Entry from the SMB Share's Permissions

qq smb_mod_share_permissions --id 579 remove_entry --trustee Guest

New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Everyone Allowed Read, Write, Change permissions

Example: Modify an Existing Permission Entry

qq smb_mod_share_permissions --id 579 modify_entry --old-trustee Guest --old-type Allowed --new-type Denied

New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Everyone Allowed Read, Write, Change permissions
2  Guest    Denied  Read, Write, Change permissions 

Example: Replace any Existing Share Permissions with New Permissions

IMPORTANT: If you don't specify new permissions, all access is denied.

qq smb_mod_share_permissions --id 579 replace --all-access

New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Everyone Allowed Read, Write, Change permissions

NOTE: If your cluster has local users or groups that are identified with the same name on your LDAP server, you can use the following domain prefixes in Qumulo Core 2.10.2 (and higher) to differentiate them:

• local: Specify users and groups on your Qumulo cluster.
• world: Specify the well-known group Everyone when a group with the same name exists on your LDAP server
• ldap_user: Specify users that exist on your LDAP server.
• ldap_group: Specify specify groups that exist on your LDAP server.

For example, you can use the following command to specify an LDAP group Users when there is also a local group named Users:

qq smb_mod_share_permissions --name grumpquat add_entry --trustee ldap_group:Users --type Allowed --rights Read

Listing SMB Share Permissions

To list the share access control lists (ACLs), run the smb_list_share command with the --id or --name parameter, for example:

qq smb_list_share --id 616

ID: 616
Name: Grumpquat_SMB
Path: /Grumpquat
Description:
Access Based Enumeration: False
Default File Create Mode: 0644
Default Directory Create Mode: 0755

Permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Guest    Denied  Read, Write, Change permissions
2  Everyone Allowed Read, Write, Change permissions

Additional Considerations

• To configure guest access, use the --grant-all-access Guest argument.
• When creating a share using a Qumulo Core 2.10.1 (or higher) cluster, you must specify explicit permissions. If you don't specify these permissions, the share is created with read-only access.
• For Qumulo Core 2.9.6 through 2.10.1, the default behavior for smb_add_share is to create a share that grants no access to anyone.
• The--all-access flag follows the default behavior prior to Qumulo Core 2.9.6 for everyone except guest access.
  NOTE: Currently, the Web UI abides by this default behavior.
  
• The output for smb_add_share and smb_add_shares doesn't include the read_only or allow_guest_access fields.
• To modify SMB share permissions (for example, set read-only mode or allow guest access), use the smb_mod_share_permissions command.

RESOLUTION 

You now know how to create, modify, and view SMB share permissions.

ADDITIONAL RESOURCES

Create an SMB Share

QQ CLI: SMB Shares

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