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 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
Like what you see? Share this article with your network!
Comments
0 comments
Please sign in to leave a comment.