The semantics of paths in VFS modules

[Richard Sharpe]

On Sat, Apr 2, 2016 at 12:54 PM, Uri Simchoni <uri at samba.org> wrote:
> Hi,
>
> I would like to document the meaning of path names in the wiki
> (add it to the vfs module writing page), and thought I'd first submit it
> to the list to get comments.

In general I like it.

There are some special cases, I think, such as if you allow wide
links, then Samba cannot use paths relative to the root of the share.

Maybe it falls under what you have already written.

> Comments are welcome.
> Thanks,
> Uri.
>
> The Meaning of Path Names
> ==========================
> What's in path names passed down to VFS functions? Are they absolute?
> Are they relative? Relative to what?
>
> The short answer is: "Paths are relative to the root of the share,
> except when they are not". A slightly longer answer is "Paths are either
> absolute or relative to the current working directory". Both answers
> could be confusing to module writers, so the following elaborates on that.
>
> At the SMB protocol level, path names are relative to the root of the
> share. When processing SMB requests, smbd changes the working directory
> (chdir()) to the root of the share, and then typically forwards those
> paths as-is (translated to UTF-8). Thus, a VFS module would *normally*
> see the same path requested by the SMB protocol, which is a path
> relative to the root of the share. However, there are exceptions:
>
> 1. When changing the working directory, smbd also uses the VFS chdir_fn
> function, and is using an absolute path - the path of the share. Thus,
> if you implement chdir_fn, expect to see absolute paths.
>
> 2. Some VFS modules modify the path and forward the request to the layer
> below them. Some of them can modify the path into an absolute path,
> depending on configuration (for example, vfs_shadow_copy2, if configured
> with an absolute snapsharepath).
>
> 3. Finally, smbd itself could use relative paths which are not relative
> to the root of the share. This happens when smbd changes into a
> directory inside the share to perform some "sensitive stuff". One
> example is changing the ownership of the file into that of the parent
> directory (inherit owner = yes). However, the recurring
> pattern with this kind of chdir() is that smbd first makes a *relative*
> chdir (to get into the path inside the share), and then returns to the
> original path using an *absolute* path.
>
> So as a module writer, how do I cope with all this?
>
> Handling Absolute Paths
> -----------------------
> Absolute paths usually have meaning only in the context of real file
> systems. A module that exposes a kernel file system (such as the default
> VFS module or the btrfs module) would have no problem handling an
> absolute path. On the other hand, getting an absolute path can be
> confusing to a module which provides a user-space file system.
>
> As noted above, smbd would only use absolute paths in order to change
> directory into the share's root directory. A user-space module can
> simply ignore this kind of chdir or use it to flag the current state as
> "in share root dir".
>
> On the other hand, some VFS modules could modify the path into an
> absolute path. The simplest way for a user-space file system VFS module
> to deal with that is to say that it cannot be stacked with other modules
> which convert the path to an absolute path.
>
> Handling Relative Paths
> ------------------------
> As explained above, a relative path would *mostly* be relative to the
> share's root, and always relative to the current working directory.
>
> One way to cope with relative paths therefore is to keep track of the
> current working directory. The default VFS module for example does this
> - the kernel keeps track of current directory for it.
>
> The following algorithm could be used by VFS modules to track the
> "current relative working directory", by implementing chdir_fn VFS function:
>
> a. Initial state is "at share's root" - current relative directory is an
> empty string.
> b. A chdir with an absolute path can be assumed to be "back into the
> share's root" - clear the current relative directory (this rule could be
> broken by another VFS module but it's easily verifiable by comparing
> with handle->conn->connectpath).
> c. A chdir with a relative path appends the path to the current relative
> directory.
> d. For any other file operation, to reconstruct the path relative to the
> share's root, append the supplied path to the current relative directory.
>
> A  different way to cope with relative paths is to ignore the cases
> where the current directory is not the share's root either because your
> module doesn't care about the exact location of the file (for example it
> performs some character conversion on path names), or you don't intend
> to support the cases where the current directory is the share's root.
>
>



-- 
Regards,
Richard Sharpe
(何以解憂？唯有杜康。--曹操)