Best practices: Adding Persistent Handle support

Stefan Metzmacher metze at
Fri Jun 2 11:24:57 UTC 2017

Hi Christoph,

> On Thu, Jun 01, 2017 at 09:26:45PM -0500, Christopher R. Hertel via samba-technical wrote:
>> I guess the reason my wording seemed convoluted is that I was thinking of
>> the situation in which, for example, you had three shares on XFS file
>> systems and another two shares on GlusterFS (or some such).  In that case,
>> you want to be specific about which VFS modules you load for which
>> particular shares.  You don't want to load a Persistent Handle module on the
>> XFS shares, for instance.
> For XFS shares (or in fact any Linux file system) you should use the
> open_by_handle_at and name_to_handle_at syscalls.  Of course I'm not
> too familar with the detailed rules of Samba structure, but as a Linux
> user and developer I'd expect these to be just available on a Linux
> setup without having to load magic modules.

I guess 'struct file_handle' of open_by_handle_at() and
name_to_handle_at() is something difference, it's something
like "open by a unique number" instead of "open by path", is that

Persistent handles in SMB3 are more persistent "struct file"
(file description) instances, so all information about an open file is
persistent, e.g. the current seek pointer, all locks and all other

So if the SMB3 client gets disconnected for a while, the open handle
(which is basically a file descriptor referencing a file description)
is still open and the client can resume this "open", without the
need of re-adding locks or doing other recover actions.

What Samba will require from the kernel will be:
- a call that takes an fd and a timeout value and hands out some kind of
  cookie/id that references the file description of the given fd
  and makes sure that the file description remains at for the given
  timeout without having a remaining file descriptor referencing the
  file description.
- a call to "resume" that takes the cookie/id and returns an fd
  that references the file description and resets the expiration timer.

In SMB2/3 there're a few different flavors of these "disconnected"
handles, we have:

- durable handles (which require an exclusive oplock),
  these are best effort by the server, but if a 2nd client
  opens the file, the disconnected handle is closed,
  so the cookie/id would be invalidated.

- resilient handles (which are explicitly requested by the application
  layer): The still running server (kernel) would keep the file
  description valid for the specified timeout, even if another
  client (not knowing the cookie/id) will open the file.

- persistent handles (are requested if the share is marked as
  "continuously available"): These are like resilient handles,
  but they're also persistent across reboots.

A possible design for new syscalls will require thinking about much more
details, but I hope this a useful overview.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: OpenPGP digital signature
URL: <>

More information about the samba-technical mailing list