SMB Share Permissions

IN THIS ARTICLE 

Outlines how to create, modify, and view SMB share permissions in Qumulo Core

REQUIREMENTS

• Cluster running Qumulo Core 2.9.6 and above
• Admin privileges on the Qumulo cluster

TIP! SMB Share permissions can be be managed via the UI in Qumulo Core 2.11.1 and above. Check out the Create an SMB Share article for more details.

DETAILS 

In Qumulo Core 2.9.6, we now support SMB share-level permissions that provide an alternate method for managing access to items in an SMB share. With share-level permissions, administrators have the option of setting 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 using the API. Once configured, the actual access will be determined by combining share and file permissions to enforce the most restrictive combination of the two.

SMB shares can be managed using new API endpoints that allow you to create or modify shares and their respective permissions. To create, modify, and view SMB share-level permissions, reference the examples below using the qq cli. 

NOTE: Legacy REST APIs are still available. However, these methods are limited to controlling read-only and allow-guest-access modes only.

Create an SMB Share

• Create a new share by specifying the name, directory path from the root of Qumulo file system, and explicit access permissions:

qq smb_add_share --name NAME --fs-path PATH --ACCESS-PERMISSIONS

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

If the directory does not already exist, add --create-fs-path to the end of the command as outlined in the example below:

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: The default behavior before 2.10.1 is to create an empty ACL that grants no access to anyone. With 2.10.1 and above, explicit permissions must be specified when creating a new share or you will receive the following error:

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

• Run the following to grant full control for everyone, including the Guest, on a new share:

qq smb_add_share --name NAME --fs-path PATH --grant-all-access Everyone Guest

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

Modify an SMB Share's Permissions

Use the ID or the name (2.10.0 and above) of an existing SMB share to modify the permissions with the new command below. If necessary, run qq smb_list_shares to verify the Qumulo ID of the SMB share you wish to modify.

qq smb_mod_share_permissions --id ID
qq smb_mod_share_permissions --name NAME

TIP! With version 2.10.3 and above, you can preview the changes to your SMB share before you modify the permissions. Include the new optional --dry-run argument for the add_entry or replace subcommands with qq smb_mod_share_permissions to display the result of any and all permission changes before you officially apply them. 

Below you'll find a list of the changes you can make to the share using the new command. To see the optional arguments for each command below, include -h at the end.

• Add an entry for a local user or group to the SMB share's permissions:

qq smb_mod_share_permissions --id ID add_entry
qq smb_mod_share_permissions --name NAME add_entry

EXAMPLE:
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

• Add an entry for a local user or group using the name:

qq smb_mod_share_permissions --id ID add_entry --trustee USER/GROUP NAME --type Allowed --rights All
qq smb_mod_share_permissions --name NAME add_entry--trustee USER/GROUP NAME --type Allowed -rights All

EXAMPLE: 
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

• Add an entry for a domain user or group using the SID:

qq smb_mod_share_permissions --id ID add_entry -t "sid:SID" -y Allowed -r All
qq smb_mod_share_permissions --name NAME add_entry -t "sid:SID" -y Allowed -r All

EXAMPLE:
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

NOTE: Users or groups can be added via UID, GID, or SID. In 2.10.1 and above, local users and groups can be added via name, and LDAP users and groups can be added via UID or CN. With the release of 2.11.0, specifying Active Directory users and groups by name is supported.

• Remove an entry from the SMB share's permissions:

qq smb_mod_share_permissions --id ID remove_entry
qq smb_mod_share_permissions --name NAME remove_entry

EXAMPLE:
qq smb_mod_share_permissions --id 579 remove_entry --trustee Guest
New permissions:
ID Trustee  Type    Rights
== ======== ======= ===============================
1  Everyone Allowed Read, Write, Change permissions

• Modify an existing permission entry:

qq smb_mod_share_permissions --id ID modify_entry
qq smb_mod_share_permissions --name NAME modify_entry

EXAMPLE:
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 

• Replace any existing share permissions with new permissions: 
  • All access will be denied if no new permissions are specified!

qq smb_mod_share_permissions --id ID replace
qq smb_mod_share_permissions --name NAME replace

EXAMPLE:
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 you have local users or groups on your cluster that are identified with the same name in your LDAP server, you can use the following domain prefixes available in version 2.10.2 and above to differentiate.

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

For example, you would 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

List SMB Share Permissions

• Run the following command to list the share ACLs: 

qq smb_list_share --id ID
qq smb_list_share --name NAME

EXAMPLE:
qq smb_list_share --id 616

ID: 616
Name: David_SMB
Path: /David
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

TIP! JSON output is available using the optional --json argument with any of the commands above.

Additional Considerations

• The smb_add_share --allow-guest-access argument has been removed. Guest access can be configured using the --grant-all-access Guest argument as specified above.
• As highlighted above, explicit permissions must be specified when creating a new share with 2.10.1 and above. If explicit permissions are not specified, the share will be created with read-only access.
• For versions 2.9.6 to 2.10.1, the behavior for smb_add_share is to create a share that grants no access to anyone.
• The --all-access option produces the default before 2.9.6 of full control for everyone except Guest. Keep in mind that the UI will abide by this default behavior until changes are made in a future release of Qumulo Core.
• The output for smb_list_share(s) no longer includes the read_only and allow_guest_access fields.
• The smb_mod_share --read-only and --allow-guest-access arguments have been replaced with the new CLI command smb_mod_share_permissions, which enables modification of SMB share permissions.

RESOLUTION 

You should now be able 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!