docs-xml/Samba3-HOWTO/TOSHARG-VFS.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="VFS">
   4 <chapterinfo>
   5         &author.jelmer;
   6         &author.jht;
   7         &author.tpot;
   8         <author><firstname>Simo</firstname><surname>Sorce</surname><contrib>original vfs_skel README</contrib></author>
   9         <author><firstname>Alexander</firstname><surname>Bokovoy</surname><contrib>original vfs_netatalk docs</contrib></author>
  10         <author><firstname>Stefan</firstname><surname>Metzmacher</surname><contrib>Update for multiple modules</contrib></author>
  11         <author><firstname>Ed</firstname><surname>Riddle</surname><contrib>original shadow_copy docs</contrib></author>
  12 </chapterinfo>
  13 <title>Stackable VFS modules</title>
  14
  15 <sect1>
  16 <title>Features and Benefits</title>
  17
  18 <para>
  19 <indexterm><primary>Virtual File System</primary><see>VFS</see></indexterm>
  20 <indexterm><primary>modules</primary></indexterm>
  21 <indexterm><primary>loaded modules</primary></indexterm>
  22 Stackable VFS (Virtual File System) modules support was new to Samba-3 and has proven quite popular. Samba
  23 passes each request to access the UNIX file system through the loaded VFS modules. This chapter covers the
  24 modules that come with the Samba source and provides references to some external modules.
  25 </para>
  26
  27
  28 </sect1>
  29
  30 <sect1>
  31 <title>Discussion</title>
  32
  33 <para>
  34 <indexterm><primary>IRIX</primary></indexterm>
  35 <indexterm><primary>GNU/Linux</primary></indexterm>
  36 If not supplied with your platform distribution binary Samba package, you may have problems compiling these
  37 modules, as shared libraries are compiled and linked in different ways on different systems.
  38 </para>
  39
  40 <para>
  41 <indexterm><primary>VFS modules</primary></indexterm>
  42 <indexterm><primary>modules</primary></indexterm>
  43 <indexterm><primary>recycle bin</primary></indexterm>
  44 To use the VFS modules, create a share similar to the one below. The important parameter is the <smbconfoption
  45 name="vfs objects"/> parameter where you can list one or more VFS modules by name. For example, to log all
  46 access to files and put deleted files in a recycle bin, see <link linkend="vfsrecyc">the smb.conf with VFS
  47 modules example</link>:
  48 </para>
  49
  50 <example id="vfsrecyc">
  51 <title>smb.conf with VFS modules</title>
  52 <smbconfblock>
  53 <smbconfsection name="[audit]"/>
  54 <smbconfoption name="comment">Audited /data directory</smbconfoption>
  55 <smbconfoption name="path">/data</smbconfoption>
  56 <smbconfoption name="vfs objects">audit recycle</smbconfoption>
  57 <smbconfoption name="writeable">yes</smbconfoption>
  58 <smbconfoption name="browseable">yes</smbconfoption>
  59 </smbconfblock>
  60 </example>
  61
  62 <para>
  63 <indexterm><primary>virus scanner</primary></indexterm>
  64 <indexterm><primary>scanner module</primary></indexterm>
  65 <indexterm><primary>recycle bin</primary></indexterm>
  66 The modules are used in the order in which they are specified.  Let's say that you want to both have a virus
  67 scanner module and a recycle bin module. It is wise to put the virus scanner module as the first one so that
  68 it is the first to get run and may detect a virus immediately, before any action is performed on that file.
  69 <smbconfoption name="vfs objects">vscan-clamav recycle</smbconfoption>
  70 </para>
  71
  72 <para>
  73 <indexterm><primary>/usr/local/samba/lib/vfs</primary></indexterm>
  74 <indexterm><primary>/usr/lib/samba/vfs</primary></indexterm>
  75 Samba will attempt to load modules from the <filename>/lib</filename> directory in the root directory of the
  76 Samba installation (usually <filename>/usr/lib/samba/vfs</filename> or
  77 <filename>/usr/local/samba/lib/vfs</filename>).
  78 </para>
  79
  80 <para>
  81 <indexterm><primary>modules</primary></indexterm>
  82 <indexterm><primary>VFS</primary></indexterm>
  83 <indexterm><primary>multiple modules</primary></indexterm>
  84 <indexterm><primary>multiple VFS</primary></indexterm>
  85 Some modules can be used twice for the same share.  This can be done using a configuration similar to the one
  86 shown in <link linkend="multimodule">the smb.conf with multiple VFS modules</link>.
  87
  88 <example id="multimodule">
  89 <title>smb.conf with multiple VFS modules</title>
  90 <smbconfblock>
  91 <smbconfsection name="[test]"/>
  92 <smbconfoption name="comment">VFS TEST</smbconfoption>
  93 <smbconfoption name="path">/data</smbconfoption>
  94 <smbconfoption name="writeable">yes</smbconfoption>
  95 <smbconfoption name="browseable">yes</smbconfoption>
  96 <smbconfoption name="vfs objects">example:example1 example example:test</smbconfoption>
  97 <smbconfoption name="example1: parameter">1</smbconfoption>
  98 <smbconfoption name="example:  parameter">5</smbconfoption>
  99 <smbconfoption name="test:     parameter">7</smbconfoption>
 100 </smbconfblock>
 101 </example>
 102 </para>
 103
 104 </sect1>
 105
 106 <sect1>
 107 <title>Included Modules</title>
 108
 109         <sect2>
 110         <title>audit</title>
 111
 112                 <para>
 113 <indexterm><primary>audit file access</primary></indexterm>
 114                 A simple module to audit file access to the syslog facility. The following operations are logged:
 115                 <itemizedlist>
 116                         <listitem><para>share</para></listitem>
 117                         <listitem><para>connect/disconnect</para></listitem>
 118                         <listitem><para>directory opens/create/remove</para></listitem>
 119                         <listitem><para>file open/close/rename/unlink/chmod</para></listitem>
 120                 </itemizedlist>
 121                 </para>
 122
 123         </sect2>
 124
 125         <sect2>
 126         <title>default_quota</title>
 127
 128         <para>
 129         This module allows the default quota values, in the windows explorer GUI, to be stored on a Samba server.
 130         The challenge is that linux filesystems only store quotas for users and groups, but no default quotas.
 131         </para>
 132
 133         <para>
 134         Samba returns NO_LIMIT as the default quotas by default and refuses to update them. With this module you
 135         can store the default quotas that are reported to a windows client, in the quota record of a user. By
 136         default the root user is taken because quota limits for root are typically not enforced.
 137         </para>
 138
 139         <para>
 140         This module takes 2 parametric entries in the &smb.conf; file.  The default prefix for each is the
 141         <quote>default_quota</quote>. This can be overwrittem when you load the module in the <emphasis>vfs
 142         modules</emphasis> parameter like this:
 143 <screen>
 144 vfs objects = default_quota:myprefix
 145 </screen>
 146         </para>
 147
 148         <para>
 149         The parametric entries that may be specified for the default_quotas module are:
 150         </para>
 151
 152         <variablelist>
 153                 <varlistentry>
 154             <term>myprefix:uid</term>
 155                         <listitem><para>
 156                         This parameter takes a integer argument that specifies the uid of the quota record that will be
 157                         used for storing the default user quotas.
 158                         </para>
 159
 160                         <para>
 161                         The default value is 0 (for root user). An example of use is:
 162 <screen>
 163 vfs objects = default_quota
 164 default_quota:  uid = 65534
 165 </screen>
 166                         The above demonstrates the case where the <constant>myprefix</constant> was omitted, thus the
 167                         default prefix is the name of the module. When a <constant>myprefix</constant> parameter is
 168                         specified the above can be re-written like this:
 169 <screen>
 170 vfs objects = default_quota:myprefix
 171 myprefix:       uid = 65534
 172 </screen>
 173                         </para></listitem>
 174                 </varlistentry>
 175
 176                 <varlistentry>
 177             <term>myprefix:uid nolimit</term>
 178                         <listitem><para>
 179                         This parameter takes a boolean argument that specifies if the stored default quota values also be
 180                         reported for the user record, or if the value <constant>NO_LIMIT</constant> should be reported to
 181                         the windows client for the user specified by the <parameter>prefix:uid</parameter> parameter.
 182                         </para>
 183
 184                         <para>
 185                         The default value is <constant>yes</constant> (which means to report NO_LIMIT). An example of use
 186                         is shown here:
 187 <screen>
 188 vfs objects = default_quota:myprefix
 189 myprefix:       uid nolimit = no
 190 </screen>
 191                         </para></listitem>
 192                 </varlistentry>
 193
 194                 <varlistentry>
 195                         <term>myprefix:gid</term>
 196                         <listitem><para>
 197                         This parameter takes an integer argument, it's just like the <parameter>prefix>:uid</parameter> but
 198                         for group quotas.  NOTE: group quotas are not supported from the windows explorer.
 199                         </para>
 200
 201                         <para>
 202                         The default value is 0 (for root group). An example of use is shown here:
 203 <screen>
 204 vfs objects = default_quota
 205 default_quota:  gid = 65534
 206 </screen>
 207                         </para></listitem>
 208                 </varlistentry>
 209
 210                 <varlistentry>
 211                         <term>myprefix:gid nolimit</term>
 212                         <listitem><para>
 213                         This parameter takes a boolean argument, just like the <parameter>prefix>:uid nolimit</parameter>
 214                         but for group quotas.  NOTE: group quotas are not supported from the windows explorer.
 215                         </para>
 216
 217                         <para>
 218                         The default value is <constant>yes</constant> (which means to report NO_LIMIT). An example of use
 219                         is shown here:
 220 <screen>
 221 vfs objects = default_quota
 222 default_quota:  uid nolimit = no
 223 </screen>
 224                         </para></listitem>
 225                 </varlistentry>
 226         </variablelist>
 227
 228         <para>
 229         An example of use of multiple parametric specifications is shown here:
 230 <screen>
 231 ...
 232 vfs objects = default_quota:quotasettings
 233 quotasettings:  uid nolimit = no
 234 quotasettings:  gid = 65534
 235 quotasettings:  gid nolimit = no
 236 ...
 237 </screen>
 238         </para>
 239
 240         </sect2>
 241
 242         <sect2>
 243         <title>extd_audit</title>
 244
 245                 <para>
 246 <indexterm><primary>audit module</primary></indexterm>
 247 <indexterm><primary>extd_audit module</primary></indexterm>
 248 <indexterm><primary>smbd</primary></indexterm>
 249                 This module is identical with the <command>audit</command> module above except
 250                 that it sends audit logs to both syslog as well as the <command>smbd</command> log files. The
 251                 <smbconfoption name="log level"/> for this module is set in the &smb.conf; file.
 252                 </para>
 253
 254                 <para>
 255                 Valid settings and the information that will be recorded are shown in <link linkend="xtdaudit">the next table</link>.
 256                 </para>
 257
 258                 <table frame="all" id="xtdaudit">
 259                         <title>Extended Auditing Log Information</title>
 260                 <tgroup cols="2" align="center">
 261                         <thead>
 262                         <row><entry align="center">Log Level</entry><entry>Log Details - File and Directory Operations</entry></row>
 263                         </thead>
 264                         <tbody>
 265                         <row><entry align="center">0</entry><entry align="left">Make Directory, Remove Directory, Unlink</entry></row>
 266                         <row><entry align="center">1</entry><entry align="left">Open Directory, Rename File, Change Permissions/ACLs</entry></row>
 267                         <row><entry align="center">2</entry><entry align="left">Open &amp; Close File</entry></row>
 268                         <row><entry align="center">10</entry><entry align="left">Maximum Debug Level</entry></row>
 269                         </tbody>
 270                 </tgroup>
 271                 </table>
 272
 273                 <sect3>
 274                 <title>Configuration of Auditing</title>
 275
 276                 <para>
 277 <indexterm><primary>logging</primary></indexterm>
 278                 This auditing tool is more flexible than most people will readily recognize. There are a number of ways
 279                 by which useful logging information can be recorded.
 280                 </para>
 281
 282                 <itemizedlist>
 283                         <listitem><para>Syslog can be used to record all transaction. This can be disabled by setting
 284                                         in the &smb.conf; file <parameter>syslog = 0</parameter>.</para></listitem>
 285                         <listitem><para>Logging can take place to the default log file (<filename>log.smbd</filename>)
 286                                         for all loaded VFS modules just by setting in the &smb.conf; file
 287                                         <parameter>log level = 0 vfs:x</parameter>, where x is the log level.
 288                                         This will disable general logging while activating all logging of VFS
 289                                         module activity at the log level specified.</para></listitem>
 290                         <listitem><para>Detailed logging can be obtained per user, per client machine, etc.
 291                                         This requires the above together with the creative use of the
 292                                         <parameter>log file</parameter> settings.</para>
 293                                         <para>An example of detailed per-user and per-machine logging can
 294                                         be obtained by setting
 295                                         <smbconfoption name="log file">/var/log/samba/%U.%m.log</smbconfoption>.
 296                                         </para></listitem>
 297                 </itemizedlist>
 298
 299                 <para>
 300                 Auditing information often must be preserved for a long time. So that the log files do not get rotated
 301                 it is essential that the <smbconfoption name="max log size">0</smbconfoption> be set
 302                 in the &smb.conf; file.
 303                 </para>
 304
 305                 </sect3>
 306
 307         </sect2>
 308
 309         <sect2 id="fakeperms">
 310         <title>fake_perms</title>
 311
 312                 <para>
 313 <indexterm><primary>fake_perms</primary></indexterm>
 314 <indexterm><primary>Roaming Profile</primary></indexterm>
 315 <indexterm><primary>writeable</primary></indexterm>
 316 <indexterm><primary>read only</primary></indexterm>
 317                 This module was created to allow Roaming Profile files and directories to be set (on the Samba server
 318                 under UNIX) as read only. This module will, if installed on the Profiles share, report to the client
 319                 that the Profile files and directories are writeable. This satisfies the client even though the files
 320                 will never be overwritten as the client logs out or shuts down.
 321                 </para>
 322
 323         </sect2>
 324
 325         <sect2>
 326         <title>recycle</title>
 327
 328                 <para>
 329 <indexterm><primary>recycle</primary></indexterm>
 330 <indexterm><primary>unlink calls</primary></indexterm>
 331 <indexterm><primary>recycle directory</primary></indexterm>
 332                 A Recycle Bin-like module. Where used, unlink calls will be intercepted and files moved
 333                 to the recycle directory instead of being deleted. This gives the same effect as the
 334                 <guiicon>Recycle Bin</guiicon> on Windows computers.
 335                 </para>
 336
 337                 <para>
 338 <indexterm><primary>recycle</primary></indexterm>
 339 <indexterm><primary>.recycle</primary></indexterm>
 340 <indexterm><primary>recycle:keeptree</primary></indexterm>
 341 <indexterm><primary>deleted files</primary></indexterm>
 342                 The <guiicon>Recycle Bin</guiicon> will not appear in
 343                 <application>Windows Explorer</application> views of the network
 344                 file system (share) nor on any mapped drive. Instead, a directory
 345                 called <filename>.recycle</filename> will be automatically created
 346                 when the first file is deleted and <parameter>recycle:repository</parameter>
 347                 is not configured.
 348                 If <parameter>recycle:repository</parameter> is configured, the name
 349                 of the created directory depends on <parameter>recycle:repository</parameter>.
 350                 Users can recover files from the recycle bin. If the
 351                 <parameter>recycle:keeptree</parameter> has been specified,     deleted
 352                 files will be found in a path identical with that from which the
 353                 file was deleted.
 354                 </para>
 355
 356                 <para>Supported options for the <command>recycle</command> module are as follow:
 357                 <variablelist>
 358                         <varlistentry>
 359                         <term>recycle:repository</term>
 360                                 <listitem><para>
 361 <indexterm><primary>recycle:repository</primary></indexterm>
 362                                 Path of the directory where deleted files should be moved.
 363                                 </para></listitem>
 364                         </varlistentry>
 365
 366                         <varlistentry>
 367                         <term>recycle:directory_mode</term>
 368                                 <listitem><para>
 369 <indexterm><primary>directory_mode</primary></indexterm>
 370                                 Set it to the octal mode you want for the recycle directory. With
 371                                 this mode the recycle directory will be created if it not
 372                                 exists and the first file is deleted.
 373                                 If <parameter>recycle:subdir_mode</parameter> is not set, these
 374                                 mode also apply to sub directories.
 375                                 If <parameter>directory_mode</parameter> not exists, the default
 376                                 mode 0700 is used.
 377                                 </para></listitem>
 378                         </varlistentry>
 379
 380                         <varlistentry>
 381                         <term>recycle:subdir_mode</term>
 382                                 <listitem><para>
 383 <indexterm><primary>recycle:subdir_mode</primary></indexterm>
 384                                 Set it to the octal mode you want for the sub directories of
 385                                 the recycle directory. With this mode   the sub directories will
 386                                 be created.
 387                                 If <parameter>recycle:subdir_mode</parameter> is not set, the
 388                                 sub directories will be created with the mode from
 389                                 <parameter>directory_mode</parameter>.
 390                                 </para></listitem>
 391                         </varlistentry>
 392
 393                         <varlistentry>
 394                         <term>recycle:keeptree</term>
 395                                 <listitem><para>
 396 <indexterm><primary>recycle:keeptree</primary></indexterm>
 397                                 Specifies whether the directory structure should be kept or if the files in the directory that is being
 398                                 deleted should be kept separately in the recycle bin.
 399                                 </para></listitem>
 400                         </varlistentry>
 401
 402                         <varlistentry>
 403                         <term>recycle:versions</term>
 404                                 <listitem><para>
 405 <indexterm><primary>recycle:versions</primary></indexterm>
 406                                 If this option is set, two files
 407                                 with the same name that are deleted will both
 408                                 be kept in the recycle bin. Newer deleted versions
 409                                 of a file will be called <quote>Copy #x of <replaceable>filename</replaceable></quote>.
 410                                 </para></listitem>
 411                         </varlistentry>
 412
 413                         <varlistentry>
 414                         <term>recycle:touch</term>
 415                                 <listitem><para>
 416 <indexterm><primary>recycle:touch</primary></indexterm>
 417                                 Specifies whether a file's access date should be touched when the file is moved to the recycle bin.
 418                                 </para></listitem>
 419                         </varlistentry>
 420
 421                         <varlistentry>
 422                         <term>recycle:touch_mtime</term>
 423                                 <listitem><para>
 424 <indexterm><primary>recycle:touch</primary></indexterm>
 425                                 Specifies whether a file's last modify date date should be touched when the file is moved to the recycle bin.
 426                                 </para></listitem>
 427                         </varlistentry>
 428
 429                         <varlistentry>
 430                         <term>recycle:maxsize</term>
 431                                 <listitem><para>
 432 <indexterm><primary>recycle:maxsize</primary></indexterm>
 433                                 Files that are larger than the number of bytes specified by this parameter will not be put into the recycle bin.
 434                                 </para></listitem>
 435                         </varlistentry>
 436
 437                         <varlistentry>
 438                         <term>recycle:exclude</term>
 439                                 <listitem><para>
 440 <indexterm><primary>recycle:exclude</primary></indexterm>
 441                                 List of files that should not be put into the recycle bin when deleted, but deleted in the regular way.
 442                                 </para></listitem>
 443                         </varlistentry>
 444
 445                         <varlistentry>
 446                         <term>recycle:exclude_dir</term>
 447                                 <listitem><para>
 448 <indexterm><primary>recycle:exclude_dir</primary></indexterm>
 449                                 Contains a list of directories. When files from these directories are
 450                                 deleted, they are not put into the
 451                                 recycle bin but are deleted in the
 452                                 regular way.
 453                                 </para></listitem>
 454                         </varlistentry>
 455
 456                         <varlistentry>
 457                         <term>recycle:noversions</term>
 458                                 <listitem><para>
 459 <indexterm><primary>recycle:noversions</primary></indexterm>
 460                                 Specifies a list of paths (wildcards such as * and ? are supported) for which no versioning
 461                                 should be used. Only useful when <emphasis>recycle:versions</emphasis> is enabled.
 462                                 </para></listitem>
 463                         </varlistentry>
 464                 </variablelist>
 465                 </para>
 466
 467         </sect2>
 468
 469         <sect2>
 470         <title>netatalk</title>
 471
 472                 <para>
 473 <indexterm><primary>netatalk</primary></indexterm>
 474                 A netatalk module will ease co-existence of Samba and netatalk file sharing services.
 475                 </para>
 476
 477                 <para>Advantages compared to the old netatalk module:
 478                 <itemizedlist>
 479 <indexterm><primary>.AppleDouble</primary></indexterm>
 480                         <listitem><para>Does not care about creating .AppleDouble forks, just keeps them in sync.</para></listitem>
 481                         <listitem><para>If a share in &smb.conf; does not contain .AppleDouble item in hide or veto list, it will be added automatically.</para></listitem>
 482                 </itemizedlist>
 483                 </para>
 484
 485         </sect2>
 486
 487     <sect2>
 488       <title>shadow_copy</title>
 489
 490         <warning><para>
 491 <indexterm><primary>shadow_copy</primary></indexterm>
 492         <emphasis>THIS IS NOT A BACKUP, ARCHIVAL, OR VERSION CONTROL SOLUTION!</emphasis>
 493         </para>
 494
 495         <para>
 496 <indexterm><primary>version control</primary></indexterm>
 497         With Samba or Windows servers, shadow_copy is designed to be an end-user tool only.  It does not replace or
 498         enhance your backup and archival solutions and should in no way be considered as such.  Additionally, if you
 499         need version control, implement a version control system.  You have been warned.
 500         </para></warning>
 501
 502
 503         <para>
 504         The shadow_copy module allows you to setup functionality that is similar to MS shadow copy services.  When
 505         setup properly, this module allows Microsoft shadow copy clients to browse "shadow copies" on Samba shares.
 506         You will need to install the shadow copy client.  You can get the MS shadow copy client <ulink noescape="1"
 507         url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">here.</ulink>.  Note the
 508         additional requirements for pre-Windows XP clients.  I did not test this functionality with any pre-Windows XP
 509         clients.  You should be able to get more information about MS Shadow Copy <ulink noescape="1"
 510         url="http://www.microsoft.com/windowsserver2003/techinfo/overview/scr.mspx">from the Microsoft's site</ulink>.
 511         </para>
 512
 513         <para>
 514 <indexterm><primary>shadow_copy</primary></indexterm>
 515 <indexterm><primary>VFS module</primary></indexterm>
 516 <indexterm><primary>shadow_copy module</primary></indexterm>
 517 <indexterm><primary>LVM</primary></indexterm>
 518 <indexterm><primary>EVMS</primary></indexterm>
 519 <indexterm><primary>Logical Volume Manager</primary><see>LVM</see></indexterm>
 520         The shadow_copy VFS module requires some underlying file system setup with some sort of Logical Volume Manager
 521         (LVM) such as LVM1, LVM2, or EVMS.  Setting up LVM is beyond the scope of this document; however, we will
 522         outline the steps we took to test this functionality for <emphasis>example purposes only.</emphasis> You need
 523         to make sure the LVM implementation you choose to deploy is ready for production.  Make sure you do plenty of
 524         tests.
 525         </para>
 526
 527         <para>
 528         Here are some common resources for LVM and EVMS:
 529         </para>
 530
 531         <itemizedlist>
 532           <listitem>
 533             <para><ulink noescape="1"
 534             url="http://www.sistina.com/products_lvm_download.htm">Sistina's
 535             LVM1 and LVM2</ulink></para>
 536           </listitem>
 537           <listitem>
 538             <para><ulink url="http://evms.sourceforge.net/">Enterprise Volume Management System (EVMS)</ulink></para>
 539           </listitem>
 540           <listitem>
 541             <para><ulink url="http://tldp.org/HOWTO/LVM-HOWTO/">The LVM HOWTO</ulink></para>
 542           </listitem>
 543           <listitem>
 544             <para>
 545               See <ulink url="http://www-106.ibm.com/developerworks/linux/library/l-lvm/">Learning
 546               Linux LVM, Part 1</ulink> and <ulink url="http://www-106.ibm.com/developerworks/library/l-lvm2.html">Learning
 547               Linux LWM, Part 2</ulink> for Daniel Robbins' well-written, two part tutorial on Linux and LVM using LVM
 548               source code and reiserfs.</para>
 549           </listitem>
 550         </itemizedlist>
 551
 552         <sect3>
 553         <title>Shadow Copy Setup</title>
 554         <para>
 555 <indexterm><primary>XFS file system</primary></indexterm>
 556 <indexterm><primary>Debian Sarge</primary></indexterm>
 557         At the time of this writing, not much testing has been done.  I tested the shadow copy VFS module with a
 558         specific scenario which was not deployed in a production environment, but more as a proof of concept.  The
 559         scenario involved a Samba file server on Debian Sarge with an XFS file system and LVM1.  I do NOT recommend
 560         you use this as a solution without doing your own due diligence with regard to all the components presented
 561         here.  That said, following is an basic outline of how I got things going.
 562         </para>
 563
 564         <orderedlist>
 565           <listitem>
 566             <formalpara><title>Installed Operating System </title>
 567             <para>
 568                 In my tests, I used <ulink url="http://www.debian.org/devel/debian-installer/">Debian
 569                 Sarge</ulink> (i.e., testing) on an XFS file system.  Setting up the OS is a bit beyond the scope of this
 570                 document.  It is assumed that you have a working OS capable of running Samba.
 571                 </para></formalpara>
 572           </listitem>
 573
 574           <listitem>
 575             <formalpara><title>Install &amp; Configure Samba</title>
 576                 <para>
 577                 See the <link linkend="introduction">installation section</link> of this HOWTO for more detail on this.
 578                 It doesn't matter if it is a Domain Controller or Member File Server, but it is assumed that you have a
 579                 working Samba 3.0.3 or later server running.
 580                 </para></formalpara>
 581           </listitem>
 582
 583           <listitem>
 584             <formalpara><title>Install &amp; Configure LVM</title>
 585                 <para>
 586 <indexterm><primary>shadow copies</primary></indexterm>
 587 <indexterm><primary>Snapshots</primary></indexterm>
 588                 Before you can make shadow copies available to the client, you have to create the shadow copies.  This is
 589                 done by taking some sort of file system snapshot.  Snapshots are a typical feature of Logical Volume
 590                 Managers such as LVM, so we first need to have that setup.
 591                 </para></formalpara>
 592
 593             <itemizedlist>
 594                 <para>
 595                 The following is provided as an example and will be most helpful for Debian users.  Again, this was tested
 596                 using the "testing" or "Sarge" distribution.
 597                 </para>
 598
 599                         <listitem>
 600                         <para>
 601 <indexterm><primary>lvm10 package</primary></indexterm>
 602 <indexterm><primary>devfsd package</primary></indexterm>
 603 <indexterm><primary>Debian</primary></indexterm>
 604 <indexterm><primary>xfsprogs</primary></indexterm>
 605 <indexterm><primary>apt-get</primary></indexterm>
 606                         Install lvm10 and devfsd packages if you have not done so already.  On Debian systems, you are warned of the
 607                         interaction of devfs and lvm1 which requires the use of devfs filenames.  Running <command>apt-get update
 608                         &amp;&amp; apt-get install lvm10 devfsd xfsprogs</command> should do the trick for this example.
 609                         </para></listitem>
 610
 611                         <listitem><para>
 612 <indexterm><primary>create volume</primary></indexterm>
 613 <indexterm><primary>create partition</primary></indexterm>
 614 <indexterm><primary>fdisk</primary></indexterm>
 615 <indexterm><primary>cfdisk</primary></indexterm>
 616 <indexterm><primary>Linux LVM</primary></indexterm>
 617                         Now you need to create a volume.  You will need to create a partition (or partitions) to add to your volume.
 618                         Use your favorite partitioning tool (e.g., Linux fdisk, cfdisk, etc.).  The partition type should be set to
 619                         0x8e for "Linux LVM."  In this example, we will use /dev/hdb1.
 620                         </para>
 621
 622                         <para>
 623 <indexterm><primary>Linux LVM partition</primary></indexterm>
 624 <indexterm><primary>LVM volume</primary></indexterm>
 625 <indexterm><primary>modprobe</primary></indexterm>
 626                         Once you have the Linux LVM partition (type 0x8e), you can run a series of commands to create the LVM volume.
 627                         You can use several disks and/or partitions, but we will use only one in this example.  You may also need to
 628                         load the kernel module with something like <command>modprobe lvm-mod</command> and set your system up to load
 629                         it on reboot by adding it to (<filename>/etc/modules</filename>).
 630                         </para></listitem>
 631
 632                         <listitem><para>
 633 <indexterm><primary>pvcreate</primary></indexterm>
 634                         Create the physical volume with <command>pvcreate /dev/hdb1</command>
 635                         </para></listitem>
 636
 637                         <listitem><para>
 638 <indexterm><primary>vgcreate</primary></indexterm>
 639 <indexterm><primary>volume group</primary></indexterm>
 640                         Create the volume group and add /dev/hda1 to it with <command>vgcreate shadowvol /dev/hdb1</command>
 641                         </para>
 642
 643                         <para>
 644 <indexterm><primary>vgdisplay</primary></indexterm>
 645                         You can use <command>vgdisplay</command> to review information about the volume group.
 646                         </para></listitem>
 647
 648                         <listitem><para>
 649 <indexterm><primary>lvcreate</primary></indexterm>
 650                         Now you can create the logical volume with something like <command>lvcreate -L400M -nsh_test shadowvol</command>
 651                         </para>
 652
 653                         <para>
 654 <indexterm><primary>/dev/shadowvol</primary></indexterm>
 655                         This creates the logical volume of 400 MBs named "sh_test" in the volume group we created called shadowvol.
 656                         If everything is working so far, you should see them in <filename>/dev/shadowvol</filename>.
 657                         </para></listitem>
 658
 659                         <listitem><para>
 660 <indexterm><primary>mkfs.xfs</primary></indexterm>
 661                         Now we should be ready to format the logical volume we named sh_test with <command>mkfs.xfs
 662                         /dev/shadowvol/sh_test</command>
 663                         </para>
 664
 665                         <para>
 666 <indexterm><primary>logical volume</primary></indexterm>
 667 <indexterm><primary>LVM</primary></indexterm>
 668 <indexterm><primary>freezing</primary></indexterm>
 669 <indexterm><primary>resizing</primary></indexterm>
 670 <indexterm><primary>growing</primary></indexterm>
 671                         You can format the logical volume with any file system you choose, but make sure to use one that allows you to
 672                         take advantage of the additional features of LVM such as freezing, resizing, and growing your file systems.
 673                         </para>
 674
 675                         <para>
 676 <indexterm><primary>LVM volume</primary></indexterm>
 677 <indexterm><primary>shadow_copy</primary></indexterm>
 678 <indexterm><primary>module</primary></indexterm>
 679                         Now we have an LVM volume where we can play with the shadow_copy VFS module.
 680                         </para></listitem>
 681
 682                         <listitem><para>
 683 <indexterm><primary>mkdir</primary></indexterm>
 684 <indexterm><primary>permissions</primary></indexterm>
 685 <indexterm><primary>chmod</primary></indexterm>
 686                         Now we need to prepare the directory with something like
 687 <screen>
 688 &rootprompt; mkdir -p /data/shadow_share
 689 </screen>
 690                         or whatever you want to name your shadow copy-enabled Samba share.  Make sure you set the permissions so that
 691                         you can use it.  If in doubt, use <command>chmod 777 /data/shadow_share</command> and tighten the permissions
 692                         once you get things working.
 693                         </para></listitem>
 694
 695                         <listitem><para>
 696 <indexterm><primary>mount</primary></indexterm>
 697                         Mount the LVM volume using something like <command>mount /dev/shadowvol/sh_test /data/shadow_share</command>
 698                         </para>
 699
 700                         <para>
 701 <indexterm><primary>/etc/fstab</primary></indexterm>
 702                         You may also want to edit your <filename>/etc/fstab</filename> so that this partition mounts during the system boot.
 703                         </para></listitem>
 704                 </itemizedlist>
 705
 706                 </listitem>
 707
 708           <listitem>
 709             <formalpara><title>Install &amp; Configure the shadow_copy VFS Module</title>
 710                 <para>
 711                 Finally we get to the actual shadow_copy VFS module.  The shadow_copy VFS module should be available in Samba
 712                 3.0.3 and higher.  The smb.conf configuration is pretty standard.  Here is our example of a share configured
 713                 with the shadow_copy VFS module:
 714                 </para></formalpara>
 715
 716                 <example id="vfsshadow">
 717                 <title>Share With shadow_copy VFS</title>
 718                 <smbconfblock>
 719                 <smbconfsection name="[shadow_share]"/>
 720                 <smbconfoption name="comment">Shadow Copy Enabled Share</smbconfoption>
 721                 <smbconfoption name="path">/data/shadow_share</smbconfoption>
 722                 <smbconfoption name="vfs objects">shadow_copy</smbconfoption>
 723                 <smbconfoption name="writeable">yes</smbconfoption>
 724                 <smbconfoption name="browseable">yes</smbconfoption>
 725                 </smbconfblock>
 726                 </example>
 727
 728                 </listitem>
 729
 730                 <listitem>
 731             <formalpara><title>Create Snapshots and Make Them Available to shadow_copy.so</title>
 732                 <para>
 733 <indexterm><primary>shadow_copy</primary></indexterm>
 734 <indexterm><primary>LVM snapshots</primary></indexterm>
 735 <indexterm><primary>module</primary></indexterm>
 736                 Before you can browse the shadow copies, you must create them and mount them.  This will most likely be done
 737                 with a script that runs as a cron job.  With this particular solution, the shadow_copy VFS module is used to
 738                 browse LVM snapshots.  Those snapshots are not created by the module.  They are not made available by the
 739                 module either.  This module allows the shadow copy-enabled client to browse the snapshots you take and make
 740                 available.
 741                 </para></formalpara>
 742
 743             <para>
 744                 Here is a simple script used to create and mount the snapshots:
 745 <screen>
 746 #!/bin/bash
 747 # This is a test, this is only a test
 748 SNAPNAME=`date +%Y.%m.%d-%H.%M.%S`
 749 xfs_freeze -f /data/shadow_share/
 750 lvcreate -L10M -s -n $SNAPNAME /dev/shadowvol/sh_test
 751 xfs_freeze -u /data/shadow_share/
 752 mkdir /data/shadow_share/@GMT-$SNAPNAME
 753 mount /dev/shadowvol/$SNAPNAME \
 754        /data/shadow_share/@GMT-$SNAPNAME -onouuid,ro
 755 </screen>
 756                 Note that the script does not handle other things like remounting snapshots on reboot.
 757             </para></listitem>
 758
 759                 <listitem>
 760             <formalpara><title>Test From Client</title>
 761                 <para>
 762                 To test, you will need to install the shadow copy client which you can obtain from the <ulink
 763                 url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">Microsoft web site.</ulink> I
 764                 only tested this with an XP client so your results may vary with other pre-XP clients.  Once installed, with
 765                 your XP client you can right-click on specific files or in the empty space of the shadow_share and view the
 766                 "properties."  If anything has changed, then you will see it on the "Previous Versions" tab of the properties
 767                 window.
 768                 </para></formalpara>
 769           </listitem>
 770         </orderedlist>
 771
 772         </sect3>
 773 </sect2>
 774
 775 </sect1>
 776
 777 <sect1>
 778 <title>VFS Modules Available Elsewhere</title>
 779
 780 <para>
 781 <indexterm><primary>VFS modules</primary></indexterm>
 782 This section contains a listing of various other VFS modules that have been posted but do not currently reside
 783 in the Samba CVS tree for one reason or another (e.g., it is easy for the maintainer to have his or her own
 784 CVS tree).
 785 </para>
 786
 787 <para>
 788 No statements about the stability or functionality of any module should be implied due to its presence here.
 789 </para>
 790
 791 <sect2>
 792 <title>DatabaseFS</title>
 793
 794 <para>
 795 <indexterm><primary>DatabaseFS</primary></indexterm>
 796 URL: <ulink noescape="1" url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">
 797 Taylors University DatabaeFS</ulink>
 798 </para>
 799
 800 <para>By <ulink url="mailto:elorimer@css.tayloru.edu">Eric Lorimer.</ulink></para>
 801
 802 <para>
 803 I have created a VFS module that implements a fairly complete read-only filesystem. It presents information
 804 from a database as a filesystem in a modular and generic way to allow different databases to be used.
 805 (Originally designed for organizing MP3s under directories such as <quote>Artists,</quote> <quote>Song
 806 Keywords,</quote> and so on. I have since easily applied it to a student roster database.) The directory
 807 structure is stored in the database itself and the module makes no assumptions about the database structure
 808 beyond the table it requires to run.
 809 </para>
 810
 811 <para>
 812 Any feedback would be appreciated: comments, suggestions, patches, and so on. If nothing else, it
 813 might prove useful for someone else who wishes to create a virtual filesystem.
 814 </para>
 815
 816 </sect2>
 817
 818 <sect2>
 819 <title>vscan</title>
 820
 821 <indexterm><primary>vscan</primary></indexterm>
 822 <para>URL: <ulink noescape="1" url="http://www.openantivirus.org/projects.php#samba-vscan">
 823 Open Anti-Virus vscan</ulink>
 824 </para>
 825
 826 <para>
 827 <indexterm><primary>samba-vscan</primary></indexterm>
 828 samba-vscan is a proof-of-concept module for Samba, which provides on-access anti-virus support for files
 829 shared using Samba.  samba-vscan supports various virus scanners and is maintained by Rainer Link.
 830 </para>
 831
 832 </sect2>
 833
 834 <sect2>
 835 <title>vscan-clamav</title>
 836 <para>
 837 Samba users have been using the RPMS from SerNet without a problem.
 838 OpenSUSE Linux users have also used the vscan scanner for quite some time
 839 with excellent results. It does impact overall write performance though.
 840 </para>
 841
 842 <para>
 843 The following share stanza is a good guide for those wanting to configure vscan-clamav:
 844 </para>
 845
 846 <screen>
 847 [share]
 848 vfs objects = vscan-clamav
 849 vscan-clamav: config-file = /etc/samba/vscan-clamav.conf
 850 </screen>
 851
 852 <para>
 853 The following example of the <filename>vscan-clamav.conf</filename> file may help to get this
 854 fully operational:
 855 </para>
 856
 857 <screen>
 858 <title>VFS: Vscan ClamAV Control File</title>
 859 #
 860 # /etc/samba/vscan-clamav.conf
 861 #
 862
 863 [samba-vscan]
 864 ; run-time configuration for vscan-samba using
 865 ; clamd
 866 ; all options are set to default values
 867
 868 ; do not scan files larger than X bytes. If set to 0 (default),
 869 ; this feature is disable (i.e. all files are scanned)
 870 max file size = 10485760
 871
 872 ; log all file access (yes/no). If set to yes, every access will
 873 ; be logged. If set to no (default), only access to infected files
 874 ; will be logged
 875 verbose file logging = no
 876
 877 ; if set to yes (default), a file will be scanned while opening
 878 scan on open = yes
 879 ; if set to yes, a file will be scanned while closing (default is yes)
 880 scan on close = yes
 881
 882 ; if communication to clamd fails, should access to file denied?
 883 ; (default: yes)
 884 deny access on error = no
 885
 886 ; if daemon failes with a minor error (corruption, etc.),
 887 ; should access to file denied?
 888 ; (default: yes)
 889 deny access on minor error = no
 890
 891 ; send a warning message via Windows Messenger service
 892 ; when virus is found?
 893 ; (default: yes)
 894 send warning message = yes
 895
 896 ; what to do with an infected file
 897 ; quarantine: try to move to quantine directory
 898 ; delete:     delete infected file
 899 ; nothing:    do nothing (default)
 900 infected file action = quarantine
 901
 902 ; where to put infected files - you really want to change this!
 903 quarantine directory  = /opt/clamav/quarantine
 904 ; prefix for files in quarantine
 905 quarantine prefix = vir-
 906
 907 ; as Windows tries to open a file multiple time in a (very) short time
 908 ; of period, samba-vscan use a last recently used file mechanism to avoid
 909 ; multiple scans of a file. This setting specified the maximum number of
 910 ; elements of the last recently used file list. (default: 100)
 911 max lru files entries = 100
 912
 913 ; an entry is invalidad after lru file entry lifetime (in seconds).
 914 ; (Default: 5)
 915 lru file entry lifetime = 5
 916
 917 ; exclude files from being scanned based on the MIME-type! Semi-colon
 918 ; separated list (default: empty list). Use this with care!
 919 exclude file types =
 920
 921 ; socket name of clamd (default: /var/run/clamd). Setting will be ignored if
 922 ; libclamav is used
 923 clamd socket name = /tmp/clamd
 924
 925 ; limits, if vscan-clamav was build for using the clamav library (libclamav)
 926 ; instead of clamd
 927
 928 ; maximum number of files in archive (default: 1000)
 929 libclamav max files in archive = 1000
 930
 931 ; maximum archived file size, in bytes (default: 10 MB)
 932 libclamav max archived file size = 5242880
 933
 934 ; maximum recursion level (default: 5)
 935 libclamav max recursion level = 5
 936 </screen>
 937
 938 <para>
 939 Obviously, a running clam daemon is necessary for this to work. This is a working example for me using ClamAV.
 940 The ClamAV documentation should provide additional configuration examples. On your system these may be located
 941 under the <filename>/usr/share/doc/</filename> directory. Some examples may also target other virus scanners,
 942 any of which can be used.
 943 </para>
 944
 945 </sect2>
 946 </sect1>
 947
 948 </chapter>