diff options
Diffstat (limited to 'docs-xml/manpages/vfs_fileid.8.xml')
| -rw-r--r-- | docs-xml/manpages/vfs_fileid.8.xml | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/docs-xml/manpages/vfs_fileid.8.xml b/docs-xml/manpages/vfs_fileid.8.xml new file mode 100644 index 0000000..8732f95 --- /dev/null +++ b/docs-xml/manpages/vfs_fileid.8.xml @@ -0,0 +1,282 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<refentry id="vfs_fileid.8"> + +<refmeta> + <refentrytitle>vfs_fileid</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="source">Samba</refmiscinfo> + <refmiscinfo class="manual">System Administration tools</refmiscinfo> + <refmiscinfo class="version">&doc.version;</refmiscinfo> +</refmeta> + + +<refnamediv> + <refname>vfs_fileid</refname> + <refpurpose>Generates file_id structs with unique device id values for + cluster setups. It also adds ways to deliberately break lock coherency for specific inodes</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>vfs objects = fileid</command> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This VFS module is part of the + <citerefentry><refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry> + suite.</para> + + <para>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 <command>stat()</command> 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 + <command>SMB_VFS_FILE_ID_CREATE()</command> operation and + generates the device number based on the configured algorithm + (see the "fileid:algorithm" option). + </para> + + <para>When using the fsname or fsid algorithm a + <command>stat()</command> and <command>statfs()</command> 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. + </para> +</refsect1> + + +<refsect1> + <title>OPTIONS</title> + + <variablelist> + + <varlistentry> + <term>fileid:algorithm = ALGORITHM</term> + <listitem> + <para>Available algorithms are <command>fsname</command>, + <command>fsid</command>, <command>next_module</command>. The default value is + <command>fsname</command>. As well as the following legacy + algorithms: <command>fsname_nodirs</command>, <command>fsname_norootdir</command>, + <command>fsname_norootdir_ext</command> and <command>hostname</command>. + </para> + + <para>The <command>fsname</command> algorithm generates + device id by hashing the kernel device name. + </para> + + <para>The <command>fsid</command> algorithm generates + the device id from the <command>f_fsid</command> returned + from the <command>statfs()</command> syscall. + </para> + + <para>The <command>next_module</command> 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. + </para> + + <para>The legacy <command>hostname</command> algorithm generates unique + devid by hashing the hostname and low level device id. + It also implies <command>fileid:nolock_all_inodes=yes</command>. + This can be used to deliberately break lock coherency in a cluster + and with <command>fileid:nolock_max_slots</command> 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 <command>fileid:nolock_all_inodes=yes</command>. + </para> + + <para>The legacy <command>fsname_nodirs</command> algorithm is an alias + for using the <command>fsname</command> algorithm together with + <command>fileid:nolock_all_dirs=yes</command>. + NOTE: Do not use this without knowing what you are doing! + It breaks SMB semantics! + See <command>fileid:nolock_paths</command> for a more fine grained + approach. + </para> + + <para>The legacy <command>fsname_norootdir</command> algorithm is an alias + for using the <command>fsname</command> algorithm together with + <command>fileid:nolock_paths= <quote>.</quote> </command>. It means + this can be used to deliberately break lock coherency + in a cluster for the root directory of a share. + </para> + + <para>The legacy <command>fsname_norootdir_ext</command> algorithm is an alias + for using the <command>fsname</command> algorithm together with + <command>fileid:nolock_paths= <quote>.</quote></command> and + <command>fileid:nolock_max_slots = 18446744073709551615</command>. + 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. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:mapping = ALGORITHM</term> + <listitem> + <para>This option is the legacy version of the + <command>fileid:algorithm</command> option, which was used in earlier + versions of fileid mapping feature in custom Samba 3.0 versions. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:fstype deny = LIST</term> + <listitem> + <para>List of file system types to be ignored for file_id + generation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:fstype allow = LIST</term> + <listitem> + <para>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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:mntdir deny = LIST</term> + <listitem> + <para>List of file system mount points to be ignored for + file_id generation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:mntdir allow = LIST</term> + <listitem> + <para>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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:nolock_max_slots = NUMBER(1-18446744073709551615)</term> + <listitem> + <para>This option alters the behavior of the <command>nolock</command> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:nolock_all_dirs = BOOL</term> + <listitem> + <para>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 <command>fileid:nolock_paths</command> for a more fine grained + approach. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:nolock_all_inodes = BOOL</term> + <listitem> + <para>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 <command>fileid:nolock_paths</command> for a more fine grained + approach. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:nolock_paths = LIST</term> + <listitem> + <para>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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>fileid:nolockinode = NUMBER</term> + <listitem> + <para>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 <command>fileid:nolock_paths</command> option is much more flexible and simpler to use. + </para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>EXAMPLES</title> + + <para>Usage of the <command>fileid</command> module with the + <command>fsid</command> algorithm:</para> + +<programlisting> + <smbconfsection name="[global]"/> + <smbconfoption name="vfs objects">fileid</smbconfoption> + <smbconfoption name="fileid:algorithm">fsid</smbconfoption> +</programlisting> + + <para>Usage of the <command>fileid</command> module in order + avoid load on heavily contended (most likely read-only) inodes.</para> + +<programlisting> + <smbconfsection name="[global]"/> + <smbconfoption name="vfs objects">fileid</smbconfoption> + <smbconfoption name="fileid:algorithm">next_module</smbconfoption> + <smbconfoption name="fileid:nolock_paths">. ContendedFolder1 /path/to/contended.exe</smbconfoption> + <smbconfoption name="fileid:nolock_max_slots">256</smbconfoption> +</programlisting> + +</refsect1> + +<refsect1> + <title>VERSION</title> + + <para>This man page is part of version &doc.version; of the Samba suite. + </para> +</refsect1> + +<refsect1> + <title>AUTHOR</title> + + <para>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.</para> + +</refsect1> + +</refentry> |