diff --git a/docs-xml/manpages/vfs_fileid.8.xml b/docs-xml/manpages/vfs_fileid.8.xml index defb71229e9..8732f951121 100644 --- a/docs-xml/manpages/vfs_fileid.8.xml +++ b/docs-xml/manpages/vfs_fileid.8.xml @@ -14,7 +14,7 @@ vfs_fileid Generates file_id structs with unique device id values for - cluster setups + cluster setups. It also adds ways to deliberately break lock coherency for specific inodes @@ -61,40 +61,61 @@ fileid:algorithm = ALGORITHM Available algorithms are fsname, - fsname_nodirs, fsid and - hostname. The default value is - 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 fsname_nodirs algorithm generates - device id by hashing the kernel device name for files and by hashing - the hostname for directories. This can be used to deliberately - break lock coherency for directories in a cluster. - + The fsid algorithm generates the device id from the f_fsid returned from the statfs() syscall. - The hostname algorithm generates device - id by hashing the hostname. This can be used to deliberately - break lock coherency in a cluster. + + 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 fsname_norootdir algorithm - generates device ids by hashing the kernel device name, except - for the root directory of shares where it will use the hostname - algorithm. This can be used to deliberately break lock coherency + + 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 fsname_norootdir_ext algorithm - generates device ids by hashing the kernel device name, except - for the root directory of shares where it will use the hostname - algorithm. Additionally it generates an extid based on the - process pid. This can be used to deliberately break lock - coherency between all smbd processes in the whole 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. + @@ -147,12 +168,69 @@ - fileid:nolockinode + fileid:nolock_max_slots = NUMBER(1-18446744073709551615) - This option triggers use of the fileid hostname algorithm - for the configured inode which can be used to deliberately break + 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. + cluster. Using the fileid:nolock_paths option is much more flexible and simpler to use. @@ -171,6 +249,17 @@ fsid + Usage of the fileid module in order + avoid load on heavily contended (most likely read-only) inodes. + + + + fileid + next_module + . ContendedFolder1 /path/to/contended.exe + 256 + +