source3/modules/The_New_VFS.txt

   1                      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   2                              THE NEW SAMBA VFS
   3
   4                       Ralph Böhme, SerNet, Samba Team
   5                      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   6
   7
   8                                  2021-01-14
   9
  10
  11 Table of Contents
  12 ─────────────────
  13
  14 1. The new VFS
  15 .. 1. Summary
  16 .. 2. Samba and O_PATH
  17 ..... 1. Background
  18 ..... 2. Usecases for O_PATH in Samba
  19 ..... 3. When to open with O_PATH
  20 ..... 4. Fallback on systems without O_PATH support
  21 ..... 5. When to use fsp_get_io_fd() or fsp_get_pathref_fd()
  22 2. VFS status quo and remaining work
  23 .. 1. VFS Functions Tables [2]
  24 ..... 1. Existing VFS Functions
  25 ..... 2. New VFS Functions
  26 .. 2. VFS functions by category
  27 ..... 1. Disk operations
  28 ..... 2. Handle based VFS functions
  29 ..... 3. Namespace changing VFS functions
  30 ..... 4. Path based VFS functions
  31 ..... 5. AT VFS functions that can't be based on handles
  32 ..... 6. AT VFS functions needed for directory enumeration
  33 ..... 7. Handle based VFS functions not allowed on O_PATH opened handles
  34 ..... 8. Pure path to path translation
  35 ..... 9. Special cases
  36
  37
  38 1 The new VFS
  39 ═════════════
  40
  41 1.1 Summary
  42 ───────────
  43
  44   The effort to modernize Samba's VFS interface has reached a major
  45   milestone with the next release Samba 4.14.
  46
  47   Starting with version 4.14 Samba provides core infrastructure code that
  48   allows basing all access to the server's filesystem on file handles and
  49   not on paths. An example of this is using `fstat()' instead of `stat()',
  50   or `SMB_VFS_FSTAT()' instead of `SMB_VFS_STAT()' in Samba parlance.
  51
  52   Historically Samba's fileserver code had to deal a lot with processing
  53   path based SMB requests. While the SMB protocol itself has been
  54   streamlined to be purely handle based starting with SMB2, large parts of
  55   infrastructure code remains in place that will "degrade" handle based SMB2
  56   requests to path based filesystem access.
  57
  58   In order to fully leverage the handle based nature of the SMB2 protocol we
  59   came up with a straight forward way to convert this infrastructure code.
  60
  61   At the core, we introduced a helper function that opens a file handle that
  62   only serves as a path reference and hence can not be used for any sort of
  63   access to file data.
  64
  65   Samba's internal file handle structure is of type `struct files_struct'
  66   and all variable pointing to objects of such type are typically called
  67   `fsp'. Until very recently the only function that would open such a file
  68   handle and return an fsp was `SMB_VFS_CREATE_FILE()'.
  69
  70   Internally `SMB_VFS_CREATE_FILE()' consisted of processing through Samba's
  71   VFS open function to open the low level file and then going through
  72   Samba's Windows NTFS emulation code.
  73
  74   The key point of the new helper function which is called
  75   `openat_pathref_fsp()' is that it skips the NTFS emulation
  76   logic. Additionally, the handle is restricted internally to be only usable
  77   as a path reference but not for any sort of IO. On Linux this is achieved
  78   by using the `O_PATH' `open()' flag, on systems without `O_PATH' support
  79   other mechanisms are used described in more detail below.
  80
  81   Path processing in Samba typically means processing client supplied paths
  82   by Samba's core path processing function `filename_convert()' which returs
  83   a pointer to an object of type `struct smb_filename'. Pointers to such
  84   objects are then passed around, often passing many layers of code.
  85
  86   By attaching an `fsp' file handle returned from `openat_pathref_fsp()' to
  87   all `struct smb_filename' objects returned from `filename_convert()', the
  88   whole infrastructure code has immediate access to a file handle and so the
  89   large infrastructure codebase can be converted to use handle based VFS
  90   functions whenever VFS access is done in a piecemeal fashion.
  91
  92
  93 1.2 Samba and O_PATH
  94 ────────────────────
  95
  96 1.2.1 Background
  97 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  98
  99   On Linux the `O_PATH' flag to `open()' can be used to open a filehandle on
 100   a file or directory with interesting properties: [1]
 101
 102   • the file-handle indicates a location in the filesystem tree,
 103
 104   • no permission checks are done by the kernel on the filesystem object and
 105
 106   • only operations that act purely at the file descriptor level are
 107     allowed.
 108
 109   The file itself is not opened, and other file operations (e.g., `read(2)',
 110   `write(2)', `fchmod(2)', `fchown(2)', `fgetxattr(2)', `ioctl(2)',
 111   `mmap(2)') fail with the error `EBADF'.
 112
 113   The following subset of operations that is relevant to Samba is allowed:
 114
 115   • `close(2)',
 116
 117   • `fchdir(2)', if the file descriptor refers to a directory,
 118
 119   • `fstat(2)',
 120
 121   • `fstatfs(2)' and
 122
 123   • passing the file descriptor as the dirfd argument of `openat()' and the
 124     other "*at()" system calls. This includes `linkat(2)' with AT_EMPTY_PATH
 125     (or via procfs using AT_SYMLINK_FOLLOW) even if the file is not a
 126     directory.
 127
 128   Opening a file or directory with the `O_PATH' flag requires no permissions
 129   on the object itself (but does require execute permission on the
 130   directories in the path prefix). By contrast, obtaining a reference to a
 131   filesystem object by opening it with the `O_RDONLY' flag requires that the
 132   caller have read permission on the object, even when the subsequent
 133   operation (e.g., `fchdir(2)', `fstat(2)') does not require read permis‐
 134   sion on the object.
 135
 136   If for example Samba receives an SMB request to open a file requesting
 137   `SEC_FILE_READ_ATTRIBUTE' access rights because the client wants to read
 138   the file's metadata from the handle, Samba will have to call `open()' with
 139   at least `O_RDONLY' access rights.
 140
 141
 142 1.2.2 Usecases for O_PATH in Samba
 143 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 144
 145   The `O_PATH' flag is currently not used in Samba. By leveraging this Linux
 146   specific flags we can avoid permission mismatches as described above.
 147
 148   Additionally `O_PATH' allows basing all filesystem accesses done by the
 149   fileserver on handle based syscalls by opening all client pathnames with
 150   `O_PATH' and consistently using for example `fstat()' instead of `stat()'
 151   throughout the codebase.
 152
 153   Subsequent parts of this document will call such file-handles opened with
 154   O_PATH *path referencing file-handles* or *pathref*s for short.
 155
 156
 157 1.2.3 When to open with O_PATH
 158 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 159
 160   In Samba the decision whether to call POSIX `open()' on a client pathname
 161   or whether to leave the low-level handle at -1 (what we call a stat-open)
 162   is based on the client requested SMB acccess mask.
 163
 164   The set of access rights that trigger an `open()' includes
 165   `READ_CONTROL_ACCESS'. As a result, the open() will be done with at least
 166   `O_RDONLY'. If the filesystem supports NT style ACLs natively (like GPFS
 167   or ZFS), the filesystem may grant the user requested right
 168   `READ_CONTROL_ACCESS', but it may not grant `READ_DATA' (`O_RDONLY').
 169
 170   Currently the full set of access rights that trigger opening a file is:
 171
 172   • FILE_READ_DATA
 173   • FILE_WRITE_DATA
 174   • FILE_APPEND_DATA
 175   • FILE_EXECUTE
 176   • WRITE_DAC_ACCESS
 177   • WRITE_OWNER_ACCESS
 178   • SEC_FLAG_SYSTEM_SECURITY
 179   • READ_CONTROL_ACCESS
 180
 181   In the future we can remove the following rights from the list on systems
 182   that support O_PATH:
 183
 184   • WRITE_DAC_ACCESS
 185   • WRITE_OWNER_ACCESS
 186   • SEC_FLAG_SYSTEM_SECURITY
 187   • READ_CONTROL_ACCESS
 188
 189
 190 1.2.4 Fallback on systems without O_PATH support
 191 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 192
 193   The code of higher level file-handle consumers must be kept simple and
 194   streamlined, avoiding special casing the handling of the file-handles
 195   opened with or without `O_PATH'. To achieve this, a fallback that allows
 196   opening a file-handle with the same higher level semantics even if the
 197   system doesn't support `O_PATH' is needed.
 198
 199   The way this is implemented on such systems is impersonating the root user
 200   for the `open()' syscall. In order to avoid privelege escalations security
 201   issues, we must carefully control the use these file-handles.
 202
 203   The low level filehandle is stored in a public struct `struct file_handle'
 204   that is part of the widely used `struct files_struct'. Consumers used to
 205   simply access the fd directly by derefencing pointers to `struct
 206   files_struct'.
 207
 208   In order to guard access to such file-handles we do two things:
 209
 210   • tag the pathref file-handles and
 211
 212   • control access to the file-handle by making the structure `struct
 213        file_handle' private, only allowing access with accessor functions
 214        that implement a security boundary.
 215
 216   In order to avoid bypassing restrictive permissions on intermediate
 217   directories of a client path, the root user is only impersonated after
 218   changing directory to the parent directory of the client requested
 219   pathname.
 220
 221   Two functions can then be used to fetch the low-level system file-handle
 222   from a `struct files_struct':
 223
 224   • `fsp_get_io_fd(fsp)': enforces fsp is NOT a pathref file-handle and
 225
 226   • `fsp_get_pathref_fd(fsp)': allows fsp to be either a pathref file-handle
 227     or a traditional POSIX file-handle opened with O_RDONLY or any other
 228     POSIX open flag.
 229
 230   Note that the name `fsp_get_pathref_fd()' may sound confusing at first
 231   given that the fsp can be either a pathref fsp or a "normal/full" fsp, but
 232   as any full file-handle can be used for IO and as path reference, the name
 233   correctly reflects the intended usage of the caller.
 234
 235
 236 1.2.5 When to use fsp_get_io_fd() or fsp_get_pathref_fd()
 237 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 238
 239   The general guideline is:
 240
 241   • if you do something like `fstat(fd)', use `fsp_get_pathref_fd()',
 242
 243   • if you do something like `*at(dirfd, ...)', use `fsp_get_pathref_fd()',
 244
 245   • if you want to print the fd for example in `DEBUG' messages, use
 246     `fsp_get_pathref_fd()',
 247
 248   • if you want to call `close(fd)', use `fsp_get_pathref_fd()',
 249
 250   • if you're doing a logical comparison of fd values, use
 251     `fsp_get_pathref_fd()'.
 252
 253   In any other case use `fsp_get_io_fd()'.
 254
 255
 256 2 VFS status quo and remaining work
 257 ═══════════════════════════════════
 258
 259 2.1 VFS Functions Tables [2]
 260 ────────────────────────────
 261
 262 2.1.1 Existing VFS Functions
 263 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 264
 265   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 266    VFS Function                       Group       Status
 267   ───────────────────────────────────────────────────────
 268    SMB_VFS_AIO_FORCE()                [fsp]       -
 269    SMB_VFS_AUDIT_FILE()               [Special]   -
 270    SMB_VFS_BRL_LOCK_WINDOWS()         [fsp]       -
 271    SMB_VFS_BRL_UNLOCK_WINDOWS()       [fsp]       -
 272    SMB_VFS_CHDIR()                    [Path]      Todo
 273    SMB_VFS_CHFLAGS()                  [Path]      Todo
 274    SMB_VFS_CHMOD()                    [Path]      -
 275    SMB_VFS_CLOSE()                    [fsp]       -
 276    SMB_VFS_CLOSEDIR()                 [fsp]       -
 277    SMB_VFS_CONNECT()                  [Disk]      -
 278    SMB_VFS_CONNECTPATH()              [P2px]      -
 279    SMB_VFS_CREATE_DFS_PATHAT()        [NsC]       -
 280    SMB_VFS_CREATE_FILE()              [NsC]       -
 281    SMB_VFS_DISCONNECT()               [Disk]      -
 282    SMB_VFS_DISK_FREE()                [Disk]      -
 283    SMB_VFS_DURABLE_COOKIE()           [fsp]       -
 284    SMB_VFS_DURABLE_DISCONNECT()       [fsp]       -
 285    SMB_VFS_DURABLE_RECONNECT()        [fsp]       -
 286    SMB_VFS_FALLOCATE()                [fsp]       -
 287    SMB_VFS_FCHMOD()                   [fsp]       -
 288    SMB_VFS_FCHOWN()                   [fsp]       -
 289    SMB_VFS_FCNTL()                    [fsp]       -
 290    SMB_VFS_FDOPENDIR()                [fsp]       -
 291    SMB_VFS_FGET_COMPRESSION()         [fsp]       -
 292    SMB_VFS_FGET_DOS_ATTRIBUTES()      [fsp]       -
 293    SMB_VFS_FGET_NT_ACL()              [fsp]       -
 294    SMB_VFS_FGETXATTR()                [xpathref]  -
 295    SMB_VFS_FILE_ID_CREATE()           [Special]   -
 296    SMB_VFS_FLISTXATTR()               [xpathref]  -
 297    SMB_VFS_FREMOVEXATTR()             [xpathref]  -
 298    SMB_VFS_FS_CAPABILITIES()          [Disk]      -
 299    SMB_VFS_FSCTL()                    [fsp]       -
 300    SMB_VFS_FSET_DOS_ATTRIBUTES()      [fsp]       -
 301    SMB_VFS_FSET_NT_ACL()              [fsp]       -
 302    SMB_VFS_FSETXATTR()                [xpathref]  -
 303    SMB_VFS_FS_FILE_ID()               [Special]   -
 304    SMB_VFS_FSTAT()                    [fsp]       -
 305    SMB_VFS_FSYNC()                    [fsp]       -
 306    SMB_VFS_FSYNC_SEND()               [fsp]       -
 307    SMB_VFS_FTRUNCATE()                [fsp]       -
 308    SMB_VFS_GET_ALLOC_SIZE()           [fsp]       -
 309    SMB_VFS_GET_DFS_REFERRALS()        [Disk]      -
 310    SMB_VFS_GET_DOS_ATTRIBUTES_RECV()  [Enum]      -
 311    SMB_VFS_GET_DOS_ATTRIBUTES_SEND()  [Enum]      -
 312    SMB_VFS_GETLOCK()                  [fsp]       -
 313    SMB_VFS_GET_NT_ACL_AT()            [Path]      Todo
 314    SMB_VFS_GET_QUOTA()                [Special]   -
 315    SMB_VFS_GET_REAL_FILENAME()        [P2px]      -
 316    SMB_VFS_GET_SHADOW_COPY_DATA()     [fsp]       -
 317    SMB_VFS_GETWD()                    [Special]   -
 318    SMB_VFS_GETXATTR()                 [Path]      Todo
 319    SMB_VFS_GETXATTRAT_RECV()          [Enum]      -
 320    SMB_VFS_GETXATTRAT_SEND()          [Enum]      -
 321    SMB_VFS_KERNEL_FLOCK()             [fsp]       -
 322    SMB_VFS_LCHOWN()                   [Path]      Todo
 323    SMB_VFS_LINKAT()                   [NsC]       -
 324    SMB_VFS_LINUX_SETLEASE()           [fsp]       -
 325    SMB_VFS_LISTXATTR()                [Path]      -
 326    SMB_VFS_LOCK()                     [fsp]       -
 327    SMB_VFS_LSEEK()                    [fsp]       -
 328    SMB_VFS_LSTAT()                    [Path]      Todo
 329    SMB_VFS_MKDIRAT()                  [NsC]       -
 330    SMB_VFS_MKNODAT()                  [NsC]       -
 331    SMB_VFS_NTIMES()                   [Path]      -
 332    SMB_VFS_OFFLOAD_READ_RECV()        [fsp]       -
 333    SMB_VFS_OFFLOAD_READ_SEND()        [fsp]       -
 334    SMB_VFS_OFFLOAD_WRITE_RECV()       [fsp]       -
 335    SMB_VFS_OFFLOAD_WRITE_SEND()       [fsp]       -
 336    SMB_VFS_OPENAT()                   [NsC]       -
 337    SMB_VFS_PREAD()                    [fsp]       -
 338    SMB_VFS_PREAD_SEND()               [fsp]       -
 339    SMB_VFS_PWRITE()                   [fsp]       -
 340    SMB_VFS_PWRITE_SEND()              [fsp]       -
 341    SMB_VFS_READ_DFS_PATHAT()          [Symlink]   Todo
 342    SMB_VFS_READDIR()                  [fsp]       -
 343    SMB_VFS_READDIR_ATTR()             [Path]      Todo
 344    SMB_VFS_READLINKAT()               [Symlink]   -
 345    SMB_VFS_REALPATH()                 [P2px]      -
 346    SMB_VFS_RECVFILE()                 [fsp]       -
 347    SMB_VFS_REMOVEXATTR()              [Path]      -
 348    SMB_VFS_RENAMEAT()                 [Path]      Todo
 349    SMB_VFS_REWINDDIR()                [fsp]       -
 350    SMB_VFS_SEEKDIR()                  [fsp]       -
 351    SMB_VFS_SENDFILE()                 [fsp]       -
 352    SMB_VFS_SET_COMPRESSION()          [fsp]       -
 353    SMB_VFS_SET_DOS_ATTRIBUTES()       [Path]      -
 354    SMB_VFS_SET_QUOTA()                [Special]   -
 355    SMB_VFS_SETXATTR()                 [Path]      -
 356    SMB_VFS_SNAP_CHECK_PATH()          [Disk]      -
 357    SMB_VFS_SNAP_CREATE()              [Disk]      -
 358    SMB_VFS_SNAP_DELETE()              [Disk]      -
 359    SMB_VFS_STAT()                     [Path]      Todo
 360    SMB_VFS_STATVFS()                  [Disk]      -
 361    SMB_VFS_STREAMINFO()               [Path]      -
 362    SMB_VFS_STRICT_LOCK_CHECK()        [fsp]       -
 363    SMB_VFS_SYMLINKAT()                [NsC]       -
 364    SMB_VFS_SYS_ACL_BLOB_GET_FD()      [xpathref]  -
 365    SMB_VFS_SYS_ACL_BLOB_GET_FILE()    [Path]      Todo
 366    SMB_VFS_SYS_ACL_DELETE_DEF_FILE()  [Path]      Todo
 367    SMB_VFS_SYS_ACL_GET_FD()           [xpathref]  -
 368    SMB_VFS_SYS_ACL_GET_FILE()         [Path]      Todo
 369    SMB_VFS_SYS_ACL_SET_FD()           [xpathref]  -
 370    SMB_VFS_TELLDIR()                  [fsp]       -
 371    SMB_VFS_TRANSLATE_NAME()           [P2px]      -
 372    SMB_VFS_UNLINKAT()                 [NsC]       -
 373   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 374
 375
 376 [fsp] See section 2.2.2
 377
 378 [Special] See section 2.2.9
 379
 380 [Path] See section 2.2.4
 381
 382 [Disk] See section 2.2.1
 383
 384 [P2px] See section 2.2.8
 385
 386 [NsC] See section 2.2.3
 387
 388 [xpathref] See section 2.2.7
 389
 390 [Enum] See section 2.2.6
 391
 392 [Symlink] See section 2.2.5
 393
 394
 395 2.1.2 New VFS Functions
 396 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 397
 398   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 399    VFS Function                     Group       Status
 400   ─────────────────────────────────────────────────────
 401    SMB_VFS_SYS_ACL_DELETE_DEF_FD()  [xpathref]  Todo
 402    SMB_VFS_READDIR_ATTRAT()         [Enum]      Todo
 403    SMB_VFS_FNTIMENS()               [fsp]       -
 404   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 405
 406
 407 [xpathref] See section 2.2.7
 408
 409 [Enum] See section 2.2.6
 410
 411 [fsp] See section 2.2.2
 412
 413
 414 2.2 VFS functions by category
 415 ─────────────────────────────
 416
 417 2.2.1 Disk operations
 418 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 419
 420   • SMB_VFS_CONNECT()
 421   • SMB_VFS_DISCONNECT()
 422   • SMB_VFS_DISK_FREE()
 423   • SMB_VFS_FS_CAPABILITIES()
 424   • SMB_VFS_GET_DFS_REFERRALS()
 425   • SMB_VFS_SNAP_CHECK_PATH()
 426   • SMB_VFS_SNAP_CREATE()
 427   • SMB_VFS_SNAP_DELETE()
 428   • SMB_VFS_STATVFS()
 429
 430   No changes needed.
 431
 432
 433 2.2.2 Handle based VFS functions
 434 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 435
 436   • SMB_VFS_AIO_FORCE()
 437   • SMB_VFS_BRL_LOCK_WINDOWS()
 438   • SMB_VFS_BRL_UNLOCK_WINDOWS()
 439   • SMB_VFS_CLOSE()
 440   • SMB_VFS_CLOSEDIR()
 441   • SMB_VFS_DURABLE_COOKIE()
 442   • SMB_VFS_DURABLE_DISCONNECT()
 443   • SMB_VFS_FALLOCATE()
 444   • SMB_VFS_FCHMOD()
 445   • SMB_VFS_FCHOWN()
 446   • SMB_VFS_FCNTL()
 447   • SMB_VFS_FDOPENDIR()
 448   • SMB_VFS_FGET_DOS_ATTRIBUTES()
 449   • SMB_VFS_FGET_NT_ACL()
 450   • SMB_VFS_FSCTL()
 451   • SMB_VFS_FSET_DOS_ATTRIBUTES()
 452   • SMB_VFS_FSET_NT_ACL()
 453   • SMB_VFS_FSTAT()
 454   • SMB_VFS_FSYNC()
 455   • SMB_VFS_FSYNC_SEND()
 456   • SMB_VFS_FTRUNCATE()
 457   • SMB_VFS_GETLOCK()
 458   • SMB_VFS_GET_ALLOC_SIZE()
 459   • SMB_VFS_GET_SHADOW_COPY_DATA()
 460   • SMB_VFS_KERNEL_FLOCK()
 461   • SMB_VFS_LINUX_SETLEASE()
 462   • SMB_VFS_LOCK()
 463   • SMB_VFS_LSEEK()
 464   • SMB_VFS_OFFLOAD_READ_SEND()
 465   • SMB_VFS_OFFLOAD_WRITE_SEND()
 466   • SMB_VFS_PREAD()
 467   • SMB_VFS_PREAD_SEND()
 468   • SMB_VFS_PWRITE()
 469   • SMB_VFS_PWRITE_SEND()
 470   • SMB_VFS_READDIR()
 471   • SMB_VFS_RECVFILE()
 472   • SMB_VFS_REWINDDIR()
 473   • SMB_VFS_SEEKDIR()
 474   • SMB_VFS_SENDFILE()
 475   • SMB_VFS_SET_COMPRESSION()
 476   • SMB_VFS_STRICT_LOCK_CHECK()
 477   • SMB_VFS_TELLDIR()
 478
 479   If an fsp is provided by the SMB layer we use that, otherwise we use the
 480   pathref fsp `smb_fname->fsp' provided by `filename_convert()'.
 481
 482
 483 2.2.3 Namespace changing VFS functions
 484 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 485
 486   • SMB_VFS_CREATE_FILE()
 487
 488   All intermediate VFS calls within `SMB_VFS_CREATE_FILE()' will be based on
 489   `smb_fname->fsp' if the requested path exists. When creating a file we
 490   rely on `non_widelink_open()' which doesn't depend on a dirfsp.
 491
 492   • SMB_VFS_MKDIRAT()
 493
 494   Needs a real dirfsp (done).
 495
 496   • SMB_VFS_OPENAT()
 497
 498   Is only called from within `non_widelink_open()' with a dirfsp equivalent
 499   of `AT_FDCWD' and so doesn't need a real dirfsp.
 500
 501   The following operations need a real dirfsp:
 502
 503   • SMB_VFS_LINKAT()
 504   • SMB_VFS_MKNODAT()
 505   • SMB_VFS_RENAMEAT()
 506   • SMB_VFS_SYMLINKAT()
 507   • SMB_VFS_UNLINKAT()
 508
 509   Callers use `openat_pathref_fsp()' to open a fsp on the parent directory.
 510
 511
 512 2.2.4 Path based VFS functions
 513 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 514
 515   All path based VFS functtions will be replaced by handle based variants
 516   using the `smb_fname->fsp' provided by `filename_convert()'.
 517
 518   • SMB_VFS_CHDIR()
 519   • SMB_VFS_CHFLAGS()
 520   • SMB_VFS_CHMOD()
 521   • SMB_VFS_DURABLE_RECONNECT()
 522   • SMB_VFS_GETXATTR()
 523   • SMB_VFS_GET_COMPRESSION()
 524   • SMB_VFS_GET_DOS_ATTRIBUTES()
 525   • SMB_VFS_GET_NT_ACL_AT()
 526   • SMB_VFS_LCHOWN()
 527   • SMB_VFS_LISTXATTR()
 528   • SMB_VFS_LSTAT()
 529   • SMB_VFS_NTIMES()
 530   • SMB_VFS_REMOVEXATTR()
 531   • SMB_VFS_SETXATTR()
 532   • SMB_VFS_SET_DOS_ATTRIBUTES()
 533   • SMB_VFS_STAT()
 534   • SMB_VFS_STREAMINFO()
 535   • SMB_VFS_SYS_ACL_BLOB_GET_FILE()
 536   • SMB_VFS_SYS_ACL_DELETE_DEF_FILE()
 537   • SMB_VFS_SYS_ACL_GET_FILE()
 538   • SMB_VFS_SYS_ACL_SET_FILE()
 539
 540   Replace with corresponding handle based VFS calls.
 541
 542
 543 2.2.5 AT VFS functions that can't be based on handles
 544 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 545
 546   • SMB_VFS_CREATE_DFS_PATHAT()
 547   • SMB_VFS_READ_DFS_PATHAT()
 548   • SMB_VFS_READLINKAT()
 549
 550   As the DFS link implementation is based on symlinks, we have to use *AT
 551   based functions with real dirfsps.
 552
 553
 554 2.2.6 AT VFS functions needed for directory enumeration
 555 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 556
 557   • SMB_VFS_GET_DOS_ATTRIBUTES_SEND()
 558   • SMB_VFS_GETXATTRAT_SEND()
 559   • SMB_VFS_READDIR_ATTRAT() (NEW)
 560
 561
 562 2.2.7 Handle based VFS functions not allowed on O_PATH opened handles
 563 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 564
 565   • SMB_VFS_FGETXATTR()
 566   • SMB_VFS_FLISTXATTR()
 567   • SMB_VFS_FREMOVEXATTR()
 568   • SMB_VFS_FSETXATTR()
 569   • SMB_VFS_SYS_ACL_BLOB_GET_FD()
 570   • SMB_VFS_SYS_ACL_GET_FD()
 571   • SMB_VFS_SYS_ACL_DELETE_DEF_FD() (NEW)
 572   • SMB_VFS_SYS_ACL_SET_FD()
 573
 574   Based upon securely opening a full fd based on `/proc/self/fd/%d' as in
 575   the case of xattrs, pathref handles can't be used for xattr IO, and in the
 576   case of ACLs pathref handles can't be used to access default ACEs.
 577
 578
 579 2.2.8 Pure path to path translation
 580 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 581
 582   • SMB_VFS_CONNECTPATH()
 583   • SMB_VFS_GET_REAL_FILENAME()
 584   • SMB_VFS_REALPATH()
 585   • SMB_VFS_TRANSLATE_NAME()
 586
 587   No changes needed.
 588
 589
 590 2.2.9 Special cases
 591 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 592
 593   • SMB_VFS_FILE_ID_CREATE()
 594   • SMB_VFS_FS_FILE_ID()
 595   • SMB_VFS_GET_QUOTA()
 596   • SMB_VFS_GETWD()
 597   • SMB_VFS_SET_QUOTA()
 598
 599   No changes needed.
 600
 601   • SMB_VFS_AUDIT_FILE()
 602
 603   This is currently unused.
 604
 605
 606
 607 Footnotes
 608 ─────────
 609
 610 [1] parts of the following sections copied from man open(2)
 611
 612 [2] `grep 'SMB_VFS_*' source3/include/vfs_macros.h | grep -v NEXT_ | sed
 613 's|.*\(SMB_VFS_.*\)(.*|\1()|' | sort'