Network Shares: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
m Expand Quota Management: share-level, per-user, per-group, provisioning quotas; full CLI reference and alert thresholds
m Related pages: scale-up and scale-out share replication
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:admin_guide]]
[[Category:admin_guide]]


== Network Share (NAS) Management ==
A '''Network Share''' is a directory that QuantaStor provisions out of a [[Storage Pools|Storage Pool]] and exports over NFS and SMB at the same time. This page covers what a share is, every tab of the Create and Modify dialogs, NFS client access rules, SMB share options, permissions and ownership, quotas, snapshots, Global Namespaces, and what happens when you delete one.


QuantaStor ''Network Shares'' provide '''NAS''' ('''N'''etwork-'''A'''ttached '''S'''torage) access to storage pools via NFSv3, NFSv4, SMB2, and SMB3 protocols.  To provision a ''Network Share'' first a ''Storage Pool'' must be created from which ''Network Shares'' may be provisioned.  With QuantaStor's storage grid technology one can provision ''Network Shares'' from any pool on any system in the grid regardless of where it is located. QuantaStor also has ''Network Share Namespaces'' which span systems and make it easy to categorize ''Network Shares'' into folders which are called ''namespaces''.  QuantaStor ''Network Shares'' support a broad spectrum of features including quotas, user & group quotas, compression, encryption (inherited from the pool), remote-replication, snapshots, cloning, snapshots of snapshots, Avid integration, and more.  Each ''Network Share'' resides within a specific ''Storage Pool'' and storage pools can move between systems (much like a VM can move between hypervisor hosts) if configured in high-availability mode.  ''Storage Pools'' may be used to provision and serve NAS storage (''Network Shares'') and SAN storage (''Storage Volumes'') at the same time.
{| class="wikitable"
! Section !! Purpose
|-
| [[#What a Network Share is|What a Network Share is]] || How a share relates to its Storage Pool, and where its data lives
|-
| [[#Creating a Network Share|Creating a Network Share]] || The Create Network Share dialog, tab by tab
|-
| [[#Modifying a Network Share|Modifying a Network Share]] || What the Modify dialog adds, removes and locks
|-
| [[#NFS client access|NFS client access]] || Per-client export rules and their NFS options
|-
| [[#SMB/CIFS access|SMB/CIFS access]] || Share-level SMB options and Active Directory touchpoints
|-
| [[#Permissions and ownership|Permissions and ownership]] || POSIX ownership, permissions, and the create masks
|-
| [[#Quotas|Quotas]] || Share space quota, file quota, and per-user/per-group quotas
|-
| [[#Snapshots|Snapshots]] || Taking snapshots, browsing them, holds, and restore/rollback/clone
|-
| [[#Usage tracking|Usage tracking]] || Per-user and per-group capacity collection, and the switches that gate it
|-
| [[#Global Namespaces|Global Namespaces]] || Presenting shares from several systems under one name
|-
| [[#Aliases, sub-shares and nested shares|Aliases, sub-shares and nested shares]] || Re-presenting part of a share, or nesting one inside another
|-
| [[#Configuration Templates|Configuration Templates]] || Saving a share's settings and applying them to new shares
|-
| [[#Enabling, disabling and deleting a share|Enabling, disabling and deleting a share]] || Taking a share offline, and what deletion removes
|}
 
== What a Network Share is ==
 
[[File:shares_toolbar.png|thumb|right|800px|The Network Shares toolbar. Only Create, Modify, Restore, Multi-Delete and Snapshot act on a share directly; everything else is a service, namespace, template or Active Directory operation.]]
 
Every Network Share belongs to exactly one [[Storage Pools|Storage Pool]] and is created from that pool's free space. On a scale-up (ZFS) pool the share is a dataset of its own, a child of the pool dataset, so it gets its own compression, record size, quota and snapshots independently of every other share in the pool. On a scale-out (CephFS) pool the share is a directory in the Ceph file system.
 
Because the pool owns the share, a share follows its pool: if the pool is configured for high availability and moves to another system in the grid, its shares move with it and are re-exported there. A pool can serve NAS (Network Shares) and SAN ([[Storage Volumes|Storage Volumes]]) at the same time.
 
A share is reachable over both protocols at once, with no per-protocol copy of the data:
 
* '''SMB''' clients see it as a share named after the share, served from the pool mount point.
* '''NFS''' clients mount it from <code>/export/&lt;share name&gt;</code>, which is a second mount of the same dataset. The export line pins the NFS <code>fsid</code> to the share's QuantaStor object ID, so the identity a client sees is the share's own and not a device number.
 
QuantaStor writes both configurations itself: the SMB stanza into {{Code|1=/etc/samba/smb.conf}} and the export line into {{Code|1=/etc/exports}}. Both are regenerated whenever a share is created, modified or deleted -- the exports file says so in its own header -- so hand edits to either are lost. QuantaStor keeps rotating daily backups of both alongside the live files. Scale-out CephFS shares are exported by NFS-Ganesha on port '''2249''' rather than 2049.
 
'''Navigation:''' the Network Shares section of the tree holds every share in the grid.
 
{{Navigation|Storage Management &rarr; Network Shares}}
 
Selecting a share fills the centre pane with its properties and the right-hand pane with three tabs -- '''Snapshots''', '''NFS/SMB Access''' and '''SMB Sessions''' -- while the Share Dashboard above offers '''Capacity''', '''Trends''', '''NFS Stats''', '''SMB Stats''', '''Replication''', '''User Usage''' and '''Group Usage'''.
 
=== Where the share operations live ===
 
[[File:shares_context_menu.png|thumb|right|266px|The right-click menu on a Network Share. Most share operations are here only -- the toolbar carries five of them.]]
 
The '''Network Share''' toolbar group carries only '''Create''', '''Modify''', '''Restore''', '''Multi-Delete''' and '''Snapshot'''. Everything else is right-click only, so looking for a toolbar button for it is wasted effort:
 
{| class="wikitable"
! Operation !! Where
|-
| Create Share, Modify Share, Snapshot Share, Restore Share || toolbar and right-click menu
|-
| Multi-Delete / Delete Share || toolbar (''Multi-Delete'') and right-click menu (''Delete Share...'')
|-
| Create Share Namespace, Create Alias, Create Backup Policy || right-click only
|-
| Add NFS Access, Set User/Group Quotas, Move Share (Hierarchically) || right-click only
|-
| Disable Share, Rollback Share, Clone Share, Remote Replicate Share || right-click only
|-
| View Mount Command, View Network Share File Locks || right-click only
|-
| Create Configuration Template || right-click only
|-
| Configure NFS Services, Restart NFS/SMB Services || toolbar (''Network Share Services'' group) and right-click menu
|}
 
'''View Mount Command''' is worth knowing about. It shows the selected share's '''Share path''' and a ready-made two-line NFS '''Mount command''' -- a <code>mkdir -p</code> for the mount point followed by the <code>mount -t nfs</code> line with the address filled in -- for whichever '''Network Port''' you pick from its combo. Both fields are read-only and meant to be copied. It also states where read-only snapshots are reachable from an NFS client.
 
== Creating a Network Share ==


=== Creating and Modifying Network Shares ===
{{Navigation|Storage Management &rarr; Network Shares &rarr; ''select a Storage Pool or Network Share'' &rarr; Network Share &rarr; Create ''(toolbar)''}}


[[File:Network Share Create Web 6.jpg|thumb|512px|Create a Network share either by selecting '''Create''' from the "Network Share" toolbar or right click on a share from either left or center pane and choose '''Create Share...''']]
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Create Share...}}


To create a ''Network Share'' right-click on a Storage Pool and select '''Create Share...'''. Alternately, select the "Network Shares" section from the tree view and then choose '''Create''' from the "Network Share" toolbar. Network Shares can be concurrently accessed via both '''NFS''' ('''N'''etwork '''F'''ile '''S'''ystem) and '''CIFS''' ('''C'''ommon '''I'''nternet '''F'''ile '''S'''ystem) protocols.  After providing a name, optional description for the share, and select the ''Storage Pool'' in which the ''Network Share'' will be created. There are a few other options you can set including protocol access types and a share level quota. From the Encryption tab one can apply Software Encryption and optionally set an encryption passphrase. When a share is provisioned with encryption, it shall remain encrypted for its entire life span. After a ''Network Share'' has been created/provisioned it may be modified via the "Modify Network Share" dialog from the "Network Shares" toolbar or right click on a ''Network Share'' and selecting '''Modify Share...'''. These options all fall under the ''General'', ''User'', ''File Masks'', ''CIFS/SMB Settings'' and ''Advanced Settings'' tabs.
Right-clicking an existing share or a Storage Pool pre-selects that pool in the dialog, which is the quickest way to land in the right pool. The dialog has six tabs; '''OK''' is available from any of them, so you only need to visit the tabs you intend to change.


[[File:Modfy Network Share Web 6.jpg|512px|thumb|center|Modify a Network share either by selecting '''Modify''' from the "Network Share" toolbar or right click on a share from either left or center pane and choose '''Modify Share...''']]
The pool type decides what the dialog offers. On a scale-out (CephFS) pool the entire '''Advanced Settings''' tab, the Nested Share options, Immutability and the NFS Security Mode are disabled, and Ransomware Detection is unavailable -- those are scale-up (ZFS) features. Conversely '''Enable File Quota''' is only selectable on a CephFS pool.


== Quota Management ==
=== General tab ===


QuantaStor supports three levels of quota enforcement for network shares, all backed by ZFS native quota properties:
[[File:shares_create_general.png|thumb|right|720px|The General tab of Create Network Share, with Enable Quota selected. Quota is off by default, and Enable File Quota is greyed out because the selected pool is scale-up (ZFS).]]


{| class="wikitable"
{| class="wikitable"
! Quota Type !! Scope !! Use Case
! Field !! Notes
|-
| '''Name''' || Pre-filled with a generated name (<code>share-1</code>, <code>share-2</code>, ...). This becomes the SMB share name and the last element of the NFS export path, so keep it to characters a client can type.
|-
| '''Description''' || Free text, shown in the share list.
|-
| '''Copy Settings from Template''' || '''Select Template...''' opens a chooser of saved Configuration Templates and copies the chosen template's settings into the rest of the dialog. See [[#Configuration Templates|Configuration Templates]].
|-
| '''Storage Pool''' || The pool the share is provisioned from. Changing it re-reads the pool type and re-applies every type-dependent enablement rule below, and resets the Nested Share options.
|-
| '''Sub Pool''' || Scale-out only: selects which Ceph data pool inside the CephFS file system backs the share. Disabled for scale-up pools.
|-
| '''Storage Pool Settings''' || Read-only summary of the selected pool: utilization bar, Pool Type (''Scale-up (ZFS)'' or ''Scale-out''), RAID Type and Free Space.
|-
| '''Create as new Nested Share''' / '''Parent Share''' || Creates the share inside an existing share rather than at the root of the pool. Parent Share stays disabled until the checkbox is ticked, and the whole fieldset is disabled unless the pool is scale-up ''and'' the pool already has at least one eligible parent share. See [[#Aliases, sub-shares and nested shares|Aliases, sub-shares and nested shares]].
|-
| '''Enable Quota''' &rarr; '''Quota Settings''' || Off by default. Ticking it enables the size field and the percentage slider; dragging the slider fills the size field with that percentage of the pool's free space. See [[#Quotas|Quotas]].
|-
| '''Excludes Snapshot Usage''' || On by default once a quota is enabled, and greyed out on CephFS pools, which do not support it. Ticked, the quota counts only live data; unticked, snapshot space counts against it too.
|-
| '''Enable File Quota''' &rarr; '''Number of files''' || A cap on the number of files in the share. Selectable only on a scale-out (CephFS) pool.
|-
| '''Enabled''' || The share is exported as soon as it is created. Clearing both ''Enable CIFS/SMB Access'' and ''Enable Public NFS Access'' forces this off and disables it -- a share with no protocol cannot be active.
|-
|-
| '''Share Space Quota''' || Entire share || Limit total capacity a share can consume in the pool
| '''Enable CIFS/SMB Access''' || On by default. The master switch for SMB on this share.
|-
|-
| '''User Quota''' || Per user within a share || Limit how much a single user (local or AD) can store
| '''Enable Public NFS Access''' || On by default, and creates the <code>[public]</code> NFS client rule that exports the share to every client. Clear it if you intend to add specific client rules instead.
|-
|-
| '''Group Quota''' || Per group within a share || Limit aggregate storage for a team or department
| '''Enable Usage Tracking''' || On by default for scale-up pools and off for scale-out. Collects per-user and per-group capacity and file usage for the share, which is what the ''User Usage'' and ''Group Usage'' dashboards report. It is a one-way setting on an existing share -- once you tick or clear it explicitly, the share stops following its pool type's default and there is no way back to "follow the pool". See [[#Usage tracking|Usage tracking]] below for the collection intervals and the global switches that can override this checkbox.
|}
|}


In addition, '''Provisioning Quotas''' (described below) can cap the total capacity and number of volumes/shares a resource group is permitted to create.
=== User tab ===
 
[[File:shares_create_user.png|thumb|right|720px|The User tab. The Search... button is only active on the AD Users and AD Groups sub-tabs.]]


=== Share Space Quota ===
The User tab controls '''SMB''' user and group access, and the POSIX ownership of the share. It has no effect on NFS access, which is governed by client rules instead.


A share space quota sets a hard ceiling on the total space the share can consume, regardless of how much free space remains in the storage pool.
'''Select User Access Mode''' presents four grids -- '''Users''', '''Groups''', '''AD Users''' and '''AD Groups''' -- each listing a principal, its '''Access Mode''', Read/Write/Execute flags and its UID:GID. Unless the share is public, every user who needs SMB access has to appear in one of these grids with an access mode other than ''None''; group entries grant access to all members.


'''Navigation:''' Storage Management → Network Shares → (right-click share) → Modify → General tab → Enable Quota
* '''Users''' and '''Groups''' list the grid's own local accounts, whose UIDs and GIDs QuantaStor generates.
* '''AD Users''' and '''AD Groups''' are populated by the '''Search...''' button, which is enabled only while one of those two sub-tabs is selected. It opens an Active Directory search dialog; results you accept are added to the grid. To remove an AD principal, set its access mode to ''None'' rather than deleting the row.
* The access modes are '''None''', '''Valid User''', '''Admin User''' and '''Invalid User''', and they become the share's Samba <code>valid users</code>, <code>admin users</code> and <code>invalid users</code> lists. ''Invalid User'' is an explicit deny, which is how you exclude one member of an otherwise-permitted group. ''Admin User'' additionally lets that principal edit the share's Windows ACLs from a Windows client or the MMC, delegating access control to the Windows side.
* '''Copy permissions from share''' copies the AD user and group settings from another share -- useful when a set of shares should share one access list. The picker only offers shares that actually have SMB user access entries.


Set the quota size using the slider or by typing a value with a suffix (MB, GB, TB).
'''Ownership Settings''' sets the POSIX owner of the share directory:


'''Snapshot exclusion:''' By default the quota includes space used by snapshots. Enable '''Exclude Snapshots from Quota''' to apply the limit only to live data (uses ZFS <code>refquota</code> instead of <code>quota</code>).
{| class="wikitable"
! Field !! Notes
|-
| '''Assigned Owner''' || Defaults to <code>nobody (65534:65534)</code>. The owner may change ownership of files and subdirectories in the share and assign SMB ACLs to it.
|-
| '''Assigned Group''' || Defaults to <code>nogroup (65534)</code>.
|}


'''CLI:'''
Both combos carry the same caveat: to assign an AD user or group as the owner, add it as a valid user or group on this tab first. Windows ACLs and the access modes here have to agree -- granting a user access through a Windows ACL does nothing if that user is not also a valid user or a member of a valid group on the share.
<pre>
# Set a 500 GB share-level quota (includes snapshot space)
qs share-modify --share=share1 --space-quota=500GB


# Set a 500 GB quota excluding snapshot space
=== File Masks &amp; Permission Settings tab ===
qs share-modify --share=share1 --space-quota=500GB --space-quota-exclude-snapshots=true


# Remove the quota (unlimited)
[[File:shares_create_permissions.png|thumb|right|720px|Permission and create-mask defaults: rwxrwxrwx on the share, 0755 for new directories and new files.]]
qs share-modify --share=share1 --space-quota=0
</pre>


Alerts fire automatically as the share quota fills:
Three 3&nbsp;&times;&nbsp;3 grids of Read/Write/Execute checkboxes over User, Group and Other, each with a '''Select All'''/'''Deselect All''' button that flips the whole grid and re-labels itself once every box is ticked.


{| class="wikitable"
{| class="wikitable"
! Threshold !! Alert Level
! Fieldset !! Applies to !! Default
|-
|-
| 80% full (20% free remaining) || Warning
| '''Owner Permission Settings''' || The share directory itself. ''User'' is the assigned owner, ''Group'' the assigned group, ''Other'' everyone else. || <code>rwxrwxrwx</code>
|-
|-
| 90% full (10% free remaining) || Alert
| '''Directory Create Permissions Mask''' || Directories created inside the share by SMB clients || <code>0755</code> -- group and other write cleared
|-
|-
| 95% full (5% free remaining) || Critical
| '''File Create Permissions Mask''' || Files created inside the share by SMB clients || <code>0755</code> -- group and other write cleared
|}
|}


=== Per-User Quotas ===
In almost all cases the owner should keep read, write and execute on the share; clearing owner execute makes the directory untraversable.
 
=== CIFS/SMB Settings tab ===


User quotas limit how much storage a single user can consume within a share. They apply to both local (POSIX) users and Active Directory users, and are enforced transparently over both NFS and SMB.
[[File:shares_create_smb.png|thumb|right|720px|CIFS/SMB Settings. Public, Writable and Browseable (All) are on by default; every advanced option is off.]]


'''Navigation:''' Storage Management → Network Shares → (right-click share) → Add User Quota
'''CIFS/SMB Configuration Options''' are the share-level SMB switches:


{| class="wikitable"
{| class="wikitable"
! Field !! Description
! Option !! Default !! Effect
|-
| '''Public''' || on || Every user can access the share, without appearing on the User tab.
|-
| '''Writable''' || on || Clear it to present the share read-only over SMB.
|-
| '''Browseable (All)''' || on || The share appears when a Windows client browses the server.
|-
|-
| '''User''' || Local username (e.g., <code>alice</code>) or AD user in <code>DOMAIN+username</code> format
| '''Browseable (Access Based)''' || off || Access-based enumeration: the share is visible only to users who have access to it. Ticking this clears '''Browseable (All)''' and disables it, since the two are alternatives.
|-
|-
| '''Quota Size''' || Maximum space this user may consume (MB, GB, TB). Set to 0 to remove the limit.
| '''Browseable (Admin Only)''' || off || Visible to the share owner only, as a hidden share reached by <code>shareName$</code>. Also clears and disables '''Browseable (All)'''.
|}
|}


'''CLI:'''
Clearing both of the restricted browse options re-enables and re-ticks '''Browseable (All)'''.
<pre>
# Set a 50 GB quota for a local user
qs share-user-quota-add --share=share1 --user=alice --space-quota=50GB


# Set a 100 GB quota for an Active Directory user
'''CIFS/SMB Advanced Options''' are all off by default. Each exists for a specific interoperability problem rather than as a general improvement, so leave them alone unless you have the problem:
qs share-user-quota-add --share=share1 --user="CORP+john.smith" --space-quota=100GB


# Remove a user quota
{| class="wikitable"
qs share-user-quota-remove --share=share1 --user=alice
! Option !! Why you would set it
|-
| '''Hide Unreadable''' || Hides files and folders the connecting user cannot read, so a browsing user sees only what they can open.
|-
| '''Hide Unwritable''' || The same for files the user cannot write.
|-
| '''Enable Avid Integration''' || Loads the Unityed Media SMB VFS module, which gives each SMB user their own Avid metadata MXF folder so several editors can work in the same Avid project folder at once. Set it for Avid Media Composer shares and nothing else.
|-
| '''Enable Auditing''' || Records SMB file operations on this share. Auditing covers SMB/CIFS access only -- NFS activity is not audited -- and the log is written per system to {{Code|1=/var/log/samba/audit.log}}, rotated at 1&nbsp;GB and kept for five generations. Which operations are recorded, and the syslog facility and prefix used, come from {{Code|1=/opt/osnexus/quantastor/conf/qs_smb_audit_defaults.conf}}; those values are read once at service start, so a change there needs a service restart. ''(The checkbox's tooltip names <code>quantastor.conf</code> instead; that is incorrect -- see QSTOR-12381.)''
|-
| '''Disable Oplocks''' || Turns off opportunistic client-side locking and SMB2/SMB3 leases, so SMB clients stop caching file data and byte-range locks. '''Tick it on any share that NFS and SMB clients use at the same time''': with oplocks on, NFS and SMB locks do not see each other and SMB clients can read stale data -- see [[Multi-protocol File Locking]]. Also needed for a few applications that mishandle oplock breaks. It costs SMB performance, most on small or lock-heavy I/O.
|-
| '''Ignore System ACLs''' || Makes Samba ignore the POSIX ACLs on the filesystem, so the share's own permissions decide access. Use it when a Windows-managed ACL set and the underlying POSIX ACLs are fighting each other.
|-
| '''Windows &amp; macOS Extended ACLs''' || Turns on extended attributes, Samba's <code>acl_xattr</code> module and ACL inheritance, so Windows-style ACLs are stored and inherited. This is what makes managing the share's permissions from the Microsoft Management Console work.
|-
| '''macOS Extended Attributes''' || Turns on extended attribute support and Samba's <code>streams_xattr</code> module, so NTFS-style alternate data streams -- which is how macOS stores resource forks -- are held in extended attributes.
|-
| '''macOS Interop Enhancements''' || Loads Samba's <code>fruit</code> module, its macOS interoperability layer.
|-
| '''DOS Extended Attributes''' || Stores the DOS hidden/system/archive/read-only attributes in extended attributes instead of mapping them onto the POSIX permission bits.
|-
| '''Extended Attributes''' || Plain extended attribute support, for applications that store their own metadata that way.
|}
 
Shares can also be managed from the Windows Server '''Microsoft Management Console''' Share Management section, which is handy in mixed-vendor environments. To turn that on for a whole system rather than per share, see [[Enabling Global MMC Management]].
 
=== Security Settings tab ===
 
[[File:shares_create_security.png|thumb|right|720px|Security Settings, with Anomaly Detection enabled so the auto-tune, threshold and filtering fieldsets become editable.]]
 
Three unrelated groups of settings share this tab.
 
'''Anomaly Detection''' watches file modify and delete events on the share and raises an alert when the rate crosses a threshold you set -- the signature of ransomware encrypting a file tree in bulk, and equally of a runaway script or a mistaken recursive delete. The checkbox is off by default and the three fieldsets below it stay disabled until it is ticked. It is not available on scale-out (CephFS) pools, and the service refuses to enable it on RPM-based distributions (RedHat, Alma).
 
Detection is per subdirectory. Every event is attributed to the directory it happened in, and each directory carries an hourly and a daily count. A '''modify''' counts distinct files touched, so a client rewriting the same file all afternoon contributes one; a '''delete''' counts every event, because a file can only be deleted once. The share's figure is the sum across its subdirectories, and the alert names the single busiest one -- which is the useful part of it, because that is where you start looking.
 
{| class="wikitable"
! Field !! Notes
|-
| '''Hourly Modify Threshold''' || Distinct files modified per hour, summed across the share's subdirectories. Must be greater than 0 -- a zero modify threshold would mean "alert on any activity at all", and the service rejects it.
|-
| '''Hourly Delete Threshold''' || File deletes per hour. Leave it at 0 to exclude deletes from detection entirely.
|-
| '''Daily Modify Threshold''' || Distinct files modified per day. Also has to be greater than 0.
|-
| '''Daily Delete Threshold''' || File deletes per day, and may likewise be left at 0.
|}
 
A threshold fires when the count '''reaches''' it rather than when it is exceeded, so a threshold of 15 alerts on the fifteenth file. The tab's own header carries the warning that matters here: setting delete thresholds costs performance, because delete events then have to be tracked as well as modifies.
 
[[File:shares_security_autotune.png|thumb|right|706px|Ticking auto-tuning clears and disables the four manual thresholds and makes '''Auto-tune Duration''' editable.]]


# List all user and group quotas on a share (shows current usage)
'''Auto-tune Thresholds''' exists because nobody knows what a share's normal traffic looks like before it has run for a while. Set the thresholds too low and every backup window pages someone; set them too high and the detector never fires. Tick '''Enable Anomaly Detection Parameter Auto-tuning''' and QuantaStor measures instead. '''Auto-tune Duration''' is a number of days -- 7 by default, 1 to 30 -- during which the filesystem monitor records the peak hourly and daily modify and delete counts the share actually sees. When the window closes, the four thresholds are set to twice those observed peaks and the share begins detecting against them.
qs share-quota-list --share=share1
</pre>


The <code>share-quota-list</code> output includes current space used alongside each limit, so you can see who is approaching their quota at a glance.
Two consequences are worth knowing before you use it:


=== Per-Group Quotas ===
* '''No threshold alerts are raised for the share while it is auto-tuning.''' The window is a learning period and the share has no thresholds of its own during it -- the four manual fields read 0 and are disabled. Auto-tune a share that is already under attack and you teach it that the attack is normal.
* '''Auto-tuning an idle share leaves a hair trigger.''' With no modify activity in the window there is no peak to double, so the thresholds fall back to built-in defaults of 3 modifies per hour and 10 per day. Choose a window that covers the share's real workload, month-end included.


Group quotas limit the aggregate storage consumed by all members of a group within a share. They are useful for departmental charge-back or to prevent any single team from consuming the entire share.
Ticking auto-tuning clears the four manual thresholds and disables them, since they are about to be derived; clearing it again puts back whatever you had typed. '''Auto-tune Duration''' is editable only once auto-tuning is ticked.


'''Navigation:''' Storage Management → Network Shares → (right-click share) → Add Group Quota
In the Modify dialog, a share that is currently auto-tuning also shows a read-only '''Anomaly Auto-tune Ends''' date, and two rules apply to it:


'''CLI:'''
* '''Changing the duration adjusts the open window from when it started''' rather than restarting it, so cutting a 7-day window to 3 days on day 2 closes it on day 3. That is deliberate: an unrelated edit to a calibrating share re-sends the same duration when you click OK, and it has to be a no-op instead of buying another full week.
<pre>
* '''Clearing the auto-tuning checkbox ends the window immediately''' and the thresholds you type take effect from that point. You have to supply non-zero hourly and daily modify thresholds to do it, because a calibrating share has none of its own to fall back on, and the dialog refuses OK until you do.
# Set a 1 TB quota for a local group
qs share-group-quota-add --share=share1 --group=engineering --space-quota=1TB


# Set a 2 TB quota for an Active Directory group
The CLI equivalents are <code>[[QuantaStor CLI Command Reference#share-create|qs share-create]] --enable-anomaly-detection=true --anomaly-thresholds=hourlyModify:15,hourlyDelete:10,dailyModify:25,dailyDelete:20</code>, with <code>--auto-threshold-calibration-duration=&lt;days&gt;</code> instead of the thresholds to auto-tune, and <code>[[QuantaStor CLI Command Reference#share-modify|qs share-modify]] --cancel-auto-threshold-calibration=true</code> -- accompanied by <code>--anomaly-thresholds</code> -- to end a window early. Re-sending a duration adjusts the window in place, as in the dialog.
qs share-group-quota-add --share=share1 --group="CORP+finance-team" --space-quota=2TB


# Remove a group quota
'''Anomaly Detection Filtering''' narrows what is watched, using either include rules or exclude rules -- the two radio buttons are mutually exclusive and selecting one disables the other's panel. A rule is a substring, not a glob: <code>/subdirA/</code> or <code>.pdf</code>. An include rule limits detection to paths containing that substring; an exclude rule drops paths containing it. Filtering on delete events matches against the subdirectory path only and does not see the file name.
qs share-group-quota-remove --share=share1 --group=engineering


# List all quotas on the share
'''Include rules combine with AND, not OR.''' A path has to contain '''every''' rule in the include list to be watched, so adding a second rule narrows the set rather than widening it: with <code>/keep/</code> and <code>/deep/</code> both listed, activity in <code>/keep/plain/</code> is ignored and only <code>/keep/deep/</code> is watched. Use a single include rule unless you specifically want that intersection. Exclude rules behave the way the list reads -- a path matching any one of them is dropped.
qs share-quota-list --share=share1
</pre>


'''Note on AD users and groups:''' Active Directory users and groups are identified using the <code>DOMAIN+name</code> format (e.g., <code>CORP+alice</code>, <code>CORP+finance-dept</code>). The domain portion must match the AD domain joined by the appliance.
'''What happens when a detection fires.''' The filesystem monitor records the event and the management service turns it into a '''Critical''' alert within a few minutes, named for the threshold that was crossed -- ''Hourly Modify Threshold / Possible Ransomware Detected'', and the daily and delete equivalents. The alert text carries the share's mount point, the busiest subdirectory and the count observed, and it goes out through [[Alert Manager]] like any other alert. Repeats of the same alert for the same share are suppressed for an hour, so a sustained burst raises one alert rather than one every few minutes.


=== Provisioning Quotas (Resource Group Caps) ===
Detection alerts, and nothing more: it does not block the writes, disconnect the client or take a snapshot of its own. Recovery is yours to do, from the share's own [[#Snapshots|snapshots]] -- so if a share is worth watching, give it a snapshot schedule as well, and consider a [[#Holds|hold]] on the snapshots you most want kept, since a hold puts a snapshot out of reach of both the retention policy and an accidental delete.


Provisioning quotas operate at a higher level than share and user quotas. They cap how much storage a [[Security_Configuration#Resource_Groups|Resource Group]] is permitted to provision in total from a given storage pool — covering both the number of objects (volumes and shares) and the aggregate allocated capacity.
Anomaly Detection is independent of the '''Immutability / Write-Once-Read-Many (WORM) Support''' fieldset below and the two combine freely on one share. Both are served by the same per-pool filesystem monitor, which reads its configuration from {{Code|1=/mnt/storage-pools/qs-&lt;pool-id&gt;/.monitor.conf}}; only the live share is watched, and its snapshots are not monitored in their own right. Turning detection on does not restrict deleting the share, unlike immutability.


This is the primary mechanism for multi-tenant storage governance: each tenant's resource group can be capped independently.
'''Immutability / Write-Once-Read-Many (WORM) Support''' is create-time only -- the fieldset does not appear in the Modify dialog, so a share cannot be made immutable after the fact. '''None''' is the default; '''Immutable''' marks files in the share immutable, and '''Days of Immutability''' sets how long. A value of 0 means immutability never expires. An immutable share cannot be deleted without the force flag, and QuantaStor auto-creates a snapshot with a hold on it to prevent deletion. '''Clearing that hold is necessary but not sufficient''' -- the delete then fails with <code>OSN_ERR_HAS_SNAPSHOTS</code>, because the check is on the snapshot count rather than on the hold. Removing an immutable share takes three steps: clear the hold, delete the snapshot, then delete the share with <code>--flags=force</code>.


'''Navigation:''' System Management → Provisioning Quotas → (toolbar) Create Provisioning Quota
'''NFS Advanced Options''' has one field, '''Security Mode''', with three values:


{| class="wikitable"
{| class="wikitable"
! Field !! Description
! Value !! Meaning
|-
|-
| '''Name''' || Unique name for this quota
| '''inherit''' || Default. Use the system-wide NFS security policy.
|-
|-
| '''Storage Pool''' || The pool from which capacity is drawn
| '''kerberos''' || Require Kerberos security for this share.
|-
|-
| '''Resource Group''' || The resource group this quota governs
| '''system''' || Use AUTH_SYS for this share, overriding a system-wide Kerberos policy.
|}
 
The point of the per-share override is that a system configured for Kerberos can still carry shares that do not require it. The system-wide default is set in [[NFS Configuration]]. On a CephFS pool this field is forced to ''inherit'' and disabled.
 
=== Advanced Settings tab ===
 
[[File:shares_create_advanced.png|thumb|right|720px|Advanced Settings. Every control here is scale-up (ZFS) only and the whole tab greys out on a scale-out pool.]]
 
'''Share Data Options''' are the dataset properties. Each is inherited from the Storage Pool unless you set it here, and each applies to this share alone:
 
{| class="wikitable"
! Field !! Default !! Notes
|-
|-
| '''Provisionable Size''' || Total thin-provisionable capacity this resource group may allocate (0 = unlimited)
| '''Compression''' || <code>on</code> || <code>on</code>, <code>off</code>, <code>lzjb</code>, <code>lz4</code>, <code>gzip</code> and <code>gzip-1</code>..<code>gzip-9</code>, <code>zle</code>, <code>zstd</code> and <code>zstd-1</code>..<code>zstd-19</code>, <code>zstd-fast</code> and <code>zstd-fast-1</code>..<code>zstd-fast-10</code>. Raise it for highly compressible data and accept the CPU cost; set it to <code>off</code> for data that is already compressed, such as media or archives.
|-
|-
| '''Utilization Limit''' || Maximum actually-used space (may be less than provisionable size) (0 = unlimited)
| '''Sync Policy''' || <code>standard</code> || <code>standard</code> commits writes the client tagged as synchronous through the pool's intent log and writes the rest straight to disk. <code>always</code> sends everything through the intent log first -- slower, but safe against clients that do not tag their writes correctly. <code>disabled</code> ignores synchronous write requests; selecting it raises a confirmation warning that it can cause data integrity problems and is not for production. An SSD write log device on the pool accelerates every synchronous workload.
|-
|-
| '''Max Volumes''' || Maximum number of storage volumes the resource group may create (0 = unlimited)
| '''Cache Policy Primary''' || <code>all</code> || What the in-memory read cache holds for this share: <code>all</code>, <code>metadata</code> or <code>none</code>.
|-
|-
| '''Max Shares''' || Maximum number of network shares the resource group may create (0 = unlimited)
| '''Cache Policy Secondary''' || <code>all</code> || The same for the pool's SSD read cache. Both combos are disabled on pools that do not support cache policy.
|-
|-
| '''Policy''' || Soft (advisory, allows overage with a warning) or Hard (blocks provisioning at the limit)
| '''Record Size''' || <code>Auto</code> || <code>Auto</code>, or 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M. The upper bound on the block size the share writes in. Large sequential files favour a large record size; small random writes favour a small one.
|-
| '''Small Block Offload''' || <code>Inherit</code> || <code>Inherit</code>, or 4K through 256K. Writes at or below this size are routed to the pool's metadata offload device group instead of the data devices. Where you set it explicitly, a value between 8K and 32K is the recommendation.
|-
| '''Read Only''' || <code>off</code> || Presents the share read-only over both protocols.
|-
| '''Case Sensitivity''' || <code>Sensitive</code> || <code>Sensitive</code>, <code>Insensitive</code> or <code>Mixed</code> file-name matching. Create-time only -- it does not appear in the Modify dialog, because it cannot be changed on an existing dataset. Windows clients expect case-insensitive behaviour; set this deliberately for SMB-only shares.
|}
|}


'''CLI:'''
'''Snapshot Browsing Options''' decide which of the several snapshot browsing routes are open on this share. The defaults are deliberately restrictive -- only the Windows ''Previous Versions'' route is left on:
<pre>
# Create a hard quota: 10 TB provisionable, 8 TB utilization cap, max 50 volumes, max 20 shares
qs provisioning-quota-create \
  --name=tenant-a-quota \
  --pool=pool1 \
  --resource-group=tenant-a \
  --psize=10TB \
  --usize=8TB \
  --max-volumes=50 \
  --max-shares=20 \
  --quota-policy=hard


# List all provisioning quotas
{| class="wikitable"
qs provisioning-quota-list
! Option !! Default !! Effect
|-
| '''Disable SMB VSS GMT snapshots''' || off (so VSS is available) || Turns off the ''Previous Versions'' tab in a Windows client's file properties.
|-
| '''Disable SMB _snaps folder browsing of activated GMT snapshots''' || on || Blocks SMB access to activated writable snapshots through a <code>_snaps</code> folder.
|-
| '''Disable NFS _snaps folder browsing of activated GMT snapshots''' || on || The same for NFS.
|-
| '''Disables explicit NFS snapshot browsing of .zfs/.snap folder''' || on || Hides the hidden snapshot directory (<code>.zfs</code> on scale-up pools, <code>.snap</code> on scale-out) from NFS clients.
|-
| '''Disable NFS cross-mount access to share''' || off (so cross-mount is on) || Removes the <code>crossmnt</code> export option, which is what lets an NFS client traverse from this export into filesystems mounted beneath it.
|}


# Get current usage for a quota
The last three are disabled for shares that cannot have snapshots, and the two <code>_snaps</code> options are disabled on CephFS pools.
qs provisioning-quota-get --quota=tenant-a-quota


# Associate an existing volume with the quota
'''Cloud Container Options''' has one checkbox, '''Use As Cloud Container Cache Share''', which nominates the share as the local cache for cloud containers rather than as a general-purpose share. It is create-time only -- the Modify dialog shows it disabled. See [[Cloud Containers / NAS Gateway]].
qs provisioning-quota-volume-add --quota=tenant-a-quota --volume=vol1


# Associate an existing share with the quota
'''Batch Create''' creates several identically configured shares in one operation, numbering them from the name you gave. It accepts 1 to 10000 and appears in the Create dialog only.
qs provisioning-quota-share-add --quota=tenant-a-quota --share=share1


# Remove a volume from the quota
== Modifying a Network Share ==
qs provisioning-quota-volume-remove --quota=tenant-a-quota --volume=vol1


# Delete the quota
{{Navigation|Storage Management &rarr; Network Shares &rarr; ''select a Network Share'' &rarr; Network Share &rarr; Modify ''(toolbar)''}}
qs provisioning-quota-delete --quota=tenant-a-quota
</pre>


Provisioning quota alerts fire at 80% of the provisionable size and again when the limit is exceeded.
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Modify Share...}}


=== Monitoring Quota Usage ===
[[File:shares_modify_general.png|thumb|right|720px|Modify Network Share. The Storage Pool is fixed, Share Options differ from the Create dialog, and a Force checkbox sits at the bottom.]]


'''Share-level and user/group quotas:'''
The Modify dialog carries the same six tabs and the same fields, with these differences:
<pre>
# Show all user and group quotas with current usage for a share
qs share-quota-list --share=share1


# Check the share's overall space quota usage
* A '''Network Share''' combo at the top selects which share to edit; switching shares reloads every tab from that share.
qs share-get --share=share1
* '''Storage Pool''' is read-only. A share cannot be moved between pools by modifying it -- use ''Clone Share...'' into the target pool instead.
</pre>
* The '''Nested Share Options''' fieldset shows the '''Parent Share''' for reference only; both the checkbox and the combo are unavailable.
* '''Share Options''' loses '''Enable Public NFS Access''' and gains '''Active Replica Checkpoint'''. NFS access on an existing share is managed through client rules, not a checkbox, so clearing public NFS access after the fact means removing the <code>[public]</code> client rule. ''Active Replica Checkpoint'' is only selectable on a share that already is one, or whose name contains <code>chkpnt</code>.
* '''Case Sensitivity''', '''Immutability / WORM''', '''Use As Cloud Container Cache Share''' and '''Batch Create''' are absent or disabled -- all of them are decided at creation.
* A '''Force''' checkbox at the bottom of the General tab. Its tooltip states the one case it is needed for: '''renaming a share requires Force'''.
* '''Enable Quota''' reflects the share's current quota, and the size field shows the quota that is set rather than a percentage of free space.


'''Provisioning quotas:'''
One more rule looks like a fault otherwise: on an '''alias''' the Share Data Options, the permission masks and the Ownership Settings are all disabled, and on a '''sub-share''' the Share Data Options are. Those values belong to the parent share -- see [[#Aliases, sub-shares and nested shares|Aliases, sub-shares and nested shares]].
<pre>
# List all quotas with used/free/limit columns
qs provisioning-quota-list


# Show which shares belong to a quota
== NFS client access ==
qs provisioning-quota-share-assoc-list --quota=tenant-a-quota


# Show which volumes belong to a quota
QuantaStor serves NFSv3 and NFSv4 concurrently; which one a client gets is decided by the client's mount options. The NFS server implementation and the system-wide settings -- including the NFSv4-only mode and the default security policy -- are covered in [[NFS Configuration]]; this section is about the per-share client rules.
qs provisioning-quota-volume-assoc-list --quota=tenant-a-quota
</pre>


Alert notifications for quota thresholds are delivered through the standard QuantaStor alerting system (email, SNMP, webhooks). See [[Call-home_/_Alerting|Call-home / Alerting]] for configuration.
Access is granted per client by a '''client filter''': an IP address, a network, a netgroup, a host or domain wildcard, or <code>[public]</code> for everyone. Each rule becomes one entry in the share's <code>/etc/exports</code> line, carrying its own NFS options. A share's rules are listed on the '''NFS/SMB Access''' tab of the right-hand pane when the share is selected.


=== Adding a client rule ===


{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Add NFS Access...}}


===== MMC Share Management =====
[[File:shares_client_add.png|thumb|right|420px|Add NFS Client Access. The radio button decides which filter field is used; Allow Full Port Range Access is on by default.]]


QuantaStor ''network shares'' can be managed directly from the '''M'''icrosoft '''M'''anagement '''C'''onsole ('''MMC''') console Share Management section from Windows Server.  This is often useful in heterogeneous environments where a combination of multiple different filers from multiple different vendors is being used.
Pick one of the five filter kinds -- the radio button decides which field is read, and typing in a field selects its radio button for you:


It is also possible to set this capability globally for a system by customizing the underling configuration file for '''S'''erver '''M'''essage '''B'''lock ('''SMB''') which is [[Enabling Global MMC Management | outlined here]].
{| class="wikitable"
! Filter !! Example
|-
| '''Public (unsecure)''' || <code>[public]</code> -- every client
|-
| '''Local IP Address''' || <code>192.168.1.100</code>
|-
| '''Network''' || <code>192.168.1.0/24</code>
|-
| '''Network Group''' || <code>@netgroup</code>
|-
| '''Host/Domain''' || <code>*.example.com</code>
|}


===== Enabled =====
=== Modifying a client rule ===


Select the "''[x] Enabled''" check-box to enable CIFS access to the ''network share''. CIFS is a dialect of SMB. When you first select to enable CIFS access the default is to make the share public with read/write access.  To adjust this so that you can assign access to specific users or to turn on special features you can adjust the CIFS settings further by selecting the "''[x] Enable CIFS/SMB Access''" check box.
{{Navigation|Storage Management &rarr; Network Shares &rarr; ''select a Network Share'' &rarr; NFS/SMB Access ''(tab)'' &rarr; ''an NFS Client Access entry (select + right-click)'' &rarr; Modify NFS Client Access...}}


For additional information see Varonis, [https://www.varonis.com/blog/cifs-vs-smb?title= CIFS vs SMB: What’s the Difference?]
[[File:shares_client_modify.png|thumb|right|420px|Modify NFS Client Access on a share's default public rule. Allow Root Access has appended <code>no_root_squash</code> to the custom options field.]]


===== Enable CIFS/SMB Access =====
The same '''Network Share NFS Client Access Settings''' appear in both dialogs, and the wording of each is worth reading before you set it:


The "''[x] Enable CIFS/SMB Access''" option acts as a master switch to enable/disable CIFS/SMB Access for the Network Share while preserving other share options.
{| class="wikitable"
! Setting !! Default !! Notes
|-
| '''Read Only''' || off || This client may read but not write the share.
|-
| '''Allow Full Port Range Access''' || '''on''' || Permits clients to connect from source ports at or above 1024, rather than requiring a reserved port below 1024. This is the NFS <code>insecure</code> export option, and QuantaStor turns it on by default for new rules.
|-
| '''Subtree checks''' || off || Asks the NFS server to security-check nested exports. QuantaStor does not allow nested NFS exports, so this has no benefit and may cost performance. Leave it off.
|-
| '''Async Writes''' || off || Lets the server acknowledge a write before it is on stable storage. It is faster and it violates the NFS protocol; the dialog's own tooltip says "Not recommended".
|-
| '''Allow Root Access''' || off || A convenience toggle that appends <code>no_root_squash</code> to the Custom NFS Export Options field, and strips it again when cleared. Without it, root on the client is mapped to an unprivileged user.
|-
| '''Custom NFS Export Options''' || empty || A comma-delimited list of raw NFS export options, for anything the checkboxes do not cover -- for example <code>all_squash,anonuid=150,anongid=100</code>.
|-
| '''Filter Priority''' &rarr; '''Auto''' / '''Priority''' || Auto || Ordering matters in an exports file: the first matching entry wins. With '''Auto''' ticked QuantaStor decides the order; clearing it enables the '''Priority''' combo (1 to 9) so you can force a specific rule ahead of a broader one -- a single host rule ahead of the network rule that also matches it, for instance.
|}


===== Enable Public NFS Access =====
To remove a rule, right-click it on the '''NFS/SMB Access''' tab and choose '''Remove NFS Client Access...'''.


By default, "''[x] Enable Public NFS Access''" is checked, you can un-check this option to turn off NFS access to this share. Later you can add NFS access rules by right-clicking on the share and choosing 'Add NFS Client Access...'.
== SMB/CIFS access ==


=== Controlling SMB/CIFS User & Group Access - User tab ===
SMB is configured in three places, and mixing them up is the usual source of "the permissions look right but the user cannot get in":


[[File:Modify Network Share - Usr.jpg|356px|thumb|Modify a Network Share.]]
# '''Whether the share is served over SMB at all''' -- the '''Enable CIFS/SMB Access''' checkbox on the General tab.
# '''Who may connect''' -- the '''Public''' checkbox on the CIFS/SMB Settings tab, or the per-user and per-group access modes on the User tab.
# '''How the share behaves once connected''' -- the rest of the CIFS/SMB Settings tab, plus the ownership and permission masks.


User and group access via the SMB/CIFS protocol is adjustable from the ''User'' tab in both the ''Network Share Create'' and the ''Network Share Modify'' dialogs.  After selecting the ''User'' tab one is presented with a group of tabs which categorize storage grid users and groups separately from '''A'''ctive '''D'''irectory ('''AD''') Users and Groups.  Unless a given share is configured as public each user that needs access to the share must be explicitly assigned as a ''Valid User'' or ''Admin User'' for the share.  To assign groups of user's access to a given share use the ''Groups'' and/or ''AD Groups'' section to assign access at the group level.  ''Admin Users'' are given special rights to adjust the Windows '''A'''ccess '''C'''ontrol '''L'''ists ('''ACL'''s) associated with a given share so that they may manage access control to the share from the Windows side and within the '''M'''icrosoft '''M'''anagement '''C'''onsole ('''MMC''').  Storage grid users which were added via the ''Users & Groups'' tab within QuantaStor may also be assigned access to shares.  These users and groups have Unix UIDs and GIDs which are auto-generated but they may also be changed via the create and modify dialogs for users and groups respectively.
Active Directory is the fourth piece. Joining a system to a domain is what makes the '''AD Users''' and '''AD Groups''' grids usable, and it is a per-system operation: each QuantaStor system must be joined individually, and a system can belong to only one domain at a time. The toolbar carries '''Join AD Domain''' and '''Leave AD Domain''' in the '''Active Directory''' group:


==== Ownership Settings ====
{{Navigation|Storage Management &rarr; Network Shares &rarr; Active Directory &rarr; Join AD Domain ''(toolbar)''}}


Separately from controlling specific SMB/CIFS access are the Ownership Settings which sets the POSIX UID ('''U'''ser '''ID''') and GID ('''G'''roup '''ID''') ownership settings for a given network share.  This setting is important for both SMB and NFS access.  The owner of the share is allowed to change the ownership of files and subdirectories of the share and to assign SMB ACLs to the share to delegate management to other users and groups from within Windows. Note that the Windows ACL settings need to work together with the User Access Mode settings discussed above.  For example, if an AD user ''Mary'' is given access via adjustment of Windows ACLs from an administrator accessing a given share via the MMC, the ''Mary'' user account also needs access via an ''AD User'' or ''AD Group'' setting on the share of ''Valid User'' which grants her access.
The join procedure, its requirements and its troubleshooting live on [[Active Directory Configuration]], and leaving a domain on [[Active Directory Leave]]. Two AD facts bear directly on shares:


=== Permissions Mask - File Masks tab ===
* QuantaStor '''caches AD user and group names''' with their UID/GID mappings so that searching from the web interface is fast. If you have just added a principal to AD, search for it by its exact name -- specific lookups bypass the cache and will find it even when the cache is stale.
* In '''large AD environments''' (tens of thousands of principals or more) the cache scan can time out and leave the AD grids empty. See [[AD User & Group Information Caching for Large Environments]] for the pre-caching options that fix it.


[[File:Create Network Share -File Masks.jpg|356px|thumb|Directory and File Permissions Mask settings.]]
'''Restart NFS/SMB Services''' in the '''Network Share Services''' toolbar group restarts both file services on the system. Restarting the file services drops client connections, so treat it as a maintenance action rather than a first troubleshooting step.
The Permission Settings set the read, write, and execute permissions for the assigned share. The ''User'' column applies to the owner of the share whereas the ''Group'' and ''Other'' columns refer to group members and non-group user access to the share. In most cases the User column should be set such that the Owner of the share has access to read/write/execute.


=== Adjusting Default File Permissions Mask Settings - File Masks tab ===
== Permissions and ownership ==


When new files and directories are created within a given network share, they will inherit the file and directory permissions mask settings indicated here.
A Network Share has two layers of access control that must agree:


=== CIFS/SMB Settings - CIFS/SMB Settings tab ===
* '''POSIX ownership and permissions''' on the share directory -- the Assigned Owner and Assigned Group on the User tab, and the Owner Permission Settings on the File Masks &amp; Permission Settings tab. These are what NFS clients see and enforce.
* '''SMB user and group access''' -- the access modes on the User tab, and optionally Windows ACLs set from a Windows client by an ''Admin'' user.


The CIFS/SMB settings allows setting CIFS/SMB Configuration and Advanced Options.  
The create masks are a third, separate thing: they apply to files and directories that SMB clients create ''inside'' the share, not to the share itself. A share whose owner permission is <code>rwxrwxrwx</code> but whose file create mask is <code>0755</code> will accept new files that only their creator can write, which is usually what you want and occasionally surprising.


[[File:Create Network Share - SMB Set.jpg|356px|thumb|CIFS/SMB Settings]]
Per-user and per-group storage limits are set in a separate dialog; see [[#Quotas|Quotas]].


===== Avid(tm) Integration / Unityed Media VFS Support =====
== Quotas ==


Unityed Media is a special Samba '''VFS''' ('''V'''irtual '''F'''ile '''S'''ystem) module that's integrated into QuantaStor to provide Avid Media Composer(tm) users with capabilities typically only available on Avid Nexus hardware.  To enable the special share features for Avid media sharing simply check the box indicating "''[x] Enable Avid Integration''". With Avid integration enabled SMB users each get a separate Avid meta-data MXF folder which enables them to concurrently work on the same Avid project folders at the same time.
Three different limits, in two different dialogs.


===== Hide Unreadable & Hide Unwritable =====
=== Share space quota ===
To only show users those folders and files to which they have access you can set these options so that things that they do not have read and/or write access to are hidden.


When creating or modifying a ''Network Share'' there are a number of advanced options which can be set to tune the share to work better in a Windows or OS/X environment including options for extended attributes, and for hiding unreadable and/or unwritable files.
The share space quota caps the total space one share may consume from its pool, independently of how much the pool has free. Set it with '''Enable Quota''' on the General tab of the Create or Modify dialog, either by typing a size with a suffix or by dragging the slider to a percentage of the pool's free space.


===== Extended attributes =====
'''Excludes Snapshot Usage''' decides what counts toward it. Ticked -- the default -- only live data counts, so a burst of snapshot growth cannot fill the quota. Unticked, snapshot space counts as well. The two are alternatives, not a pair: setting one always clears the other, and clearing the quota removes both. Scale-out (CephFS) shares do not support the distinction and the checkbox is disabled for them.
Extended attributes are file-system features where extra metadata can be associated with files. This is useful for enabling security controls (ACLs) for DOS and OS/X. Extended attributes can also be used by a variety of other applications so if you need this capability simply enable it by checking the box(es) for DOS, OS/X and/or for plain Extended Attribute support.


=== Advanced Configuration Options - Advanced Settings tab ===
A quota smaller than 1&nbsp;MiB is raised to 1&nbsp;MiB.


There are several advanced configuration options available to be adjusted for Network Shares including compression, sync policy, record size (similar to block size), extended attributes, and special features like Avid Media Composer(tm) integration. Options for Snapshot browsing, Cloud container cache, NFS security, and Nested share creation are available.
<code>[[QuantaStor CLI Command Reference#share-modify|qs share-modify]] --share=&lt;share&gt; --space-quota=&lt;size&gt; --space-quota-exclude-snapshots=&lt;true|false&gt;</code> does the same from the CLI, and <code>--space-quota=0</code> removes the quota. Two CLI-specific traps:


[[File:Crt Netwrk Share - Adv Settings.jpg|thumb|356px|Advanced Settings for Network Share.]]
* '''The CLI default is not the dialog default.''' The dialog ticks ''Excludes Snapshot Usage''; omitting <code>--space-quota-exclude-snapshots</code> on the CLI gives you the other behaviour, with snapshot space counted.
* '''<code>share-modify</code> ignores the flag on its own.''' You have to pass <code>--space-quota</code> in the same command, otherwise the whole quota block is skipped and the flag has no effect.


==== Data Compression ====
=== File quota ===


''Network Shares'' and ''Storage Volumes'' inherit the compression mode and type from whatever is set for the ''Storage Pool'' from which they are provisioned unless explicitly adjusted.  Compression levels may be adjusted specifically for any given ''Network Share'' to meet the needs of the data contained within the share. For network shares that contain files which are heavily compressible you might increase the compression level to gzip (gzip6), but note that it'll use more CPU power for higher compression levels.  For network shares that contain data that is already compressed, you may opt to turn compression 'off'.
A cap on the '''number of files''' rather than the space they occupy, set with '''Enable File Quota''' on the General tab. It applies to scale-out (CephFS) shares only; on a scale-up pool the checkbox is greyed out. The CLI argument is <code>--file-quota</code>.
<br>'''Note''', this feature is specific to ZFS based Storage Pools.


==== Cache Sync Policy ====
=== Per-user and per-group quotas ===


The ''Sync Policy'' indicates the strategy that the pool uses to optimize writes to a given network share.  ''Standard'' mode is the default and uses a combination of synchronous and asynchronous write modes to ensure consistency while optimizing write performance. If I/O write requests have been tagged as ''SYNC_IO'' then all IO is first sent to the file-system intent log (ZIL) and then staged out to disk, otherwise the data can be written directly to disk without first staging to the intent log.  In the ''Always'' mode the data is always sent to the file-system intent log first irrespective of whether the client has specified a given write request as ''SYNC''.  The ''Always'' mode is generally a bit slower but technically safer if the client is not properly tagging the IO.  Databases and virtualization platfoms generally mark all write I/O as ''SYNC''. An SSD based write log will greatly accelerate ''storage pool'' performance for all workloads and systems using the ''SYNC'' write mode.  With an SSD write log in place IOs are combined into transaction groups which greatly improves overall IOPs performance. The ''Sync Policy'' for each ''Network Share'' is inherited from the ''Storage Pool'' from which the share is provisioned but may be adjusted on a per-share basis using the ''Modify Network Share'' dialog.
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Set User/Group Quotas...}}


===== Disable Snapshot Browsing =====
[[File:shares_quota_manager.png|thumb|right|800px|The Network Share User & Group Quota Manager. The right-hand grid lists quotas already on the share with each principal's current utilization.]]


Snapshots can be used to recover data and by default your snapshots are visible under a special ShareName_snaps folder.  If you don't want users to see these snapshot folders you can disable it.<br>'''Note''', you can still access the snapshots for easy file recovery via the Previous Snapshots section of Properties page for the share in Windows.
The '''Network Share User &amp; Group Quota Manager''' limits how much a single user or group may store inside one share. Limits apply to both local and Active Directory principals and are enforced over NFS and SMB alike.


==== CIFS Configuration Options ====
Pick the share at the top -- the dialog only offers shares whose type supports quotas -- and the '''Network Share Information''' panel confirms its system, pool and current utilization. Then:


[[File:Modfy Network CIFS-SMB Web 6.jpg|thumb|512px|To Modify a Network share either select "Modify" from the Network Share toolbar or right click on a share from either left or center pane and choose "Modify Share..."]]
# Select principals in the '''Users &amp; Groups''' list on the left, which has '''Users''', '''AD Users''' and '''AD Groups''' sub-tabs.
# Enter a '''Quota Size''' (or drag the slider). The field is pre-filled with <code>10GiB</code>.
# Click '''Add Quota &gt;&gt;'''. The principal appears in the '''Network Share User &amp; Group Quotas''' grid on the right with its quota and its current utilization.


There are a number of custom options that can be set to adjust the CIFS/SMB access to your ''network share'' for different use cases. Under the 'CIFS/SMB Settings' tab the 'Public' option makes the ''network share'' public so that all users can access it. The 'Writable' option makes the share writable as opposed to read-only and the 'Browseable' option makes it so that you can see the share when you browse for it from your Windows server or desktop. The 'Advanced Options' tab allows modification of Share Data Settings, Snapshot Browsing Options, Cloud Container Options, NFS Advanced Options, and Nested Share Settings.
'''&lt;&lt; Remove Quota''' takes a selected entry back off the share, and '''Copy From Share''' below the grid copies an entire quota set from another share. '''Apply''' commits without closing the dialog, which is convenient when working through several shares.


=== NFS Access Management ===
The equivalent CLI commands are <code>[[QuantaStor CLI Command Reference#share-user-quota-add|qs share-user-quota-add]] --share=&lt;share&gt; --user=&lt;user&gt; --quota-size=&lt;size&gt;</code> and <code>[[QuantaStor CLI Command Reference#share-group-quota-add|qs share-group-quota-add]] --share=&lt;share&gt; --user-group=&lt;group&gt; --quota-size=&lt;size&gt;</code>, with matching <code>share-user-quota-remove</code> and <code>share-group-quota-remove</code>. Sizes take a suffix -- <code>4G</code>, <code>100M</code>, <code>1.4T</code>. Active Directory principals are named <code>DOMAIN+name</code>.


QuantaStor supports NFS access via NFSv3 and NFSv4 at the same time.  To use one mode versus another simply change the NFS mount options at the client side to use ones preferred protocol.  NFS access may be managed via Kerberos but in general NFS access is managed by allowing or disallowing access to specific IP addresses and/or networks.  In QuantaStor these NFS access entries are called ''Network Share Client Access'' entries and sometimes ''NFS Client Access'' entries.  NFS access entries appear in the tree view as child objects of the Network Share and can be modified/edited to apply special options or deleted by using the right-click on ''Add NFS Access...'' from the pop-up menu when the share or ''Client Access'' entry is selected.
''Note: <code>qs share-quota-list</code> currently prints its table twice and duplicates rows (QSTOR-12373); read the quotas from the Quota Manager dialog until that is fixed.''


==== Configuring NFS Services ====
Tenant-level caps on how much a resource group may provision in total are a separate mechanism, configured with the <code>provisioning-quota-*</code> commands and described under resource groups in [[Security Configuration]].


[[File:Cnfg NFS Services Web 6.jpg|thumb|512px|To configure Network Services either select "Configure NFS" from the Network Share Services of the Network Share Services toolbar or right click on a network share in either the center or left panes and select "Configure NFS Services...".]]
=== Reservations ===


The default NFS mode is to support both NFSv3 and NFSv4 but the service may be configured via the ''NFS Services Configuration'' dialog to force the system into NFSv4 mode. To access this dialog select the ''Storage Management'' tab from the Main Tab, then ''Network Share'' from the tree view, then ''Configure NFS'' from the ''Network Share Services'' toolbar. One can also right click on a Network Share in the tree view and select  "Configure NFS Services..." from the right click menu.
A quota is a ceiling; a '''reservation''' is a floor. Reserving space guarantees a share that much capacity out of its pool, so no other share can consume it. Reservations are '''CLI only''' -- there is no field for one in the Create or Modify Network Share dialog, and the share detail panel does not display it. Set it with <code>[[QuantaStor CLI Command Reference#share-create|qs share-create]] --reserved=&lt;size&gt;</code> or <code>[[QuantaStor CLI Command Reference#share-modify|qs share-modify]] --reserved=&lt;size&gt;</code>, and read it back from the '''Reserved''' column of <code>[[QuantaStor CLI Command Reference#share-list|qs share-list]]</code>.


==== Controlling NFS Access ====
Three things to know before using it:


[[File:Add NFS Access Web 6.jpg|thumb|512px|To add NFS client access select "Add NFS Access..." from the right click menu on a network share in either Tree View or Tree View Detail views.]]
* '''A reservation can only grow.''' <code>share-modify</code> rejects a smaller value than the share already has.
* '''It applies to scale-up (ZFS) shares only.''' The value is accepted and stored on other share types, and on an alias or sub-share, but nothing applies it.
* '''A Configuration Template carries it.''' A template captured from a share that has a reservation will apply that reservation to shares created from it in the web interface, even though no dialog can enter one.


NFS share access is filtered by IP address. This can be done by right clicking on a network share, and selecting "Add NFS Access...". By default the share is set to have [public] access. This dialog allows one to enable access to specific IP address, a range of IP addresses, or to specific networks.
== Usage tracking ==


==== NFS Client Access Settings & Custom Options ====
'''Enable Usage Tracking''' on a share's General tab turns on collection of per-user and per-group capacity and file counts, which is what the '''User Usage''' and '''Group Usage''' dashboards report and what makes the per-user quota utilization figures meaningful.


Often times shares access will require special options like ''no_root_squash'' and these are all adjustable in the from within the "Modify NFS Client Access" dialog and in the ''Advanced Settings'' section in the ''Add NFS Client Access'' dialog. To access the ''Modify NFS Client Access...'' dialog simply expand the ''Network Share'' in the tree view, then right-click on an access entry and select "Modify NFS Client Access..". Various NFS client access options are presented including "Read Only", "Allow Full Port Range Access", "Subtree checks", and "Async Writes".  You can also add custom options such as "no_root_squash" in the space provided below.
The per-share checkbox is not the only switch. Collection is also gated globally, per filesystem type, by {{Code|1=/opt/osnexus/quantastor/conf/qs_shareusage.conf}}:


=== Active Directory Configuration ===
{| class="wikitable"
QuantaStor systems can be joined to an AD domain so that CIFS/SMB access can be applied to specific AD users and AD groups.  <br><br>'''Note:''' that each QuantaStor system can only be joined to a single AD domain and that each system must be individually joined to an AD domain.
! Key !! Default !! Controls
To configure an Active Directory either select "Configure Active Directory" from the Network Share Services of the Network Share Services toolbar or right click on a network share in either the center or left panes and select "Configure Active Directory...".
|-
| <code>zfs_usage_tracking_enabled</code> || <code>true</code> || Whether any scale-up (ZFS) share collects usage
|-
| <code>ceph_usage_tracking_enabled</code> || <code>false</code> || The same for scale-out (CephFS) shares
|-
| <code>zfs_interval_minutes</code> || <code>60</code> || How often ZFS shares are sampled
|-
| <code>ceph_interval_minutes</code> || <code>1440</code> || How often CephFS shares are sampled
|-
| <code>top_n</code> || <code>10</code> || How many top users and groups per share are recorded
|-
| <code>retention_weeks</code> || <code>12</code> || How long usage statistics are kept
|}
 
Two consequences of that table are worth spelling out, because they are the usual reason usage figures look missing:
 
* '''A <code>false</code> global overrides the per-share checkbox.''' Because <code>ceph_usage_tracking_enabled</code> ships as <code>false</code>, a CephFS share with ''Enable Usage Tracking'' ticked still collects nothing until the global is turned on. That is deliberate -- CephFS collection walks the directory tree, where ZFS reads the figures straight out of the filesystem, which is why the shipped Ceph interval is a day rather than an hour.
* '''Usage is sampled, not live.''' A newly written file shows up at the next interval, so up to an hour later on a ZFS share.
 
The first five keys are re-read on the service's own one-minute tick, so a change to them takes effect within a minute without a restart. <code>retention_weeks</code> is applied by the statistics database setup and needs a service restart.
 
Shares that are cloud containers, and shares whose directory does not exist, are skipped regardless of the settings.
 
== Snapshots ==
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; ''select a Network Share'' &rarr; Network Share &rarr; Snapshot ''(toolbar)''}}
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Snapshot Share...}}
 
[[File:shares_snapshot.png|thumb|right|552px|Snapshot Network Share. The default GMT timestamp name is what snapshot browsing from Windows clients relies on.]]
 
A snapshot is a space-efficient point-in-time copy of the share, taken instantly. Scale-up (ZFS) and scale-out (CephFS) shares support snapshots; standard shares and Ceph object gateway shares do not, and the dialog refuses to open on those.
 
{| class="wikitable"
! Field !! Notes
|-
| '''Network Share''' || The share to snapshot, with its Storage Pool shown read-only beneath.
|-
| '''Create snapshot using default GMT timestamp name''' || The default. Produces a UTC name of the form <code>@GMT-2026.09.03-03.36.09</code>, which is the exact format Windows clients read for the ''Previous Versions'' tab. Keep it unless you have a reason not to. This choice also makes the snapshot ''lazy'': the writable copy is not materialized until something needs it, which costs no extra space and saves CPU and memory. Scheduled snapshots always take this path.
|-
| '''Create snapshot with custom name''' || Enables the '''Name''' field. A custom name is easier for a person to recognise, but it is not picked up by Windows snapshot browsing, and the snapshot is made writable straight away rather than lazily. Names containing <code>GMT</code> are rejected, so a hand-made snapshot cannot impersonate a timestamped one.
|-
| '''Description''' || Free text.
|-
| '''Active''' || On by default. An active snapshot is exported and browsable; an inactive one exists but is not presented to clients.
|}
 
The '''Snapshots''' tab of the right-hand pane lists a share's snapshots with the '''Schedule''' that created each one and its '''Retention Tags''' -- which is how you tell a hand-made snapshot from one a schedule owns.
 
=== Browsing snapshots ===
 
A share's snapshots are presented in three different ways, each governed by one of the Snapshot Browsing Options on the Advanced Settings tab:
 
{| class="wikitable"
! Route !! How a client reaches it !! Default
|-
| '''Windows Previous Versions''' || The ''Previous Versions'' tab of a file or folder's Properties in Windows Explorer. This is Samba's shadow-copy support reading the timestamped <code>@GMT-</code> snapshots, which is why the default name format matters. || available
|-
| '''The <code>_snaps</code> folder''' || A folder beside the share holding one entry per activated snapshot. Available over SMB and over NFS, each with its own switch. || blocked on both protocols
|-
| '''The hidden snapshot directory''' || <code>.zfs</code> on a scale-up share, <code>.snap</code> on scale-out, reached explicitly by an NFS client. || blocked
|}
 
So out of the box a Windows user can recover a file from a snapshot themselves, and an NFS or SMB user cannot browse snapshots at all. Open the other routes deliberately.
 
=== Holds ===
 
A '''hold''' pins a snapshot so that nothing can remove it -- not the Delete Network Shares dialog, and not a snapshot schedule's retention expiry. That makes it the right tool for a snapshot you need to keep for an audit or an investigation while schedules continue to rotate the rest.
 
Add and remove one with <code>[[QuantaStor CLI Command Reference#share-hold-add|qs share-hold-add]] --share=&lt;snapshot&gt; --hold-tag=&lt;tag&gt;</code> and <code>[[QuantaStor CLI Command Reference#share-hold-remove|qs share-hold-remove]] --share=&lt;snapshot&gt;</code>. Points worth knowing:
 
* '''Tags are prefixed and there is only one.''' A tag you supply is prefixed with <code>QS-</code> if it does not start that way, an omitted tag becomes <code>QS-keep</code> (or <code>QS-</code> plus the schedule id for a scheduled snapshot), and a second hold on the same snapshot is refused.
* '''The hold outlives the QuantaStor database.''' It is a hold on the underlying filesystem snapshot, so even a direct filesystem-level destroy is refused until the hold is released.
* '''Immutable shares get one automatically.''' A share created with WORM/Immutable protection has a held snapshot auto-created specifically to block deletion. Clearing the hold is only the first step -- the snapshot itself must then be deleted before the share can be removed, because the delete check counts snapshots rather than holds.
 
<code>[[QuantaStor CLI Command Reference#share-list|qs share-list]] --include-snapshots=true --snapshots-with-holds-only=true</code> lists what is currently held.
 
=== Snapshot schedules ===
 
Taking snapshots on a timetable, with retention, is the job of a '''Snapshot Schedule''' rather than this dialog. A schedule holds a set of shares, a timetable and a retention count, and the snapshots it creates are tagged with the schedule's retention tags so it can expire them later. The relationship runs both ways and matters when you come to remove things:
 
* Deleting a share that '''is used by, or was previously created by, a snapshot schedule''' requires the force flag. QuantaStor refuses otherwise, and names the schedule in the error.
* Snapshots can outlive the schedule that made them. The Delete Network Shares dialog has a '''Select All Orphaned Snapshots''' button for exactly those -- snapshots on the chosen pool that are no longer associated with a schedule.
 
See [[Snapshot Schedules]] for setting them up. For copies that leave the system entirely, see [[Backup Policies]].
 
=== Restore, rollback, clone and promote ===
 
Four related right-click operations, easy to confuse:
 
{| class="wikitable"
! Operation !! What it does
|-
| '''Restore Share...''' || Returns the share's contents to a chosen snapshot. It works with '''any''' snapshot, but it is a file-level copy rather than an instant operation: QuantaStor takes the share '''offline''' for the duration, copies the snapshot's contents back over the live share, then re-exports it. Plan for the outage on a large share.
|-
| '''Rollback Share...''' || The same result, instantly, but only for the '''most recent''' snapshot -- newer snapshots have to be deleted first. It fails if the share is in use.
|-
| '''Clone Share...''' || Creates a new, '''fully independent''' share from a snapshot, into a pool you choose. It is a full copy, not a thin clone, so it takes time and space proportional to the data -- and it is the way to get a share into a different Storage Pool. To get one onto a different ''system'', use ''Remote Replicate Share...'' instead. Scale-up (ZFS) pools only.
|-
| '''Promote Share''' || Swaps a snapshot into the parent's place: the parent is renamed aside and the snapshot takes its name. Reversible -- running it again on a promoted share demotes it.
|}
 
== Global Namespaces ==
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Global Namespaces &rarr; Create ''(toolbar)''}}
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Create Share Namespace...}}
 
[[File:shares_namespace_create.png|thumb|right|800px|Create Network Share Namespace. Selected systems advertise the namespace; selected shares are the ones it presents.]]
 
A '''Network Share Namespace''' -- '''Global Namespaces''' on the toolbar -- gathers shares from one or more systems and presents them under a single name on '''all''' of the selected systems. A client can then connect to any member system and be redirected to whichever system actually holds the share, using Microsoft DFS for SMB and NFSv4 referrals for NFS. It removes the need for clients to know which system a share lives on.
 
{| class="wikitable"
! Field !! Notes
|-
| '''Name''' / '''Description''' || The namespace name is what clients connect to.
|-
| '''Microsoft DFS''' || '''Grouped''', '''Flat''' (default) or '''Disabled'''. ''Flat'' presents the member shares at the root of each server, without the namespace name in the path. ''Grouped'' puts them under a folder named after the namespace, so namespace <code>ns1</code> with <code>share1</code> and <code>share2</code> presents as <code>/ns1/share1</code> and <code>/ns1/share2</code> from every server. ''Disabled'' means the namespace is not presented over SMB at all.
|-
| '''NFSv4 Referrals''' || '''Flat''' (default) or '''Disabled'''. There is no grouped mode for NFS.
|-
| '''Scope Namespace to Selected Systems''' || Tick each system that should advertise the namespace, and choose its '''Network Ports'''. ''Auto (all available IP addresses)'' -- the default -- advertises every address that system has; selecting specific ports restricts redirection to those addresses, which is what you want when only some of a system's interfaces are on the client network.
|-
| '''Select Network Share(s)''' || The dual list of member shares, with a '''Search''' box and '''Reset''' for narrowing a long list. Both a system selection and a share selection are required.
|}
 
Underneath, the two modes produce two different pieces of configuration on '''every''' member system: DFS referral entries in that system's generated SMB configuration, and NFSv4 <code>refer=</code> targets appended to its export lines. A client connecting to any member is redirected from there to the system that holds the data.
 
Two membership rules and one precedence rule matter in practice:
 
* '''A share can belong to only one namespace''', and cloud-backup shares, nested shares and Ceph shares cannot join one at all.
* '''For a share on a high-availability pool, the pool's virtual interfaces win over <code>--preferred-ports</code>.''' Redirection has to point at an address that follows the pool when it moves, so the HA pool's VIF list takes precedence over the per-system port selection. Setting preferred ports on such a system has no effect on those shares.
 
'''Modify''' changes the name, description and the two modes; '''share-namespace-add-shares''' and '''share-namespace-remove-shares''' add and remove members. Deleting a namespace does '''not''' delete its member shares -- but note the converse: a share that belongs to a namespace cannot be deleted until it is removed from the namespace, and QuantaStor names the namespace in the error.
 
The CLI equivalents are <code>[[QuantaStor CLI Command Reference#share-namespace-create|qs share-namespace-create]] --name=&lt;name&gt; --preferred-ports=&lt;list&gt; --share-list=&lt;list&gt;</code> and the rest of the <code>share-namespace-*</code> family. Passing a Storage System name rather than a port to <code>--preferred-ports</code> selects automatic address selection for that system.
 
Do not confuse these with Ceph pool namespaces (<code>ceph-pool-namespace-*</code>), which isolate workloads inside a Ceph pool and have nothing to do with share presentation.
 
== Aliases, sub-shares and nested shares ==
 
Three ways to present something other than a plain top-level share, all reached from the right-click menu or the CLI:
 
{| class="wikitable"
! Kind !! Created with !! What it is
|-
| '''Alias''' || ''Create Alias...'', or <code>[[QuantaStor CLI Command Reference#share-create-alias|qs share-create-alias]] --name=&lt;name&gt; --parent-share=&lt;share&gt;</code> || A second export name for '''exactly the same directory''' as the parent share. Use it to present one share under two names with different access control.
|-
| '''Sub-share''' || The same command with <code>--subpath=&lt;dir&gt;</code> || An export of a '''subdirectory''' of the parent share. The directory is created if it does not exist and the path may be nested several levels deep.
|-
| '''Nested share''' || '''Create as new Nested Share''' on the General tab, or <code>--parent-share</code> on <code>qs share-create</code> || A share '''of its own''' created inside another share rather than at the pool root. Scale-up pools only, and only where the pool already has an eligible parent.
|}
 
The difference that matters is whether the child has storage of its own:
 
{| class="wikitable"
! !! Alias !! Sub-share !! Nested share
|-
| Own dataset || no || no || '''yes'''
|-
| Own quota and reservation || no || no || '''yes'''
|-
| Own snapshots || no || no || '''yes'''
|-
| Own name, description, NFS client rules, SMB access, CIFS options || yes || yes || yes
|}
 
An alias or sub-share therefore has its own access control and nothing else. That is why the Modify dialog disables the Share Data Options for a sub-share, and the Share Data Options, the permission masks and the Ownership Settings for an alias: those values live on the parent's dataset, so editing them through the child would change the parent. It also explains three behaviours that otherwise look like faults:
 
* '''Snapshotting an alias or sub-share snapshots the parent.''' The request is redirected; you do not get a snapshot of just the child.
* '''Rollback and Restore are refused''' on an alias or sub-share, and the error names the parent to use instead. Rolling the parent back rolls its aliases and sub-shares back with it.
* '''Clone is refused''' on all three kinds.
 
Aliases and sub-shares cannot be chained -- the parent of an alias must be a real share -- and they are not available on scale-out, Ceph object gateway or cloud shares. <code>--inherit-access</code> copies the parent's <code>cifs</code> or <code>nfs</code> access entries to the new alias at creation; without it the alias starts with none.
 
Deleting an alias removes only the export and the object: because the data belongs to the parent, '''the files are left in place'''. Deleting a sub-share does remove its directory.
 
'''Move Share (Hierarchically)...''' re-parents an existing share, and is the <code>[[QuantaStor CLI Command Reference#share-move|qs share-move]] --share=&lt;share&gt; --new-parent=&lt;share&gt;</code> operation.
 
== Configuration Templates ==
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Configuration Templates &rarr; Create ''(toolbar)''}}
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Create Configuration Template...}}
 
A '''Configuration Template''' captures an existing share's settings so that new shares can be created with them, which is how you keep a set of shares consistent without re-filling six tabs each time. Templates are listed on the '''Configuration Templates''' tab beside the Network Shares list.
 
Create a template from a share you have already configured the way you want. When creating a share, '''Select Template...''' on the General tab applies one; a template mask decides which groups of settings are copied -- all of them, or just the general, user, permissions, CIFS, NFS, security or advanced groups. The CLI equivalents are <code>[[QuantaStor CLI Command Reference#share-template-create|qs share-template-create]]</code>, <code>share-template-apply</code> and <code>[[QuantaStor CLI Command Reference#share-create-from-template|qs share-create-from-template]]</code>. One template may be marked as the default.
 
Where you only want to align two existing shares, <code>[[QuantaStor CLI Command Reference#share-copy-settings|qs share-copy-settings]] --share=&lt;target&gt; --share-copy-settings-source=&lt;source&gt;</code> copies one share's settings onto another directly, with no template object in between. There is no equivalent button in the interface -- the '''Copy permissions from share''' button on the User tab copies the SMB access list only.


==== Joining an AD Domain ====
== Enabling, disabling and deleting a share ==
To join a domain first navigate to the "Network Shares" main tab section. Next select "Configure CIFS" from the toolbar, or by right-clicking in the "Network Shares" section and selecting "Configure CIFS Services..." from the pop-up menu. Check the box to enable active directory, and provide the necessary information. KDC is most likely your domain controllers FQDN (DC.DOMAIN.COM).
<br><br>
'''Note''', Your storage system name must be <= 15 characters long.


If there are any problems joining the domain please verify that you can ping the IP address of the domain controller, and that you are also able to ping the domain itself.
=== Disabling ===


Once a given QuantaStor system has been joined to an AD domain, verify that it has been added by logging into the AD Domain Controller and then check under the Computer entry tab for the system.
'''Disable Share...''' on the right-click menu -- or clearing '''Enabled''' in the Modify dialog, or <code>[[QuantaStor CLI Command Reference#share-disable|qs share-disable]] --share=&lt;share&gt;</code> -- takes the share out of service. Disabling does three things: it marks the share offline, it regenerates {{Code|1=/etc/samba/smb.conf}} and {{Code|1=/etc/exports}} with the share's entries dropped from both, and it '''kills any process still holding an open file handle on the share'''. That last step is what makes disabling reliable, and it is also why you should not use it casually on a share with active clients.
 
The share's data is not touched: the dataset stays mounted where it was, and '''Enable''' puts the share straight back into both configuration files.
 
The two switches on the General tab are not the same thing:
 
{| class="wikitable"
! Switch !! Effect
|-
| '''Enabled''' || Protocol-agnostic. Drops the SMB stanza ''and'' the NFS export line, and marks the share offline.
|-
| '''Enable CIFS/SMB Access''' || SMB only. Drops the SMB stanza; the NFS export line and the share's client rules are untouched and the share stays online.
|}
 
There is one interlock worth knowing, because otherwise it looks like the dialog ignored you: if you leave '''Enabled''' ticked but clear '''Enable CIFS/SMB Access''' on a share that has '''no NFS client rules''', the share ends up offline anyway, with the state detail ''"No access via SMB or NFS has been configured, share is offline."'' A share with no protocol cannot be online.
 
=== Deleting ===
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share &rarr; Multi-Delete ''(toolbar)''}}
 
{{Navigation|Storage Management &rarr; Network Shares &rarr; Network Share ''(select + right-click)'' &rarr; Delete Share...}}
 
[[File:shares_delete.png|thumb|right|800px|Delete Network Shares. Hide Snapshots is ticked by default, so snapshots are not listed until you clear it.]]
 
Both routes open the same '''Delete Network Shares''' dialog, which deletes any number of shares and snapshots in one operation.
 
{| class="wikitable"
! Control !! Notes
|-
| '''Search and Filter Settings''' || '''Storage System''' and '''Storage Pool''' narrow the candidate list, '''Quick Search''' filters it by name. '''Hide Aliases''' and '''Hide Snapshots''' are both ticked by default, so snapshots do not appear until you clear the box.
|-
| '''Select the Network Shares (and/or Snapshots) to Delete''' || A dual list. The arrows move selections; you can also drag, with Ctrl for individual items and Shift for a range. The Selected side reports the space that will be recovered.
|-
| '''Select All Snapshots''' || Selects every snapshot on the chosen Storage Pool.
|-
| '''Select All Orphaned Snapshots''' || Selects only snapshots on that pool that are no longer associated with a replication schedule.
|-
| '''Force''' || Required when one or more of the selected shares is in use, and for the refusals listed below.
|-
| '''Delete Child Snapshots Only''' || Deletes the selected shares' snapshots and leaves the shares themselves in place.
|}
 
'''Deletion destroys the share's data.''' The share's directory contents are removed recursively, its SMB stanza and its export line are dropped from the generated configuration files, and its database record and metadata file are removed. There is no undo, which is why the dialog asks for confirmation and reports how many shares are about to go. The exception is an '''alias''', whose files belong to its parent and are left in place.
 
QuantaStor '''refuses''' the delete outright in these cases, rather than deleting something you may still need:
 
{| class="wikitable"
! Refused when !! What to do
|-
| The share '''has snapshots''' || Delete the snapshots first, or select them alongside the share in this dialog.
|-
| The share has '''sub-shares, aliases or nested shares''' under it || Remove the children first.
|-
| The share '''belongs to a Global Namespace''' || Remove it from the namespace first. The error names the namespace.
|-
| The share, or one of its snapshots, '''has a hold''' on it || Clear the hold, then delete the snapshot -- clearing the hold alone leaves the delete failing on the snapshot count. Immutable shares get an auto-created snapshot with a hold precisely to stop this.
|-
| The share's '''Storage Pool is not mounted or active''' || Bring the pool online. If the pool no longer exists at all, the share's record is simply removed.
|}


[[File:adComputerEntry.png]]
Two more cases are refused '''unless Force is set''': a share marked '''immutable''', and a share that is used by, or was created by, a '''snapshot or replication schedule'''. A share nominated as a '''Cloud Container cache''' also needs Force, and its cloud containers should be removed first.


==== Active Directory User & Group Name/ID Caching ====
Where [[Security Configuration#Multi-admin Approvals|multi-admin approval]] covers Network Share deletes, a delete raises an approval request instead of running, and the task reports how many of the required approvals have been met.
QuantaStor caches AD user names and their associated Unix user ID and group ID (UID/GID) information to accelerate user and group searching from within the web UI. If one has recently added users or groups to an Active Directory configuration then the user or group name should be explicitly specified when searching since the QuantaStor service cache may be stale.  User and group specific lookups do not rely on the cache so they will return a result even if the cache is out of date.


===== Active Directory Caching for Large Enterprise Deployments =====
== Related pages ==
For large Active Directory environments (10K-100K+ users and groups) it can take a long time for QuantaStor to gather information from AD to populate QuantaStor's internal cache.  If it takes too long the scan will timeout and the AD information list presented to the user in the web user interface will be empty. To account for the slow interaction with some AD servers in large environments QuantaStor has some advanced options for [[AD User & Group Information Caching for Large Environments|pre-caching information for large Active Directory environments which is documented and outlined in this section.]]


==== Leaving an Active Directory Domain ====
* [[Storage Pools]] -- the pool a share is provisioned from
[[Active Directory Leave|To leave a domain]] first navigate to the ''Network Shares'' section and press the ''Active Directory Configuration'' button in the toolbar or by right-clicking in the "Network Shares" space and selecting "Active Directory Configuration" from the pop-up menu.  Uncheck the checkbox to disable Active Directory integration and press OK. 
* [[NFS Configuration]] -- the NFS server implementations and system-wide NFS settings
To remove the Computer entry from to AD domain controller one must specify the Domain Administrator username and password. After pressing ''OK'' the selected QuantaStor system will leave the domain.
* [[Multi-protocol File Locking]] -- locking on shares used by NFS and SMB clients at the same time
* [[Active Directory Configuration]] -- joining a system to a domain so AD users and groups can be granted share access
* [[Active Directory Leave]] -- leaving a domain
* [[AD User & Group Information Caching for Large Environments]] -- AD cache tuning for large directories
* [[Enabling Global MMC Management]] -- enabling MMC share management for a whole system
* [[Snapshot Schedules]] -- scheduled snapshots and retention
* [[Remote-replication (DR)]] -- replicating shares on scale-up (ZFS) pools to another system
* [[Scale-out File Replication]] -- replicating shares on scale-out (CephFS) pools to another Ceph Cluster
* [[Backup Policies]] -- copying share data off the system
* [[Cloud Containers / NAS Gateway]] -- cloud containers and the share used as their cache
* [[Security Configuration]] -- users, groups, resource groups and provisioning quotas
* [[Storage Volumes]] -- block (SAN) storage from the same pools
* [[QuantaStor CLI Command Reference#Network_Share_Management_.5BSHARE.5D|QuantaStor CLI Command Reference]] -- the full <code>share-*</code> command set, and the <code>share-namespace-*</code>, <code>share-template-*</code> and quota commands


===== Verifying Users Have CIFS/SMB Passwords =====
----
Older QuantaStor v2 & v3 systems were designed such that user accounts could not be implicitly used for SMB access, just management access.  If a given user has the ''CIFS Ready'' property set to ''Password Change Required'' then the password for that user must be changed before the user account can be used to access SMB/CIFS shares. To do this simply select the user from the ''User & Groups'' section then select "Set Password" to change it via the change password dialog. Administrator users may change the password without having to supply the old password. After the password has been changed the property will update and will now show up as ''SMB/CIFS Ready''.
<small>''Verified against QuantaStor 6.9.0.''</small>

Latest revision as of 16:43, 28 September 2026


A Network Share is a directory that QuantaStor provisions out of a Storage Pool and exports over NFS and SMB at the same time. This page covers what a share is, every tab of the Create and Modify dialogs, NFS client access rules, SMB share options, permissions and ownership, quotas, snapshots, Global Namespaces, and what happens when you delete one.

Section Purpose
What a Network Share is How a share relates to its Storage Pool, and where its data lives
Creating a Network Share The Create Network Share dialog, tab by tab
Modifying a Network Share What the Modify dialog adds, removes and locks
NFS client access Per-client export rules and their NFS options
SMB/CIFS access Share-level SMB options and Active Directory touchpoints
Permissions and ownership POSIX ownership, permissions, and the create masks
Quotas Share space quota, file quota, and per-user/per-group quotas
Snapshots Taking snapshots, browsing them, holds, and restore/rollback/clone
Usage tracking Per-user and per-group capacity collection, and the switches that gate it
Global Namespaces Presenting shares from several systems under one name
Aliases, sub-shares and nested shares Re-presenting part of a share, or nesting one inside another
Configuration Templates Saving a share's settings and applying them to new shares
Enabling, disabling and deleting a share Taking a share offline, and what deletion removes

What a Network Share is

The Network Shares toolbar. Only Create, Modify, Restore, Multi-Delete and Snapshot act on a share directly; everything else is a service, namespace, template or Active Directory operation.

Every Network Share belongs to exactly one Storage Pool and is created from that pool's free space. On a scale-up (ZFS) pool the share is a dataset of its own, a child of the pool dataset, so it gets its own compression, record size, quota and snapshots independently of every other share in the pool. On a scale-out (CephFS) pool the share is a directory in the Ceph file system.

Because the pool owns the share, a share follows its pool: if the pool is configured for high availability and moves to another system in the grid, its shares move with it and are re-exported there. A pool can serve NAS (Network Shares) and SAN (Storage Volumes) at the same time.

A share is reachable over both protocols at once, with no per-protocol copy of the data:

  • SMB clients see it as a share named after the share, served from the pool mount point.
  • NFS clients mount it from /export/<share name>, which is a second mount of the same dataset. The export line pins the NFS fsid to the share's QuantaStor object ID, so the identity a client sees is the share's own and not a device number.

QuantaStor writes both configurations itself: the SMB stanza into /etc/samba/smb.conf and the export line into /etc/exports. Both are regenerated whenever a share is created, modified or deleted -- the exports file says so in its own header -- so hand edits to either are lost. QuantaStor keeps rotating daily backups of both alongside the live files. Scale-out CephFS shares are exported by NFS-Ganesha on port 2249 rather than 2049.

Navigation: the Network Shares section of the tree holds every share in the grid.

Navigation: Storage Management → Network Shares

Selecting a share fills the centre pane with its properties and the right-hand pane with three tabs -- Snapshots, NFS/SMB Access and SMB Sessions -- while the Share Dashboard above offers Capacity, Trends, NFS Stats, SMB Stats, Replication, User Usage and Group Usage.

Where the share operations live

The right-click menu on a Network Share. Most share operations are here only -- the toolbar carries five of them.

The Network Share toolbar group carries only Create, Modify, Restore, Multi-Delete and Snapshot. Everything else is right-click only, so looking for a toolbar button for it is wasted effort:

Operation Where
Create Share, Modify Share, Snapshot Share, Restore Share toolbar and right-click menu
Multi-Delete / Delete Share toolbar (Multi-Delete) and right-click menu (Delete Share...)
Create Share Namespace, Create Alias, Create Backup Policy right-click only
Add NFS Access, Set User/Group Quotas, Move Share (Hierarchically) right-click only
Disable Share, Rollback Share, Clone Share, Remote Replicate Share right-click only
View Mount Command, View Network Share File Locks right-click only
Create Configuration Template right-click only
Configure NFS Services, Restart NFS/SMB Services toolbar (Network Share Services group) and right-click menu

View Mount Command is worth knowing about. It shows the selected share's Share path and a ready-made two-line NFS Mount command -- a mkdir -p for the mount point followed by the mount -t nfs line with the address filled in -- for whichever Network Port you pick from its combo. Both fields are read-only and meant to be copied. It also states where read-only snapshots are reachable from an NFS client.

Creating a Network Share

Navigation: Storage Management → Network Shares → select a Storage Pool or Network Share → Network Share → Create (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Create Share...

Right-clicking an existing share or a Storage Pool pre-selects that pool in the dialog, which is the quickest way to land in the right pool. The dialog has six tabs; OK is available from any of them, so you only need to visit the tabs you intend to change.

The pool type decides what the dialog offers. On a scale-out (CephFS) pool the entire Advanced Settings tab, the Nested Share options, Immutability and the NFS Security Mode are disabled, and Ransomware Detection is unavailable -- those are scale-up (ZFS) features. Conversely Enable File Quota is only selectable on a CephFS pool.

General tab

The General tab of Create Network Share, with Enable Quota selected. Quota is off by default, and Enable File Quota is greyed out because the selected pool is scale-up (ZFS).
Field Notes
Name Pre-filled with a generated name (share-1, share-2, ...). This becomes the SMB share name and the last element of the NFS export path, so keep it to characters a client can type.
Description Free text, shown in the share list.
Copy Settings from Template Select Template... opens a chooser of saved Configuration Templates and copies the chosen template's settings into the rest of the dialog. See Configuration Templates.
Storage Pool The pool the share is provisioned from. Changing it re-reads the pool type and re-applies every type-dependent enablement rule below, and resets the Nested Share options.
Sub Pool Scale-out only: selects which Ceph data pool inside the CephFS file system backs the share. Disabled for scale-up pools.
Storage Pool Settings Read-only summary of the selected pool: utilization bar, Pool Type (Scale-up (ZFS) or Scale-out), RAID Type and Free Space.
Create as new Nested Share / Parent Share Creates the share inside an existing share rather than at the root of the pool. Parent Share stays disabled until the checkbox is ticked, and the whole fieldset is disabled unless the pool is scale-up and the pool already has at least one eligible parent share. See Aliases, sub-shares and nested shares.
Enable Quota → Quota Settings Off by default. Ticking it enables the size field and the percentage slider; dragging the slider fills the size field with that percentage of the pool's free space. See Quotas.
Excludes Snapshot Usage On by default once a quota is enabled, and greyed out on CephFS pools, which do not support it. Ticked, the quota counts only live data; unticked, snapshot space counts against it too.
Enable File Quota → Number of files A cap on the number of files in the share. Selectable only on a scale-out (CephFS) pool.
Enabled The share is exported as soon as it is created. Clearing both Enable CIFS/SMB Access and Enable Public NFS Access forces this off and disables it -- a share with no protocol cannot be active.
Enable CIFS/SMB Access On by default. The master switch for SMB on this share.
Enable Public NFS Access On by default, and creates the [public] NFS client rule that exports the share to every client. Clear it if you intend to add specific client rules instead.
Enable Usage Tracking On by default for scale-up pools and off for scale-out. Collects per-user and per-group capacity and file usage for the share, which is what the User Usage and Group Usage dashboards report. It is a one-way setting on an existing share -- once you tick or clear it explicitly, the share stops following its pool type's default and there is no way back to "follow the pool". See Usage tracking below for the collection intervals and the global switches that can override this checkbox.

User tab

The User tab. The Search... button is only active on the AD Users and AD Groups sub-tabs.

The User tab controls SMB user and group access, and the POSIX ownership of the share. It has no effect on NFS access, which is governed by client rules instead.

Select User Access Mode presents four grids -- Users, Groups, AD Users and AD Groups -- each listing a principal, its Access Mode, Read/Write/Execute flags and its UID:GID. Unless the share is public, every user who needs SMB access has to appear in one of these grids with an access mode other than None; group entries grant access to all members.

  • Users and Groups list the grid's own local accounts, whose UIDs and GIDs QuantaStor generates.
  • AD Users and AD Groups are populated by the Search... button, which is enabled only while one of those two sub-tabs is selected. It opens an Active Directory search dialog; results you accept are added to the grid. To remove an AD principal, set its access mode to None rather than deleting the row.
  • The access modes are None, Valid User, Admin User and Invalid User, and they become the share's Samba valid users, admin users and invalid users lists. Invalid User is an explicit deny, which is how you exclude one member of an otherwise-permitted group. Admin User additionally lets that principal edit the share's Windows ACLs from a Windows client or the MMC, delegating access control to the Windows side.
  • Copy permissions from share copies the AD user and group settings from another share -- useful when a set of shares should share one access list. The picker only offers shares that actually have SMB user access entries.

Ownership Settings sets the POSIX owner of the share directory:

Field Notes
Assigned Owner Defaults to nobody (65534:65534). The owner may change ownership of files and subdirectories in the share and assign SMB ACLs to it.
Assigned Group Defaults to nogroup (65534).

Both combos carry the same caveat: to assign an AD user or group as the owner, add it as a valid user or group on this tab first. Windows ACLs and the access modes here have to agree -- granting a user access through a Windows ACL does nothing if that user is not also a valid user or a member of a valid group on the share.

File Masks & Permission Settings tab

Permission and create-mask defaults: rwxrwxrwx on the share, 0755 for new directories and new files.

Three 3 × 3 grids of Read/Write/Execute checkboxes over User, Group and Other, each with a Select All/Deselect All button that flips the whole grid and re-labels itself once every box is ticked.

Fieldset Applies to Default
Owner Permission Settings The share directory itself. User is the assigned owner, Group the assigned group, Other everyone else. rwxrwxrwx
Directory Create Permissions Mask Directories created inside the share by SMB clients 0755 -- group and other write cleared
File Create Permissions Mask Files created inside the share by SMB clients 0755 -- group and other write cleared

In almost all cases the owner should keep read, write and execute on the share; clearing owner execute makes the directory untraversable.

CIFS/SMB Settings tab

CIFS/SMB Settings. Public, Writable and Browseable (All) are on by default; every advanced option is off.

CIFS/SMB Configuration Options are the share-level SMB switches:

Option Default Effect
Public on Every user can access the share, without appearing on the User tab.
Writable on Clear it to present the share read-only over SMB.
Browseable (All) on The share appears when a Windows client browses the server.
Browseable (Access Based) off Access-based enumeration: the share is visible only to users who have access to it. Ticking this clears Browseable (All) and disables it, since the two are alternatives.
Browseable (Admin Only) off Visible to the share owner only, as a hidden share reached by shareName$. Also clears and disables Browseable (All).

Clearing both of the restricted browse options re-enables and re-ticks Browseable (All).

CIFS/SMB Advanced Options are all off by default. Each exists for a specific interoperability problem rather than as a general improvement, so leave them alone unless you have the problem:

Option Why you would set it
Hide Unreadable Hides files and folders the connecting user cannot read, so a browsing user sees only what they can open.
Hide Unwritable The same for files the user cannot write.
Enable Avid Integration Loads the Unityed Media SMB VFS module, which gives each SMB user their own Avid metadata MXF folder so several editors can work in the same Avid project folder at once. Set it for Avid Media Composer shares and nothing else.
Enable Auditing Records SMB file operations on this share. Auditing covers SMB/CIFS access only -- NFS activity is not audited -- and the log is written per system to /var/log/samba/audit.log, rotated at 1 GB and kept for five generations. Which operations are recorded, and the syslog facility and prefix used, come from /opt/osnexus/quantastor/conf/qs_smb_audit_defaults.conf; those values are read once at service start, so a change there needs a service restart. (The checkbox's tooltip names quantastor.conf instead; that is incorrect -- see QSTOR-12381.)
Disable Oplocks Turns off opportunistic client-side locking and SMB2/SMB3 leases, so SMB clients stop caching file data and byte-range locks. Tick it on any share that NFS and SMB clients use at the same time: with oplocks on, NFS and SMB locks do not see each other and SMB clients can read stale data -- see Multi-protocol File Locking. Also needed for a few applications that mishandle oplock breaks. It costs SMB performance, most on small or lock-heavy I/O.
Ignore System ACLs Makes Samba ignore the POSIX ACLs on the filesystem, so the share's own permissions decide access. Use it when a Windows-managed ACL set and the underlying POSIX ACLs are fighting each other.
Windows & macOS Extended ACLs Turns on extended attributes, Samba's acl_xattr module and ACL inheritance, so Windows-style ACLs are stored and inherited. This is what makes managing the share's permissions from the Microsoft Management Console work.
macOS Extended Attributes Turns on extended attribute support and Samba's streams_xattr module, so NTFS-style alternate data streams -- which is how macOS stores resource forks -- are held in extended attributes.
macOS Interop Enhancements Loads Samba's fruit module, its macOS interoperability layer.
DOS Extended Attributes Stores the DOS hidden/system/archive/read-only attributes in extended attributes instead of mapping them onto the POSIX permission bits.
Extended Attributes Plain extended attribute support, for applications that store their own metadata that way.

Shares can also be managed from the Windows Server Microsoft Management Console Share Management section, which is handy in mixed-vendor environments. To turn that on for a whole system rather than per share, see Enabling Global MMC Management.

Security Settings tab

Security Settings, with Anomaly Detection enabled so the auto-tune, threshold and filtering fieldsets become editable.

Three unrelated groups of settings share this tab.

Anomaly Detection watches file modify and delete events on the share and raises an alert when the rate crosses a threshold you set -- the signature of ransomware encrypting a file tree in bulk, and equally of a runaway script or a mistaken recursive delete. The checkbox is off by default and the three fieldsets below it stay disabled until it is ticked. It is not available on scale-out (CephFS) pools, and the service refuses to enable it on RPM-based distributions (RedHat, Alma).

Detection is per subdirectory. Every event is attributed to the directory it happened in, and each directory carries an hourly and a daily count. A modify counts distinct files touched, so a client rewriting the same file all afternoon contributes one; a delete counts every event, because a file can only be deleted once. The share's figure is the sum across its subdirectories, and the alert names the single busiest one -- which is the useful part of it, because that is where you start looking.

Field Notes
Hourly Modify Threshold Distinct files modified per hour, summed across the share's subdirectories. Must be greater than 0 -- a zero modify threshold would mean "alert on any activity at all", and the service rejects it.
Hourly Delete Threshold File deletes per hour. Leave it at 0 to exclude deletes from detection entirely.
Daily Modify Threshold Distinct files modified per day. Also has to be greater than 0.
Daily Delete Threshold File deletes per day, and may likewise be left at 0.

A threshold fires when the count reaches it rather than when it is exceeded, so a threshold of 15 alerts on the fifteenth file. The tab's own header carries the warning that matters here: setting delete thresholds costs performance, because delete events then have to be tracked as well as modifies.

Ticking auto-tuning clears and disables the four manual thresholds and makes Auto-tune Duration editable.

Auto-tune Thresholds exists because nobody knows what a share's normal traffic looks like before it has run for a while. Set the thresholds too low and every backup window pages someone; set them too high and the detector never fires. Tick Enable Anomaly Detection Parameter Auto-tuning and QuantaStor measures instead. Auto-tune Duration is a number of days -- 7 by default, 1 to 30 -- during which the filesystem monitor records the peak hourly and daily modify and delete counts the share actually sees. When the window closes, the four thresholds are set to twice those observed peaks and the share begins detecting against them.

Two consequences are worth knowing before you use it:

  • No threshold alerts are raised for the share while it is auto-tuning. The window is a learning period and the share has no thresholds of its own during it -- the four manual fields read 0 and are disabled. Auto-tune a share that is already under attack and you teach it that the attack is normal.
  • Auto-tuning an idle share leaves a hair trigger. With no modify activity in the window there is no peak to double, so the thresholds fall back to built-in defaults of 3 modifies per hour and 10 per day. Choose a window that covers the share's real workload, month-end included.

Ticking auto-tuning clears the four manual thresholds and disables them, since they are about to be derived; clearing it again puts back whatever you had typed. Auto-tune Duration is editable only once auto-tuning is ticked.

In the Modify dialog, a share that is currently auto-tuning also shows a read-only Anomaly Auto-tune Ends date, and two rules apply to it:

  • Changing the duration adjusts the open window from when it started rather than restarting it, so cutting a 7-day window to 3 days on day 2 closes it on day 3. That is deliberate: an unrelated edit to a calibrating share re-sends the same duration when you click OK, and it has to be a no-op instead of buying another full week.
  • Clearing the auto-tuning checkbox ends the window immediately and the thresholds you type take effect from that point. You have to supply non-zero hourly and daily modify thresholds to do it, because a calibrating share has none of its own to fall back on, and the dialog refuses OK until you do.

The CLI equivalents are qs share-create --enable-anomaly-detection=true --anomaly-thresholds=hourlyModify:15,hourlyDelete:10,dailyModify:25,dailyDelete:20, with --auto-threshold-calibration-duration=<days> instead of the thresholds to auto-tune, and qs share-modify --cancel-auto-threshold-calibration=true -- accompanied by --anomaly-thresholds -- to end a window early. Re-sending a duration adjusts the window in place, as in the dialog.

Anomaly Detection Filtering narrows what is watched, using either include rules or exclude rules -- the two radio buttons are mutually exclusive and selecting one disables the other's panel. A rule is a substring, not a glob: /subdirA/ or .pdf. An include rule limits detection to paths containing that substring; an exclude rule drops paths containing it. Filtering on delete events matches against the subdirectory path only and does not see the file name.

Include rules combine with AND, not OR. A path has to contain every rule in the include list to be watched, so adding a second rule narrows the set rather than widening it: with /keep/ and /deep/ both listed, activity in /keep/plain/ is ignored and only /keep/deep/ is watched. Use a single include rule unless you specifically want that intersection. Exclude rules behave the way the list reads -- a path matching any one of them is dropped.

What happens when a detection fires. The filesystem monitor records the event and the management service turns it into a Critical alert within a few minutes, named for the threshold that was crossed -- Hourly Modify Threshold / Possible Ransomware Detected, and the daily and delete equivalents. The alert text carries the share's mount point, the busiest subdirectory and the count observed, and it goes out through Alert Manager like any other alert. Repeats of the same alert for the same share are suppressed for an hour, so a sustained burst raises one alert rather than one every few minutes.

Detection alerts, and nothing more: it does not block the writes, disconnect the client or take a snapshot of its own. Recovery is yours to do, from the share's own snapshots -- so if a share is worth watching, give it a snapshot schedule as well, and consider a hold on the snapshots you most want kept, since a hold puts a snapshot out of reach of both the retention policy and an accidental delete.

Anomaly Detection is independent of the Immutability / Write-Once-Read-Many (WORM) Support fieldset below and the two combine freely on one share. Both are served by the same per-pool filesystem monitor, which reads its configuration from /mnt/storage-pools/qs-<pool-id>/.monitor.conf; only the live share is watched, and its snapshots are not monitored in their own right. Turning detection on does not restrict deleting the share, unlike immutability.

Immutability / Write-Once-Read-Many (WORM) Support is create-time only -- the fieldset does not appear in the Modify dialog, so a share cannot be made immutable after the fact. None is the default; Immutable marks files in the share immutable, and Days of Immutability sets how long. A value of 0 means immutability never expires. An immutable share cannot be deleted without the force flag, and QuantaStor auto-creates a snapshot with a hold on it to prevent deletion. Clearing that hold is necessary but not sufficient -- the delete then fails with OSN_ERR_HAS_SNAPSHOTS, because the check is on the snapshot count rather than on the hold. Removing an immutable share takes three steps: clear the hold, delete the snapshot, then delete the share with --flags=force.

NFS Advanced Options has one field, Security Mode, with three values:

Value Meaning
inherit Default. Use the system-wide NFS security policy.
kerberos Require Kerberos security for this share.
system Use AUTH_SYS for this share, overriding a system-wide Kerberos policy.

The point of the per-share override is that a system configured for Kerberos can still carry shares that do not require it. The system-wide default is set in NFS Configuration. On a CephFS pool this field is forced to inherit and disabled.

Advanced Settings tab

Advanced Settings. Every control here is scale-up (ZFS) only and the whole tab greys out on a scale-out pool.

Share Data Options are the dataset properties. Each is inherited from the Storage Pool unless you set it here, and each applies to this share alone:

Field Default Notes
Compression on on, off, lzjb, lz4, gzip and gzip-1..gzip-9, zle, zstd and zstd-1..zstd-19, zstd-fast and zstd-fast-1..zstd-fast-10. Raise it for highly compressible data and accept the CPU cost; set it to off for data that is already compressed, such as media or archives.
Sync Policy standard standard commits writes the client tagged as synchronous through the pool's intent log and writes the rest straight to disk. always sends everything through the intent log first -- slower, but safe against clients that do not tag their writes correctly. disabled ignores synchronous write requests; selecting it raises a confirmation warning that it can cause data integrity problems and is not for production. An SSD write log device on the pool accelerates every synchronous workload.
Cache Policy Primary all What the in-memory read cache holds for this share: all, metadata or none.
Cache Policy Secondary all The same for the pool's SSD read cache. Both combos are disabled on pools that do not support cache policy.
Record Size Auto Auto, or 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M. The upper bound on the block size the share writes in. Large sequential files favour a large record size; small random writes favour a small one.
Small Block Offload Inherit Inherit, or 4K through 256K. Writes at or below this size are routed to the pool's metadata offload device group instead of the data devices. Where you set it explicitly, a value between 8K and 32K is the recommendation.
Read Only off Presents the share read-only over both protocols.
Case Sensitivity Sensitive Sensitive, Insensitive or Mixed file-name matching. Create-time only -- it does not appear in the Modify dialog, because it cannot be changed on an existing dataset. Windows clients expect case-insensitive behaviour; set this deliberately for SMB-only shares.

Snapshot Browsing Options decide which of the several snapshot browsing routes are open on this share. The defaults are deliberately restrictive -- only the Windows Previous Versions route is left on:

Option Default Effect
Disable SMB VSS GMT snapshots off (so VSS is available) Turns off the Previous Versions tab in a Windows client's file properties.
Disable SMB _snaps folder browsing of activated GMT snapshots on Blocks SMB access to activated writable snapshots through a _snaps folder.
Disable NFS _snaps folder browsing of activated GMT snapshots on The same for NFS.
Disables explicit NFS snapshot browsing of .zfs/.snap folder on Hides the hidden snapshot directory (.zfs on scale-up pools, .snap on scale-out) from NFS clients.
Disable NFS cross-mount access to share off (so cross-mount is on) Removes the crossmnt export option, which is what lets an NFS client traverse from this export into filesystems mounted beneath it.

The last three are disabled for shares that cannot have snapshots, and the two _snaps options are disabled on CephFS pools.

Cloud Container Options has one checkbox, Use As Cloud Container Cache Share, which nominates the share as the local cache for cloud containers rather than as a general-purpose share. It is create-time only -- the Modify dialog shows it disabled. See Cloud Containers / NAS Gateway.

Batch Create creates several identically configured shares in one operation, numbering them from the name you gave. It accepts 1 to 10000 and appears in the Create dialog only.

Modifying a Network Share

Navigation: Storage Management → Network Shares → select a Network Share → Network Share → Modify (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Modify Share...
Modify Network Share. The Storage Pool is fixed, Share Options differ from the Create dialog, and a Force checkbox sits at the bottom.

The Modify dialog carries the same six tabs and the same fields, with these differences:

  • A Network Share combo at the top selects which share to edit; switching shares reloads every tab from that share.
  • Storage Pool is read-only. A share cannot be moved between pools by modifying it -- use Clone Share... into the target pool instead.
  • The Nested Share Options fieldset shows the Parent Share for reference only; both the checkbox and the combo are unavailable.
  • Share Options loses Enable Public NFS Access and gains Active Replica Checkpoint. NFS access on an existing share is managed through client rules, not a checkbox, so clearing public NFS access after the fact means removing the [public] client rule. Active Replica Checkpoint is only selectable on a share that already is one, or whose name contains chkpnt.
  • Case Sensitivity, Immutability / WORM, Use As Cloud Container Cache Share and Batch Create are absent or disabled -- all of them are decided at creation.
  • A Force checkbox at the bottom of the General tab. Its tooltip states the one case it is needed for: renaming a share requires Force.
  • Enable Quota reflects the share's current quota, and the size field shows the quota that is set rather than a percentage of free space.

One more rule looks like a fault otherwise: on an alias the Share Data Options, the permission masks and the Ownership Settings are all disabled, and on a sub-share the Share Data Options are. Those values belong to the parent share -- see Aliases, sub-shares and nested shares.

NFS client access

QuantaStor serves NFSv3 and NFSv4 concurrently; which one a client gets is decided by the client's mount options. The NFS server implementation and the system-wide settings -- including the NFSv4-only mode and the default security policy -- are covered in NFS Configuration; this section is about the per-share client rules.

Access is granted per client by a client filter: an IP address, a network, a netgroup, a host or domain wildcard, or [public] for everyone. Each rule becomes one entry in the share's /etc/exports line, carrying its own NFS options. A share's rules are listed on the NFS/SMB Access tab of the right-hand pane when the share is selected.

Adding a client rule

Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Add NFS Access...
Add NFS Client Access. The radio button decides which filter field is used; Allow Full Port Range Access is on by default.

Pick one of the five filter kinds -- the radio button decides which field is read, and typing in a field selects its radio button for you:

Filter Example
Public (unsecure) [public] -- every client
Local IP Address 192.168.1.100
Network 192.168.1.0/24
Network Group @netgroup
Host/Domain *.example.com

Modifying a client rule

Navigation: Storage Management → Network Shares → select a Network Share → NFS/SMB Access (tab) → an NFS Client Access entry (select + right-click) → Modify NFS Client Access...
Modify NFS Client Access on a share's default public rule. Allow Root Access has appended no_root_squash to the custom options field.

The same Network Share NFS Client Access Settings appear in both dialogs, and the wording of each is worth reading before you set it:

Setting Default Notes
Read Only off This client may read but not write the share.
Allow Full Port Range Access on Permits clients to connect from source ports at or above 1024, rather than requiring a reserved port below 1024. This is the NFS insecure export option, and QuantaStor turns it on by default for new rules.
Subtree checks off Asks the NFS server to security-check nested exports. QuantaStor does not allow nested NFS exports, so this has no benefit and may cost performance. Leave it off.
Async Writes off Lets the server acknowledge a write before it is on stable storage. It is faster and it violates the NFS protocol; the dialog's own tooltip says "Not recommended".
Allow Root Access off A convenience toggle that appends no_root_squash to the Custom NFS Export Options field, and strips it again when cleared. Without it, root on the client is mapped to an unprivileged user.
Custom NFS Export Options empty A comma-delimited list of raw NFS export options, for anything the checkboxes do not cover -- for example all_squash,anonuid=150,anongid=100.
Filter Priority → Auto / Priority Auto Ordering matters in an exports file: the first matching entry wins. With Auto ticked QuantaStor decides the order; clearing it enables the Priority combo (1 to 9) so you can force a specific rule ahead of a broader one -- a single host rule ahead of the network rule that also matches it, for instance.

To remove a rule, right-click it on the NFS/SMB Access tab and choose Remove NFS Client Access....

SMB/CIFS access

SMB is configured in three places, and mixing them up is the usual source of "the permissions look right but the user cannot get in":

  1. Whether the share is served over SMB at all -- the Enable CIFS/SMB Access checkbox on the General tab.
  2. Who may connect -- the Public checkbox on the CIFS/SMB Settings tab, or the per-user and per-group access modes on the User tab.
  3. How the share behaves once connected -- the rest of the CIFS/SMB Settings tab, plus the ownership and permission masks.

Active Directory is the fourth piece. Joining a system to a domain is what makes the AD Users and AD Groups grids usable, and it is a per-system operation: each QuantaStor system must be joined individually, and a system can belong to only one domain at a time. The toolbar carries Join AD Domain and Leave AD Domain in the Active Directory group:

Navigation: Storage Management → Network Shares → Active Directory → Join AD Domain (toolbar)

The join procedure, its requirements and its troubleshooting live on Active Directory Configuration, and leaving a domain on Active Directory Leave. Two AD facts bear directly on shares:

  • QuantaStor caches AD user and group names with their UID/GID mappings so that searching from the web interface is fast. If you have just added a principal to AD, search for it by its exact name -- specific lookups bypass the cache and will find it even when the cache is stale.
  • In large AD environments (tens of thousands of principals or more) the cache scan can time out and leave the AD grids empty. See AD User & Group Information Caching for Large Environments for the pre-caching options that fix it.

Restart NFS/SMB Services in the Network Share Services toolbar group restarts both file services on the system. Restarting the file services drops client connections, so treat it as a maintenance action rather than a first troubleshooting step.

Permissions and ownership

A Network Share has two layers of access control that must agree:

  • POSIX ownership and permissions on the share directory -- the Assigned Owner and Assigned Group on the User tab, and the Owner Permission Settings on the File Masks & Permission Settings tab. These are what NFS clients see and enforce.
  • SMB user and group access -- the access modes on the User tab, and optionally Windows ACLs set from a Windows client by an Admin user.

The create masks are a third, separate thing: they apply to files and directories that SMB clients create inside the share, not to the share itself. A share whose owner permission is rwxrwxrwx but whose file create mask is 0755 will accept new files that only their creator can write, which is usually what you want and occasionally surprising.

Per-user and per-group storage limits are set in a separate dialog; see Quotas.

Quotas

Three different limits, in two different dialogs.

Share space quota

The share space quota caps the total space one share may consume from its pool, independently of how much the pool has free. Set it with Enable Quota on the General tab of the Create or Modify dialog, either by typing a size with a suffix or by dragging the slider to a percentage of the pool's free space.

Excludes Snapshot Usage decides what counts toward it. Ticked -- the default -- only live data counts, so a burst of snapshot growth cannot fill the quota. Unticked, snapshot space counts as well. The two are alternatives, not a pair: setting one always clears the other, and clearing the quota removes both. Scale-out (CephFS) shares do not support the distinction and the checkbox is disabled for them.

A quota smaller than 1 MiB is raised to 1 MiB.

qs share-modify --share=<share> --space-quota=<size> --space-quota-exclude-snapshots=<true|false> does the same from the CLI, and --space-quota=0 removes the quota. Two CLI-specific traps:

  • The CLI default is not the dialog default. The dialog ticks Excludes Snapshot Usage; omitting --space-quota-exclude-snapshots on the CLI gives you the other behaviour, with snapshot space counted.
  • share-modify ignores the flag on its own. You have to pass --space-quota in the same command, otherwise the whole quota block is skipped and the flag has no effect.

File quota

A cap on the number of files rather than the space they occupy, set with Enable File Quota on the General tab. It applies to scale-out (CephFS) shares only; on a scale-up pool the checkbox is greyed out. The CLI argument is --file-quota.

Per-user and per-group quotas

Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Set User/Group Quotas...
The Network Share User & Group Quota Manager. The right-hand grid lists quotas already on the share with each principal's current utilization.

The Network Share User & Group Quota Manager limits how much a single user or group may store inside one share. Limits apply to both local and Active Directory principals and are enforced over NFS and SMB alike.

Pick the share at the top -- the dialog only offers shares whose type supports quotas -- and the Network Share Information panel confirms its system, pool and current utilization. Then:

  1. Select principals in the Users & Groups list on the left, which has Users, AD Users and AD Groups sub-tabs.
  2. Enter a Quota Size (or drag the slider). The field is pre-filled with 10GiB.
  3. Click Add Quota >>. The principal appears in the Network Share User & Group Quotas grid on the right with its quota and its current utilization.

<< Remove Quota takes a selected entry back off the share, and Copy From Share below the grid copies an entire quota set from another share. Apply commits without closing the dialog, which is convenient when working through several shares.

The equivalent CLI commands are qs share-user-quota-add --share=<share> --user=<user> --quota-size=<size> and qs share-group-quota-add --share=<share> --user-group=<group> --quota-size=<size>, with matching share-user-quota-remove and share-group-quota-remove. Sizes take a suffix -- 4G, 100M, 1.4T. Active Directory principals are named DOMAIN+name.

Note: qs share-quota-list currently prints its table twice and duplicates rows (QSTOR-12373); read the quotas from the Quota Manager dialog until that is fixed.

Tenant-level caps on how much a resource group may provision in total are a separate mechanism, configured with the provisioning-quota-* commands and described under resource groups in Security Configuration.

Reservations

A quota is a ceiling; a reservation is a floor. Reserving space guarantees a share that much capacity out of its pool, so no other share can consume it. Reservations are CLI only -- there is no field for one in the Create or Modify Network Share dialog, and the share detail panel does not display it. Set it with qs share-create --reserved=<size> or qs share-modify --reserved=<size>, and read it back from the Reserved column of qs share-list.

Three things to know before using it:

  • A reservation can only grow. share-modify rejects a smaller value than the share already has.
  • It applies to scale-up (ZFS) shares only. The value is accepted and stored on other share types, and on an alias or sub-share, but nothing applies it.
  • A Configuration Template carries it. A template captured from a share that has a reservation will apply that reservation to shares created from it in the web interface, even though no dialog can enter one.

Usage tracking

Enable Usage Tracking on a share's General tab turns on collection of per-user and per-group capacity and file counts, which is what the User Usage and Group Usage dashboards report and what makes the per-user quota utilization figures meaningful.

The per-share checkbox is not the only switch. Collection is also gated globally, per filesystem type, by /opt/osnexus/quantastor/conf/qs_shareusage.conf:

Key Default Controls
zfs_usage_tracking_enabled true Whether any scale-up (ZFS) share collects usage
ceph_usage_tracking_enabled false The same for scale-out (CephFS) shares
zfs_interval_minutes 60 How often ZFS shares are sampled
ceph_interval_minutes 1440 How often CephFS shares are sampled
top_n 10 How many top users and groups per share are recorded
retention_weeks 12 How long usage statistics are kept

Two consequences of that table are worth spelling out, because they are the usual reason usage figures look missing:

  • A false global overrides the per-share checkbox. Because ceph_usage_tracking_enabled ships as false, a CephFS share with Enable Usage Tracking ticked still collects nothing until the global is turned on. That is deliberate -- CephFS collection walks the directory tree, where ZFS reads the figures straight out of the filesystem, which is why the shipped Ceph interval is a day rather than an hour.
  • Usage is sampled, not live. A newly written file shows up at the next interval, so up to an hour later on a ZFS share.

The first five keys are re-read on the service's own one-minute tick, so a change to them takes effect within a minute without a restart. retention_weeks is applied by the statistics database setup and needs a service restart.

Shares that are cloud containers, and shares whose directory does not exist, are skipped regardless of the settings.

Snapshots

Navigation: Storage Management → Network Shares → select a Network Share → Network Share → Snapshot (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Snapshot Share...
Snapshot Network Share. The default GMT timestamp name is what snapshot browsing from Windows clients relies on.

A snapshot is a space-efficient point-in-time copy of the share, taken instantly. Scale-up (ZFS) and scale-out (CephFS) shares support snapshots; standard shares and Ceph object gateway shares do not, and the dialog refuses to open on those.

Field Notes
Network Share The share to snapshot, with its Storage Pool shown read-only beneath.
Create snapshot using default GMT timestamp name The default. Produces a UTC name of the form @GMT-2026.09.03-03.36.09, which is the exact format Windows clients read for the Previous Versions tab. Keep it unless you have a reason not to. This choice also makes the snapshot lazy: the writable copy is not materialized until something needs it, which costs no extra space and saves CPU and memory. Scheduled snapshots always take this path.
Create snapshot with custom name Enables the Name field. A custom name is easier for a person to recognise, but it is not picked up by Windows snapshot browsing, and the snapshot is made writable straight away rather than lazily. Names containing GMT are rejected, so a hand-made snapshot cannot impersonate a timestamped one.
Description Free text.
Active On by default. An active snapshot is exported and browsable; an inactive one exists but is not presented to clients.

The Snapshots tab of the right-hand pane lists a share's snapshots with the Schedule that created each one and its Retention Tags -- which is how you tell a hand-made snapshot from one a schedule owns.

Browsing snapshots

A share's snapshots are presented in three different ways, each governed by one of the Snapshot Browsing Options on the Advanced Settings tab:

Route How a client reaches it Default
Windows Previous Versions The Previous Versions tab of a file or folder's Properties in Windows Explorer. This is Samba's shadow-copy support reading the timestamped @GMT- snapshots, which is why the default name format matters. available
The _snaps folder A folder beside the share holding one entry per activated snapshot. Available over SMB and over NFS, each with its own switch. blocked on both protocols
The hidden snapshot directory .zfs on a scale-up share, .snap on scale-out, reached explicitly by an NFS client. blocked

So out of the box a Windows user can recover a file from a snapshot themselves, and an NFS or SMB user cannot browse snapshots at all. Open the other routes deliberately.

Holds

A hold pins a snapshot so that nothing can remove it -- not the Delete Network Shares dialog, and not a snapshot schedule's retention expiry. That makes it the right tool for a snapshot you need to keep for an audit or an investigation while schedules continue to rotate the rest.

Add and remove one with qs share-hold-add --share=<snapshot> --hold-tag=<tag> and qs share-hold-remove --share=<snapshot>. Points worth knowing:

  • Tags are prefixed and there is only one. A tag you supply is prefixed with QS- if it does not start that way, an omitted tag becomes QS-keep (or QS- plus the schedule id for a scheduled snapshot), and a second hold on the same snapshot is refused.
  • The hold outlives the QuantaStor database. It is a hold on the underlying filesystem snapshot, so even a direct filesystem-level destroy is refused until the hold is released.
  • Immutable shares get one automatically. A share created with WORM/Immutable protection has a held snapshot auto-created specifically to block deletion. Clearing the hold is only the first step -- the snapshot itself must then be deleted before the share can be removed, because the delete check counts snapshots rather than holds.

qs share-list --include-snapshots=true --snapshots-with-holds-only=true lists what is currently held.

Snapshot schedules

Taking snapshots on a timetable, with retention, is the job of a Snapshot Schedule rather than this dialog. A schedule holds a set of shares, a timetable and a retention count, and the snapshots it creates are tagged with the schedule's retention tags so it can expire them later. The relationship runs both ways and matters when you come to remove things:

  • Deleting a share that is used by, or was previously created by, a snapshot schedule requires the force flag. QuantaStor refuses otherwise, and names the schedule in the error.
  • Snapshots can outlive the schedule that made them. The Delete Network Shares dialog has a Select All Orphaned Snapshots button for exactly those -- snapshots on the chosen pool that are no longer associated with a schedule.

See Snapshot Schedules for setting them up. For copies that leave the system entirely, see Backup Policies.

Restore, rollback, clone and promote

Four related right-click operations, easy to confuse:

Operation What it does
Restore Share... Returns the share's contents to a chosen snapshot. It works with any snapshot, but it is a file-level copy rather than an instant operation: QuantaStor takes the share offline for the duration, copies the snapshot's contents back over the live share, then re-exports it. Plan for the outage on a large share.
Rollback Share... The same result, instantly, but only for the most recent snapshot -- newer snapshots have to be deleted first. It fails if the share is in use.
Clone Share... Creates a new, fully independent share from a snapshot, into a pool you choose. It is a full copy, not a thin clone, so it takes time and space proportional to the data -- and it is the way to get a share into a different Storage Pool. To get one onto a different system, use Remote Replicate Share... instead. Scale-up (ZFS) pools only.
Promote Share Swaps a snapshot into the parent's place: the parent is renamed aside and the snapshot takes its name. Reversible -- running it again on a promoted share demotes it.

Global Namespaces

Navigation: Storage Management → Network Shares → Global Namespaces → Create (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Create Share Namespace...
Create Network Share Namespace. Selected systems advertise the namespace; selected shares are the ones it presents.

A Network Share Namespace -- Global Namespaces on the toolbar -- gathers shares from one or more systems and presents them under a single name on all of the selected systems. A client can then connect to any member system and be redirected to whichever system actually holds the share, using Microsoft DFS for SMB and NFSv4 referrals for NFS. It removes the need for clients to know which system a share lives on.

Field Notes
Name / Description The namespace name is what clients connect to.
Microsoft DFS Grouped, Flat (default) or Disabled. Flat presents the member shares at the root of each server, without the namespace name in the path. Grouped puts them under a folder named after the namespace, so namespace ns1 with share1 and share2 presents as /ns1/share1 and /ns1/share2 from every server. Disabled means the namespace is not presented over SMB at all.
NFSv4 Referrals Flat (default) or Disabled. There is no grouped mode for NFS.
Scope Namespace to Selected Systems Tick each system that should advertise the namespace, and choose its Network Ports. Auto (all available IP addresses) -- the default -- advertises every address that system has; selecting specific ports restricts redirection to those addresses, which is what you want when only some of a system's interfaces are on the client network.
Select Network Share(s) The dual list of member shares, with a Search box and Reset for narrowing a long list. Both a system selection and a share selection are required.

Underneath, the two modes produce two different pieces of configuration on every member system: DFS referral entries in that system's generated SMB configuration, and NFSv4 refer= targets appended to its export lines. A client connecting to any member is redirected from there to the system that holds the data.

Two membership rules and one precedence rule matter in practice:

  • A share can belong to only one namespace, and cloud-backup shares, nested shares and Ceph shares cannot join one at all.
  • For a share on a high-availability pool, the pool's virtual interfaces win over --preferred-ports. Redirection has to point at an address that follows the pool when it moves, so the HA pool's VIF list takes precedence over the per-system port selection. Setting preferred ports on such a system has no effect on those shares.

Modify changes the name, description and the two modes; share-namespace-add-shares and share-namespace-remove-shares add and remove members. Deleting a namespace does not delete its member shares -- but note the converse: a share that belongs to a namespace cannot be deleted until it is removed from the namespace, and QuantaStor names the namespace in the error.

The CLI equivalents are qs share-namespace-create --name=<name> --preferred-ports=<list> --share-list=<list> and the rest of the share-namespace-* family. Passing a Storage System name rather than a port to --preferred-ports selects automatic address selection for that system.

Do not confuse these with Ceph pool namespaces (ceph-pool-namespace-*), which isolate workloads inside a Ceph pool and have nothing to do with share presentation.

Aliases, sub-shares and nested shares

Three ways to present something other than a plain top-level share, all reached from the right-click menu or the CLI:

Kind Created with What it is
Alias Create Alias..., or qs share-create-alias --name=<name> --parent-share=<share> A second export name for exactly the same directory as the parent share. Use it to present one share under two names with different access control.
Sub-share The same command with --subpath=<dir> An export of a subdirectory of the parent share. The directory is created if it does not exist and the path may be nested several levels deep.
Nested share Create as new Nested Share on the General tab, or --parent-share on qs share-create A share of its own created inside another share rather than at the pool root. Scale-up pools only, and only where the pool already has an eligible parent.

The difference that matters is whether the child has storage of its own:

Alias Sub-share Nested share
Own dataset no no yes
Own quota and reservation no no yes
Own snapshots no no yes
Own name, description, NFS client rules, SMB access, CIFS options yes yes yes

An alias or sub-share therefore has its own access control and nothing else. That is why the Modify dialog disables the Share Data Options for a sub-share, and the Share Data Options, the permission masks and the Ownership Settings for an alias: those values live on the parent's dataset, so editing them through the child would change the parent. It also explains three behaviours that otherwise look like faults:

  • Snapshotting an alias or sub-share snapshots the parent. The request is redirected; you do not get a snapshot of just the child.
  • Rollback and Restore are refused on an alias or sub-share, and the error names the parent to use instead. Rolling the parent back rolls its aliases and sub-shares back with it.
  • Clone is refused on all three kinds.

Aliases and sub-shares cannot be chained -- the parent of an alias must be a real share -- and they are not available on scale-out, Ceph object gateway or cloud shares. --inherit-access copies the parent's cifs or nfs access entries to the new alias at creation; without it the alias starts with none.

Deleting an alias removes only the export and the object: because the data belongs to the parent, the files are left in place. Deleting a sub-share does remove its directory.

Move Share (Hierarchically)... re-parents an existing share, and is the qs share-move --share=<share> --new-parent=<share> operation.

Configuration Templates

Navigation: Storage Management → Network Shares → Configuration Templates → Create (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Create Configuration Template...

A Configuration Template captures an existing share's settings so that new shares can be created with them, which is how you keep a set of shares consistent without re-filling six tabs each time. Templates are listed on the Configuration Templates tab beside the Network Shares list.

Create a template from a share you have already configured the way you want. When creating a share, Select Template... on the General tab applies one; a template mask decides which groups of settings are copied -- all of them, or just the general, user, permissions, CIFS, NFS, security or advanced groups. The CLI equivalents are qs share-template-create, share-template-apply and qs share-create-from-template. One template may be marked as the default.

Where you only want to align two existing shares, qs share-copy-settings --share=<target> --share-copy-settings-source=<source> copies one share's settings onto another directly, with no template object in between. There is no equivalent button in the interface -- the Copy permissions from share button on the User tab copies the SMB access list only.

Enabling, disabling and deleting a share

Disabling

Disable Share... on the right-click menu -- or clearing Enabled in the Modify dialog, or qs share-disable --share=<share> -- takes the share out of service. Disabling does three things: it marks the share offline, it regenerates /etc/samba/smb.conf and /etc/exports with the share's entries dropped from both, and it kills any process still holding an open file handle on the share. That last step is what makes disabling reliable, and it is also why you should not use it casually on a share with active clients.

The share's data is not touched: the dataset stays mounted where it was, and Enable puts the share straight back into both configuration files.

The two switches on the General tab are not the same thing:

Switch Effect
Enabled Protocol-agnostic. Drops the SMB stanza and the NFS export line, and marks the share offline.
Enable CIFS/SMB Access SMB only. Drops the SMB stanza; the NFS export line and the share's client rules are untouched and the share stays online.

There is one interlock worth knowing, because otherwise it looks like the dialog ignored you: if you leave Enabled ticked but clear Enable CIFS/SMB Access on a share that has no NFS client rules, the share ends up offline anyway, with the state detail "No access via SMB or NFS has been configured, share is offline." A share with no protocol cannot be online.

Deleting

Navigation: Storage Management → Network Shares → Network Share → Multi-Delete (toolbar)
Navigation: Storage Management → Network Shares → Network Share (select + right-click) → Delete Share...
Delete Network Shares. Hide Snapshots is ticked by default, so snapshots are not listed until you clear it.

Both routes open the same Delete Network Shares dialog, which deletes any number of shares and snapshots in one operation.

Control Notes
Search and Filter Settings Storage System and Storage Pool narrow the candidate list, Quick Search filters it by name. Hide Aliases and Hide Snapshots are both ticked by default, so snapshots do not appear until you clear the box.
Select the Network Shares (and/or Snapshots) to Delete A dual list. The arrows move selections; you can also drag, with Ctrl for individual items and Shift for a range. The Selected side reports the space that will be recovered.
Select All Snapshots Selects every snapshot on the chosen Storage Pool.
Select All Orphaned Snapshots Selects only snapshots on that pool that are no longer associated with a replication schedule.
Force Required when one or more of the selected shares is in use, and for the refusals listed below.
Delete Child Snapshots Only Deletes the selected shares' snapshots and leaves the shares themselves in place.

Deletion destroys the share's data. The share's directory contents are removed recursively, its SMB stanza and its export line are dropped from the generated configuration files, and its database record and metadata file are removed. There is no undo, which is why the dialog asks for confirmation and reports how many shares are about to go. The exception is an alias, whose files belong to its parent and are left in place.

QuantaStor refuses the delete outright in these cases, rather than deleting something you may still need:

Refused when What to do
The share has snapshots Delete the snapshots first, or select them alongside the share in this dialog.
The share has sub-shares, aliases or nested shares under it Remove the children first.
The share belongs to a Global Namespace Remove it from the namespace first. The error names the namespace.
The share, or one of its snapshots, has a hold on it Clear the hold, then delete the snapshot -- clearing the hold alone leaves the delete failing on the snapshot count. Immutable shares get an auto-created snapshot with a hold precisely to stop this.
The share's Storage Pool is not mounted or active Bring the pool online. If the pool no longer exists at all, the share's record is simply removed.

Two more cases are refused unless Force is set: a share marked immutable, and a share that is used by, or was created by, a snapshot or replication schedule. A share nominated as a Cloud Container cache also needs Force, and its cloud containers should be removed first.

Where multi-admin approval covers Network Share deletes, a delete raises an approval request instead of running, and the task reports how many of the required approvals have been met.

Related pages


Verified against QuantaStor 6.9.0.