NAME

       vfs_fileid - Generates file_id structs with unique device id values for cluster setups. It
       also adds ways to deliberately break lock coherency for specific inodes

SYNOPSIS

       vfs objects = fileid

DESCRIPTION

       This VFS module is part of the samba(7) suite.

       Samba uses file_id structs to uniquely identify files for locking purpose. By default the
       file_id contains the device and inode number returned by the stat() system call. As the
       file_id is a unique identifier of a file, it must be the same on all nodes in a cluster
       setup. This module overloads the SMB_VFS_FILE_ID_CREATE() operation and generates the
       device number based on the configured algorithm (see the "fileid:algorithm" option).

       When using the fsname or fsid algorithm a stat() and statfs() call is required for all
       mounted file systems to generate the file_id. If e.g. an NFS file system is unresponsive
       such a call might block and the smbd process will become unresponsive. Use the
       "fileid:fstype deny", "fileid:fstype allow", "fileid:mntdir deny", or "fileid:mntdir
       allow" options to ignore potentially unresponsive file systems.

OPTIONS

       fileid:algorithm = ALGORITHM
           Available algorithms are fsname, fsid, next_module. The default value is fsname. As
           well as the following legacy algorithms: fsname_nodirs, fsname_norootdir,
           fsname_norootdir_ext and hostname.

           The fsname algorithm generates device id by hashing the kernel device name.

           The fsid algorithm generates the device id from the f_fsid returned from the statfs()
           syscall.

           The next_module algorithm lets the next vfs module in the module chain generate the
           id. This is mainly used in combination with the various 'nolock' features the fileid
           module provides.

           The legacy hostname algorithm generates unique devid by hashing the hostname and low
           level device id. It also implies fileid:nolock_all_inodes=yes. This can be used to
           deliberately break lock coherency in a cluster and with fileid:nolock_max_slots also
           between local processes within a node. NOTE: Do not use this without knowing what you
           are doing! It breaks SMB semantics and it can lead to data corruption! This implies
           fileid:nolock_all_inodes=yes.

           The legacy fsname_nodirs algorithm is an alias for using the fsname algorithm together
           with fileid:nolock_all_dirs=yes. NOTE: Do not use this without knowing what you are
           doing! It breaks SMB semantics! See fileid:nolock_paths for a more fine grained
           approach.

           The legacy fsname_norootdir algorithm is an alias for using the fsname algorithm
           together with fileid:nolock_paths= “.”. It means this can be used to deliberately
           break lock coherency in a cluster for the root directory of a share.

           The legacy fsname_norootdir_ext algorithm is an alias for using the fsname algorithm
           together with fileid:nolock_paths= “.”  and fileid:nolock_max_slots =
           18446744073709551615. It means this can be used to deliberately break lock coherency
           completely for the root directory of a share. Even local processes are no longer lock
           coherent.

       fileid:mapping = ALGORITHM
           This option is the legacy version of the fileid:algorithm option, which was used in
           earlier versions of fileid mapping feature in custom Samba 3.0 versions.

       fileid:fstype deny = LIST
           List of file system types to be ignored for file_id generation.

       fileid:fstype allow = LIST
           List of file system types to be allowed for file_id generation. If this option is set,
           file system types not listed here are ignored.

       fileid:mntdir deny = LIST
           List of file system mount points to be ignored for file_id generation.

       fileid:mntdir allow = LIST
           List of file system mount points to be allowed for file_id generation. If this option
           is set, file system mount points not listed here are ignored.

       fileid:nolock_max_slots = NUMBER(1-18446744073709551615)
           This option alters the behavior of the nolock algorithm in a ways that it also breaks
           the lock coherency between individual processes on the same host. The default is to
           have just 1 concurrent slot available per host. By incressing the number of slots you
           can specify how many concurrent processes can work on a given inode without
           contention, the number should typically be larger than the a number of logical cpus,
           maybe 2 times of num_cpus.

       fileid:nolock_all_dirs = BOOL
           This option triggers the use of the fileid nolock behavior for all directory inodes,
           which can be used to deliberately break the lock coherency for all directories. NOTE:
           Do not use this without knowing what you are doing! It breaks SMB semantics! See
           fileid:nolock_paths for a more fine grained approach.

       fileid:nolock_all_inodes = BOOL
           This option triggers the use of the fileid nolock algorithm for all directoriy inode,
           which can be used to deliberately break the lock coherency for all directories. NOTE:
           Do not use this without knowing what you are doing! It breaks SMB semantics and it can
           lead to data corruption! See fileid:nolock_paths for a more fine grained approach.

       fileid:nolock_paths = LIST
           This option specifies a path list referring to files and/or directories, which should
           use fileid nolock algorithm in order to deliberately break the lock coherency for
           them. The specified paths can be relative to the share root directory or absolute. The
           names are case sensitive unix pathnames! Note all paths are only evaluated at tree
           connect time, when the share is being connected, from there on only the related device
           and inode numbers from the stat() syscall are compared. Non existing paths will
           generate a log level 0 message. NOTE: This option should be used with care as it
           breaks SMB semantics! But it may help in situation where a specific (commonly
           read-only) inode is highly contended.

       fileid:nolockinode = NUMBER
           This legacy option triggers use of the fileid nolock behavior for the configured
           inode, while ignoring and device id. This can be used to deliberately break lock
           coherency for the corresponding file or directory in a cluster. Using the
           fileid:nolock_paths option is much more flexible and simpler to use.

EXAMPLES

       Usage of the fileid module with the fsid algorithm:

                   [global]
                vfs objects = fileid
                fileid:algorithm = fsid

       Usage of the fileid module in order avoid load on heavily contended (most likely
       read-only) inodes.

                   [global]
                vfs objects = fileid
                fileid:algorithm = next_module
                fileid:nolock_paths = . ContendedFolder1 /path/to/contended.exe
                fileid:nolock_max_slots = 256

VERSION

       This man page is part of version 4.17.7-Ubuntu of the Samba suite.

AUTHOR

       The original Samba software and related utilities were created by Andrew Tridgell. Samba
       is now developed by the Samba Team as an Open Source project similar to the way the Linux
       kernel is developed.