docs-xml/manpages/vfs_fileid.8.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="vfs_fileid.8">
   4
   5 <refmeta>
   6         <refentrytitle>vfs_fileid</refentrytitle>
   7         <manvolnum>8</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>vfs_fileid</refname>
  16         <refpurpose>Generates file_id structs with unique device id values for
  17         cluster setups</refpurpose>
  18 </refnamediv>
  19
  20 <refsynopsisdiv>
  21         <cmdsynopsis>
  22                 <command>vfs objects = fileid</command>
  23         </cmdsynopsis>
  24 </refsynopsisdiv>
  25
  26 <refsect1>
  27         <title>DESCRIPTION</title>
  28
  29         <para>This VFS module is part of the
  30         <citerefentry><refentrytitle>samba</refentrytitle>
  31         <manvolnum>7</manvolnum></citerefentry>
  32         suite.</para>
  33
  34         <para>Samba uses file_id structs to uniquely identify files
  35         for locking purpose. By default the file_id contains the device
  36         and inode number returned by the <command>stat()</command> system call.
  37         As the file_id is a unique identifier of a file, it must be the same
  38         on all nodes in a cluster setup. This module overloads the
  39         <command>SMB_VFS_FILE_ID_CREATE()</command> operation and
  40         generates the device number based on the configured algorithm
  41         (see the "fileid:algorithm" option).
  42         </para>
  43
  44         <para>When using the fsname or fsid algorithm a
  45         <command>stat()</command> and <command>statfs()</command> call is
  46         required for all mounted file systems to generate the file_id. If e.g.
  47         an NFS file system is unresponsive such a call might block and the smbd
  48         process will become unresponsive. Use the "fileid:fstype deny",
  49         "fileid:fstype allow", "fileid:mntdir deny", or "fileid:mntdir allow"
  50         options to ignore potentially unresponsive file systems.
  51         </para>
  52 </refsect1>
  53
  54
  55 <refsect1>
  56         <title>OPTIONS</title>
  57
  58         <variablelist>
  59
  60                 <varlistentry>
  61                 <term>fileid:algorithm = ALGORITHM</term>
  62                 <listitem>
  63                 <para>Available algorithms are <command>fsname</command>,
  64                 <command>fsname_nodirs</command>, <command>fsid</command> and
  65                 <command>hostname</command>. The default value is
  66                 <command>fsname</command>.
  67                 </para>
  68                 <para>The <command>fsname</command> algorithm generates
  69                 device id by hashing the kernel device name.
  70                 </para>
  71                 <para>The <command>fsname_nodirs</command> algorithm generates
  72                 device id by hashing the kernel device name for files and by hashing
  73                 the hostname for directories. This can be used to deliberately
  74                 break lock coherency for directories in a cluster.
  75                 </para>
  76                 <para>The <command>fsid</command> algorithm generates
  77                 the device id from the <command>f_fsid</command> returned
  78                 from the <command>statfs()</command> syscall.
  79                 </para>
  80                 <para>The <command>hostname</command> algorithm generates device
  81                 id by hashing the hostname. This can be used to deliberately
  82                 break lock coherency in a cluster.
  83                 </para>
  84                 <para>The <command>fsname_norootdir</command> algorithm
  85                 generates device ids by hashing the kernel device name, except
  86                 for the root directory of shares where it will use the hostname
  87                 algorithm. This can be used to deliberately break lock coherency
  88                 in a cluster for the root directory of a share.
  89                 </para>
  90                 </listitem>
  91                 </varlistentry>
  92
  93                 <varlistentry>
  94                 <term>fileid:mapping = ALGORITHM</term>
  95                 <listitem>
  96                 <para>This option is the legacy version of the
  97                 <command>fileid:algorithm</command> option, which was used in earlier
  98                 versions of fileid mapping feature in custom Samba 3.0 versions.
  99                 </para>
 100                 </listitem>
 101                 </varlistentry>
 102
 103                 <varlistentry>
 104                 <term>fileid:fstype deny = LIST</term>
 105                 <listitem>
 106                 <para>List of file system types to be ignored for file_id
 107                 generation.
 108                 </para>
 109                 </listitem>
 110                 </varlistentry>
 111
 112                 <varlistentry>
 113                 <term>fileid:fstype allow = LIST</term>
 114                 <listitem>
 115                 <para>List of file system types to be allowed for file_id
 116                 generation. If this option is set, file system types not listed
 117                 here are ignored.
 118                 </para>
 119                 </listitem>
 120                 </varlistentry>
 121
 122                 <varlistentry>
 123                 <term>fileid:mntdir deny = LIST</term>
 124                 <listitem>
 125                 <para>List of file system mount points to be ignored for
 126                 file_id generation.
 127                 </para>
 128                 </listitem>
 129                 </varlistentry>
 130
 131                 <varlistentry>
 132                 <term>fileid:mntdir allow = LIST</term>
 133                 <listitem>
 134                 <para>List of file system mount points to be allowed for file_id
 135                 generation. If this option is set, file system mount points
 136                 not listed here are ignored.
 137                 </para>
 138                 </listitem>
 139                 </varlistentry>
 140
 141                 <varlistentry>
 142                 <term>fileid:nolockinode</term>
 143                 <listitem>
 144                 <para>This option triggers use of the fileid hostname algorithm
 145                 for the configured inode which can be used to deliberately break
 146                 lock coherency for the corresponding file or directory in a
 147                 cluster.
 148                 </para>
 149                 </listitem>
 150                 </varlistentry>
 151         </variablelist>
 152 </refsect1>
 153
 154 <refsect1>
 155         <title>EXAMPLES</title>
 156
 157         <para>Usage of the <command>fileid</command> module with the
 158         <command>fsid</command> algorithm:</para>
 159
 160 <programlisting>
 161         <smbconfsection name="[global]"/>
 162         <smbconfoption name="vfs objects">fileid</smbconfoption>
 163         <smbconfoption name="fileid:algorithm">fsid</smbconfoption>
 164 </programlisting>
 165
 166 </refsect1>
 167
 168 <refsect1>
 169         <title>VERSION</title>
 170
 171         <para>This man page is part of version &doc.version; of the Samba suite.
 172         </para>
 173 </refsect1>
 174
 175 <refsect1>
 176         <title>AUTHOR</title>
 177
 178         <para>The original Samba software and related utilities
 179         were created by Andrew Tridgell. Samba is now developed
 180         by the Samba Team as an Open Source project similar
 181         to the way the Linux kernel is developed.</para>
 182
 183 </refsect1>
 184
 185 </refentry>