Anyone running a Linux NAS knows the pain of a dropped SMB connection. Restart Samba to apply a change and Windows Explorer hangs, or a VM disk on an SMB share throws I/O errors. SMB3 persistent handles are the protocol feature meant to fix exactly that, and Samba 4.25 is the first release to include them.
The important caveat first, straight from the Samba 4.25 release notes: the feature is experimental, and it has a significant performance cost. The release notes say it’s meant only for workloads that need continuous availability, and not for general-purpose file servers.
What persistent handles do
With persistent handles, Samba writes the state of every open file handle to durable on-disk storage. If the server restarts or the connection is lost, a client that supports them can reconnect and keep using its open files, instead of every handle being invalidated. The release notes name virtual machine storage and clustered databases as the target workloads.
The price is latency: Samba has to persist handle metadata synchronously on every open, update, lease and close. On a ctdb cluster, the new persistent handles durability option chooses between full_outage (the default: handles survive the whole cluster going down) and partial_outage (cheaper; handles survive as long as one node is up).
The locking trade-off
Persistent handles only work on shares that Samba controls exclusively. The release notes require these share settings:
kernel oplocks = no
kernel share modes = no
posix locking = noThat turns off interoperability with local POSIX file access and NFS on the share. If anything else (an NFS export, a container writing to the same path, a local backup script) touches those files, Samba’s locks no longer protect it. Use a dedicated share that only Samba writes to.
Configuring Samba 4.25
Two switches are needed: the global persistent handles option and the per-share continuous availability option.
[global]
server min protocol = SMB3
persistent handles = yes
[vmstore]
path = /tank/vmstore
read only = no
continuous availability = yes
kernel oplocks = no
kernel share modes = no
posix locking = noCheck testparm after editing: it validates the file and shows the options Samba actually understood. Because the feature is new and experimental, read the smb.conf man page of your installed version for these options before relying on them.
Running it
You need Samba 4.25 or later: check with smbd --version. Distribution packages and container images lag behind upstream releases. At the time of writing, for example, the servercontainers/samba image shipped Samba 4.23, which doesn’t have the feature at all. Whatever you run, keep Samba’s state directories on persistent storage: the handle state has to survive a restart for persistent handles to be of any use.
Clients
- Windows negotiates persistent handles itself when the share advertises continuous availability over SMB3.
- Linux (
mount.cifs) has apersistenthandlesmount option. The man page also documents ahandletimeoutoption for how long the server keeps handles for a reconnecting client. - Proxmox VE CIFS storage accepts extra mount options through the
optionsproperty in/etc/pve/storage.cfg. Withsmbversionunset ordefault, it negotiates the highest SMB2+ version both sides support:
cifs: vmstore
server 192.168.1.100
share vmstore
content images
username proxmox
options persistenthandlesNote that Proxmox always mounts CIFS storage with the soft option, so long outages still end in I/O errors on the client side. Persistent handles help with short interruptions, not with a NAS that’s down for minutes.
How to test it
Copy a large file from a client, restart Samba on the server, and watch whether the copy pauses and continues or fails. Test this on non-critical data first, and measure the slowdown on your hardware before putting VM disks on such a share. For most homelab file shares, a plain share without persistent handles remains the better choice.
[discussion]
Comments are powered by Giscus — backed by GitHub Discussions. Sign in with GitHub to join the conversation.