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.
NOTES:
- You can still use legacy REST APIs. However, these methods are limited to controlling only read-only and allow-guest-access modes.
-
To request JSON output, use the
--json
flag with any of the following commands.
To Create an SMB Share
-
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 -
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
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.
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
== ======= ==== ======Command error: Must specify initial permissions (--no-access, --read-only, --all-access, --grant-read-access, etc.)
-
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 theadd_entry
orreplace
subcommands of thesmb_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 groupEveryone
when a group with the same name exists on your LDAP serverldap_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
andsmb_add_shares
doesn't include theread_only
orallow_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
Like what you see? Share this article with your network!
Comments
0 comments