docs/docbook/projdoc/VFS.xml

   1 <chapter id="VFS">
   2 <chapterinfo>
   3         &author.jelmer;
   4         &author.jht;
   5         <author><firstname>Tim</firstname><surname>Potter</surname></author>
   6         <author><firstname>Simo</firstname><surname>Sorce</surname><contrib>original vfs_skel README</contrib></author>
   7         <author><firstname>Alexander</firstname><surname>Bokovoy</surname><contrib>original vfs_netatalk docs</contrib></author>
   8         <author><firstname>Stefan</firstname><surname>Metzmacher</surname><contrib>Update for multiple modules</contrib></author>
   9 </chapterinfo>
  10 <title>Stackable VFS modules</title>
  11
  12 <sect1>
  13 <title>Features and Benefits</title>
  14
  15 <para>
  16 Since Samba-3, there is support for stackable VFS(Virtual File System) modules.
  17 Samba passes each request to access the unix file system thru the loaded VFS modules.
  18 This chapter covers all the modules that come with the samba source and references to
  19 some external modules.
  20 </para>
  21
  22
  23 </sect1>
  24
  25 <sect1>
  26 <title>Discussion</title>
  27
  28 <para>
  29 If not supplied with your platform distribution binary Samba package you may have problems
  30 to compile these modules, as shared libraries are compiled and linked in different ways
  31 on different systems.  They currently have been tested against GNU/Linux and IRIX.
  32 </para>
  33
  34 <para>
  35 To use the VFS modules, create a share similar to the one below.  The
  36 important parameter is the <smbconfoption><name>vfs objects</name></smbconfoption> parameter where
  37 you can list one or more VFS modules by name. For example, to log all access
  38 to files and put deleted files in a recycle bin:
  39
  40 <smbconfexample>
  41         <title>smb.conf with VFS modules</title>
  42         <smbconfsection>[audit]</smbconfsection>
  43 <smbconfoption><name>comment</name><value>Audited /data directory</value></smbconfoption>
  44 <smbconfoption><name>path</name><value>/data</value></smbconfoption>
  45 <smbconfoption><name>vfs objects</name><value>audit recycle</value></smbconfoption>
  46 <smbconfoption><name>writeable</name><value>yes</value></smbconfoption>
  47 <smbconfoption><name>browseable</name><value>yes</value></smbconfoption>
  48         </smbconfexample>
  49 </para>
  50
  51 <para>
  52 The modules are used in the order in which they are specified.
  53 </para>
  54
  55 <para>
  56 Samba will attempt to load modules from the <emphasis>lib</emphasis>
  57 directory in the root directory of the samba installation (usually
  58 <filename>/usr/lib/samba/vfs</filename> or <filename>/usr/local/samba/lib/vfs
  59 </filename>).
  60 </para>
  61
  62 <para>
  63 Some modules can be used twice for the same share.
  64 This can be done using a configuration similar to the one below.
  65
  66 <smbconfexample>
  67         <title>smb.conf with multiple VFS modules</title>
  68 <smbconfsection>[test]</smbconfsection>
  69 <smbconfoption><name>comment</name><value>VFS TEST</value></smbconfoption>
  70 <smbconfoption><name>path</name><value>/data</value></smbconfoption>
  71 <smbconfoption><name>writeable</name><value>yes</value></smbconfoption>
  72 <smbconfoption><name>browseable</name><value>yes</value></smbconfoption>
  73 <smbconfoption><name>vfs objects</name><value>example:example1 example example:test</value></smbconfoption>
  74 <smbconfoption><name>example1: parameter</name><value>1</value></smbconfoption>
  75 <smbconfoption><name>example:  parameter</name><value>5</value></smbconfoption>
  76 <smbconfoption><name>test:        parameter</name><value>7</value></smbconfoption>
  77 </smbconfexample>
  78 </para>
  79
  80 </sect1>
  81
  82 <sect1>
  83 <title>Included modules</title>
  84
  85         <sect2>
  86         <title>audit</title>
  87
  88                 <para>
  89                 A simple module to audit file access to the syslog
  90                 facility.  The following operations are logged:
  91                 <itemizedlist>
  92                 <listitem><para>share</para></listitem>
  93                 <listitem><para>connect/disconnect</para></listitem>
  94                 <listitem><para>directory opens/create/remove</para></listitem>
  95                 <listitem><para>file open/close/rename/unlink/chmod</para></listitem>
  96                 </itemizedlist>
  97                 </para>
  98
  99         </sect2>
 100
 101         <sect2>
 102         <title>extd_audit</title>
 103
 104                 <para>
 105                 This module is identical with the <emphasis>audit</emphasis> module above except
 106                 that it sends audit logs to both syslog as well as the smbd log file/s. The
 107                 loglevel for this module is set in the smb.conf file.
 108                 </para>
 109
 110                 <para>
 111                 The logging information that will be written to the smbd log file is controlled by
 112                 the <smbconfoption><name>log level</name></smbconfoption> parameter in &smb.conf;. The
 113                 following information will be recorded:
 114                 </para>
 115
 116                 <table frame="all"><title>Extended Auditing Log Information</title>
 117                 <tgroup cols="2" align="center">
 118                         <thead>
 119                         <row><entry align="center">Log Level</entry><entry>Log Details - File and Directory Operations</entry></row>
 120                         </thead>
 121                         <tbody>
 122                         <row><entry align="center">0</entry><entry align="left">Creation / Deletion</entry></row>
 123                         <row><entry align="center">1</entry><entry align="left">Create / Delete / Rename / Permission Changes</entry></row>
 124                         <row><entry align="center">2</entry><entry align="left">Create / Delete / Rename / Perm Change / Open / Close</entry></row>
 125                         </tbody>
 126                 </tgroup>
 127                 </table>
 128
 129         </sect2>
 130
 131         <sect2>
 132         <title>fake_perms</title>
 133
 134                 <para>
 135                 This module was created to allow Roaming Profile files and directories to be set (on the Samba server
 136                 under Unix) as read only. This module will if installed on the Profiles share will report to the client
 137                 that the Profile files and directories are writable. This satisfies the client even though the files
 138                 will never be overwritten as the client logs out or shuts down.
 139                 </para>
 140
 141         </sect2>
 142
 143         <sect2>
 144         <title>recycle</title>
 145
 146                 <para>
 147                 A recycle-bin like module. When used any unlink call
 148                 will be intercepted and files moved to the recycle
 149                 directory instead of being deleted. This gives the same
 150                 effect as the "Recycle Bin" on Windows computers.
 151                 </para>
 152
 153                 <para>Supported options:
 154                 <variablelist>
 155                         <varlistentry>
 156                         <term>recycle:repository</term>
 157                         <listitem><para>Relative path of the directory where deleted files should be moved to</para></listitem>
 158                         </varlistentry>
 159
 160                         <varlistentry>
 161                         <term>recycle:keeptree</term>
 162                         <listitem><para>Specifies whether the directory structure should
 163                                         be kept or if the files in the directory that is being
 164                                         deleted should be kept seperately in the recycle bin.
 165                         </para></listitem>
 166                         </varlistentry>
 167
 168                         <varlistentry>
 169                         <term>recycle:versions</term>
 170                         <listitem><para>If this option is set, two files
 171                                         with the same name that are deleted will both
 172                                         be kept in the recycle bin. Newer deleted versions
 173                                         of a file will be called "Copy #x of <replaceable>filename</replaceable>".</para></listitem>
 174                         </varlistentry>
 175
 176                         <varlistentry>
 177                         <term>recycle:touch</term>
 178                         <listitem><para>Specifies whether a file's access
 179                                         date should be touched when the file is moved to
 180                         the recycle bin.</para></listitem>
 181                         </varlistentry>
 182
 183                         <varlistentry>
 184                         <term>recycle:maxsize</term>
 185                         <listitem><para>Files that are larger than the number
 186                                         of bytes specified by this parameter will
 187                                         not be put into the recycle bin.</para></listitem>
 188                         </varlistentry>
 189
 190                         <varlistentry>
 191                         <term>recycle:exclude</term>
 192                         <listitem><para>List of files that should not
 193                                         be put into the recycle bin when deleted, but deleted
 194                                         in the regular way.</para></listitem>
 195                         </varlistentry>
 196
 197                         <varlistentry>
 198                         <term>recycle:exclude_dir</term>
 199                         <listitem><para>Contains a list of directories. When files from
 200                                         these directories are deleted, they are not put into the
 201                                         recycle bin, but deleted in the regular way.
 202                         </para></listitem>
 203                         </varlistentry>
 204
 205                         <varlistentry>
 206                         <term>recycle:noversions</term>
 207                         <listitem><para>Opposite of <parameter>recycle:versions</parameter>. If both options are specified, this one takes precedence.</para></listitem>
 208                         </varlistentry>
 209                 </variablelist>
 210                 </para>
 211
 212         </sect2>
 213
 214         <sect2>
 215         <title>netatalk</title>
 216
 217                 <para>
 218                 A netatalk module, that will ease co-existence of samba and
 219                 netatalk file sharing services.
 220                 </para>
 221
 222                 <para>Advantages compared to the old netatalk module:
 223                 <itemizedlist>
 224                 <listitem><para>it doesn't care about creating of .AppleDouble forks, just keeps them in sync</para></listitem>
 225                 <listitem><para>if a share in &smb.conf; doesn't contain .AppleDouble item in hide or veto list, it will be added automatically</para></listitem>
 226                 </itemizedlist>
 227                 </para>
 228
 229         </sect2>
 230
 231 </sect1>
 232
 233 <sect1>
 234 <title>VFS modules available elsewhere</title>
 235
 236 <para>
 237 This section contains a listing of various other VFS modules that
 238 have been posted but don't currently reside in the Samba CVS
 239 tree for one reason or another (e.g. it is easy for the maintainer
 240 to have his or her own CVS tree).
 241 </para>
 242
 243 <para>
 244 No statements about the stability or functionality of any module
 245 should be implied due to its presence here.
 246 </para>
 247
 248         <sect2>
 249         <title>DatabaseFS</title>
 250
 251                 <para>
 252                 URL: <ulink noescape="1" url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">http://www.css.tayloru.edu/~elorimer/databasefs/index.php</ulink>
 253                 </para>
 254
 255                 <para>By <ulink url="mailto:elorimer@css.tayloru.edu">Eric Lorimer</ulink>.</para>
 256
 257                 <para>
 258                 I have created a VFS module which implements a fairly complete read-only
 259                 filesystem.  It presents information from a database as a filesystem in
 260                 a modular and generic way to allow different databases to be used
 261                 (originally designed for organizing MP3s under directories such as
 262                 "Artists," "Song Keywords," etc... I have since applied it to a student
 263                 roster database very easily).  The directory structure is stored in the
 264                 database itself and the module makes no assumptions about the database
 265                 structure beyond the table it requires to run.
 266                 </para>
 267
 268                 <para>
 269                 Any feedback would be appreciated: comments, suggestions, patches,
 270                 etc...  If nothing else, hopefully it might prove useful for someone
 271                 else who wishes to create a virtual filesystem.
 272                 </para>
 273
 274         </sect2>
 275
 276         <sect2>
 277         <title>vscan</title>
 278
 279         <para>URL: <ulink noescape="1" url="http://www.openantivirus.org/">http://www.openantivirus.org/</ulink></para>
 280
 281                 <para>
 282                 samba-vscan is a proof-of-concept module for Samba, which
 283                 uses the VFS (virtual file system) features of Samba 2.2.x/3.0
 284                 alphaX. Of course, Samba has to be compiled with VFS support.
 285                 samba-vscan supports various virus scanners and is maintained
 286                 by Rainer Link.
 287                 </para>
 288
 289         </sect2>
 290 </sect1>
 291
 292 </chapter>