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