1VFS_FILEID(8)             System Administration tools            VFS_FILEID(8)
2
3
4

NAME

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

SYNOPSIS

11       vfs objects = fileid
12

DESCRIPTION

14       This VFS module is part of the samba(7) suite.
15
16       Samba uses file_id structs to uniquely identify files for locking
17       purpose. By default the file_id contains the device and inode number
18       returned by the stat() system call. As the file_id is a unique
19       identifier of a file, it must be the same on all nodes in a cluster
20       setup. This module overloads the SMB_VFS_FILE_ID_CREATE() operation and
21       generates the device number based on the configured algorithm (see the
22       "fileid:algorithm" option).
23
24       When using the fsname or fsid algorithm a stat() and statfs() call is
25       required for all mounted file systems to generate the file_id. If e.g.
26       an NFS file system is unresponsive such a call might block and the smbd
27       process will become unresponsive. Use the "fileid:fstype deny",
28       "fileid:fstype allow", "fileid:mntdir deny", or "fileid:mntdir allow"
29       options to ignore potentially unresponsive file systems.
30

OPTIONS

32       fileid:algorithm = ALGORITHM
33           Available algorithms are fsname, fsid, next_module. The default
34           value is fsname. As well as the following legacy algorithms:
35           fsname_nodirs, fsname_norootdir, fsname_norootdir_ext and hostname.
36
37           The fsname algorithm generates device id by hashing the kernel
38           device name.
39
40           The fsid algorithm generates the device id from the f_fsid returned
41           from the statfs() syscall.
42
43           The next_module algorithm lets the next vfs module in the module
44           chain generate the id. This is mainly used in combination with the
45           various 'nolock' features the fileid module provides.
46
47           The legacy hostname algorithm generates unique devid by hashing the
48           hostname and low level device id. It also implies
49           fileid:nolock_all_inodes=yes. This can be used to deliberately
50           break lock coherency in a cluster and with fileid:nolock_max_slots
51           also between local processes within a node. NOTE: Do not use this
52           without knowing what you are doing! It breaks SMB semantics and it
53           can lead to data corruption! This implies
54           fileid:nolock_all_inodes=yes.
55
56           The legacy fsname_nodirs algorithm is an alias for using the fsname
57           algorithm together with fileid:nolock_all_dirs=yes. NOTE: Do not
58           use this without knowing what you are doing! It breaks SMB
59           semantics! See fileid:nolock_paths for a more fine grained
60           approach.
61
62           The legacy fsname_norootdir algorithm is an alias for using the
63           fsname algorithm together with fileid:nolock_paths= “.”. It means
64           this can be used to deliberately break lock coherency in a cluster
65           for the root directory of a share.
66
67           The legacy fsname_norootdir_ext algorithm is an alias for using the
68           fsname algorithm together with fileid:nolock_paths= “.”  and
69           fileid:nolock_max_slots = 18446744073709551615. It means this can
70           be used to deliberately break lock coherency completely for the
71           root directory of a share. Even local processes are no longer lock
72           coherent.
73
74       fileid:mapping = ALGORITHM
75           This option is the legacy version of the fileid:algorithm option,
76           which was used in earlier versions of fileid mapping feature in
77           custom Samba 3.0 versions.
78
79       fileid:fstype deny = LIST
80           List of file system types to be ignored for file_id generation.
81
82       fileid:fstype allow = LIST
83           List of file system types to be allowed for file_id generation. If
84           this option is set, file system types not listed here are ignored.
85
86       fileid:mntdir deny = LIST
87           List of file system mount points to be ignored for file_id
88           generation.
89
90       fileid:mntdir allow = LIST
91           List of file system mount points to be allowed for file_id
92           generation. If this option is set, file system mount points not
93           listed here are ignored.
94
95       fileid:nolock_max_slots = NUMBER(1-18446744073709551615)
96           This option alters the behavior of the nolock algorithm in a ways
97           that it also breaks the lock coherency between individual processes
98           on the same host. The default is to have just 1 concurrent slot
99           available per host. By incressing the number of slots you can
100           specify how many concurrent processes can work on a given inode
101           without contention, the number should typically be larger than the
102           a number of logical cpus, maybe 2 times of num_cpus.
103
104       fileid:nolock_all_dirs = BOOL
105           This option triggers the use of the fileid nolock behavior for all
106           directory inodes, which can be used to deliberately break the lock
107           coherency for all directories. NOTE: Do not use this without
108           knowing what you are doing! It breaks SMB semantics! See
109           fileid:nolock_paths for a more fine grained approach.
110
111       fileid:nolock_all_inodes = BOOL
112           This option triggers the use of the fileid nolock algorithm for all
113           directoriy inode, which can be used to deliberately break the lock
114           coherency for all directories. NOTE: Do not use this without
115           knowing what you are doing! It breaks SMB semantics and it can lead
116           to data corruption! See fileid:nolock_paths for a more fine grained
117           approach.
118
119       fileid:nolock_paths = LIST
120           This option specifies a path list referring to files and/or
121           directories, which should use fileid nolock algorithm in order to
122           deliberately break the lock coherency for them. The specified paths
123           can be relative to the share root directory or absolute. The names
124           are case sensitive unix pathnames! Note all paths are only
125           evaluated at tree connect time, when the share is being connected,
126           from there on only the related device and inode numbers from the
127           stat() syscall are compared. Non existing paths will generate a log
128           level 0 message. NOTE: This option should be used with care as it
129           breaks SMB semantics! But it may help in situation where a specific
130           (commonly read-only) inode is highly contended.
131
132       fileid:nolockinode = NUMBER
133           This legacy option triggers use of the fileid nolock behavior for
134           the configured inode, while ignoring and device id. This can be
135           used to deliberately break lock coherency for the corresponding
136           file or directory in a cluster. Using the fileid:nolock_paths
137           option is much more flexible and simpler to use.
138

EXAMPLES

140       Usage of the fileid module with the fsid algorithm:
141
142                   [global]
143                vfs objects = fileid
144                fileid:algorithm = fsid
145
146       Usage of the fileid module in order avoid load on heavily contended
147       (most likely read-only) inodes.
148
149                   [global]
150                vfs objects = fileid
151                fileid:algorithm = next_module
152                fileid:nolock_paths = . ContendedFolder1 /path/to/contended.exe
153                fileid:nolock_max_slots = 256
154

VERSION

156       This man page is part of version 4.19.3 of the Samba suite.
157

AUTHOR

159       The original Samba software and related utilities were created by
160       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
161       Source project similar to the way the Linux kernel is developed.
162
163
164
165Samba 4.19.3                      11/27/2023                     VFS_FILEID(8)
Impressum