summaryrefslogtreecommitdiff
path: root/docs/Samba3-HOWTO/TOSHARG-VFS.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/Samba3-HOWTO/TOSHARG-VFS.xml')
-rw-r--r--docs/Samba3-HOWTO/TOSHARG-VFS.xml631
1 files changed, 631 insertions, 0 deletions
diff --git a/docs/Samba3-HOWTO/TOSHARG-VFS.xml b/docs/Samba3-HOWTO/TOSHARG-VFS.xml
new file mode 100644
index 0000000000..3fdcc0ea81
--- /dev/null
+++ b/docs/Samba3-HOWTO/TOSHARG-VFS.xml
@@ -0,0 +1,631 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<chapter id="VFS">
+<chapterinfo>
+ &author.jelmer;
+ &author.jht;
+ &author.tpot;
+ <author><firstname>Simo</firstname><surname>Sorce</surname><contrib>original vfs_skel README</contrib></author>
+ <author><firstname>Alexander</firstname><surname>Bokovoy</surname><contrib>original vfs_netatalk docs</contrib></author>
+ <author><firstname>Stefan</firstname><surname>Metzmacher</surname><contrib>Update for multiple modules</contrib></author>
+ <author><firstname>Ed</firstname><surname>Riddle</surname><contrib>original shadow_copy docs</contrib></author>
+</chapterinfo>
+<title>Stackable VFS modules</title>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+Since Samba-3, there is support for stackable VFS (Virtual File System) modules.
+Samba passes each request to access the UNIX file system through the loaded VFS modules.
+This chapter covers all the modules that come with the Samba source and references to
+some external modules.
+</para>
+
+
+</sect1>
+
+<sect1>
+<title>Discussion</title>
+
+<para>
+If not supplied with your platform distribution binary Samba package you may have problems
+compiling these modules, as shared libraries are compiled and linked in different ways
+on different systems. They currently have been tested against GNU/Linux and IRIX.
+</para>
+
+<para>
+To use the VFS modules, create a share similar to the one below. The
+important parameter is the <smbconfoption name="vfs objects"/> parameter where
+you can list one or more VFS modules by name. For example, to log all access
+to files and put deleted files in a recycle bin, see <link linkend="vfsrecyc">next configuration</link>:
+
+<smbconfexample id="vfsrecyc">
+ <title>smb.conf with VFS modules</title>
+ <smbconfsection name="[audit]"/>
+<smbconfoption name="comment">Audited /data directory</smbconfoption>
+<smbconfoption name="path">/data</smbconfoption>
+<smbconfoption name="vfs objects">audit recycle</smbconfoption>
+<smbconfoption name="writeable">yes</smbconfoption>
+<smbconfoption name="browseable">yes</smbconfoption>
+ </smbconfexample>
+</para>
+
+<para>
+The modules are used in the order in which they are specified.
+Let's say that you want to both have a virus scanner module and a recycle
+bin module. It is wise to put the virus scanner module as the first one so
+that it is the first that get run an may detect a virus immediately, before
+any action is performed on that file.
+<smbconfoption name="vfs objects">vscan-clamav recycle</smbconfoption>
+</para>
+
+<para>
+Samba will attempt to load modules from the <filename>/lib</filename> directory in the root directory of the
+Samba installation (usually <filename>/usr/lib/samba/vfs</filename> or <filename>/usr/local/samba/lib/vfs
+</filename>).
+</para>
+
+<para>
+Some modules can be used twice for the same share.
+This can be done using a configuration similar to the one shown in <link linkend="multimodule">the following example</link>.
+
+<smbconfexample id="multimodule">
+ <title>smb.conf with multiple VFS modules</title>
+<smbconfsection name="[test]"/>
+<smbconfoption name="comment">VFS TEST</smbconfoption>
+<smbconfoption name="path">/data</smbconfoption>
+<smbconfoption name="writeable">yes</smbconfoption>
+<smbconfoption name="browseable">yes</smbconfoption>
+<smbconfoption name="vfs objects">example:example1 example example:test</smbconfoption>
+<smbconfoption name="example1: parameter">1</smbconfoption>
+<smbconfoption name="example: parameter">5</smbconfoption>
+<smbconfoption name="test: parameter">7</smbconfoption>
+</smbconfexample>
+</para>
+
+</sect1>
+
+<sect1>
+<title>Included Modules</title>
+
+ <sect2>
+ <title>audit</title>
+
+ <para>
+ A simple module to audit file access to the syslog
+ facility. The following operations are logged:
+ <itemizedlist>
+ <listitem><para>share</para></listitem>
+ <listitem><para>connect/disconnect</para></listitem>
+ <listitem><para>directory opens/create/remove</para></listitem>
+ <listitem><para>file open/close/rename/unlink/chmod</para></listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>extd_audit</title>
+
+ <para>
+ This module is identical with the <command>audit</command> module above except
+ that it sends audit logs to both syslog as well as the <command>smbd</command> log files. The
+ <smbconfoption name="log level"/> for this module is set in the &smb.conf; file.
+ </para>
+
+ <para>
+ Valid settings and the information that will be recorded are shown in <link linkend="xtdaudit">the next table</link>.
+ </para>
+
+ <table frame="all" id="xtdaudit">
+ <title>Extended Auditing Log Information</title>
+ <tgroup cols="2" align="center">
+ <thead>
+ <row><entry align="center">Log Level</entry><entry>Log Details - File and Directory Operations</entry></row>
+ </thead>
+ <tbody>
+ <row><entry align="center">0</entry><entry align="left">Make Directory, Remove Directory, Unlink</entry></row>
+ <row><entry align="center">1</entry><entry align="left">Open Directory, Rename File, Change Permissions/ACLs</entry></row>
+ <row><entry align="center">2</entry><entry align="left">Open &amp; Close File</entry></row>
+ <row><entry align="center">10</entry><entry align="left">Maximum Debug Level</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect3>
+ <title>Configuration of Auditing</title>
+
+ <para>
+ This auditing tool is more felxible than most people readily will recognize. There are a number of ways
+ by which useful logging information can be recorded.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>Syslog can be used to record all transaction. This can be disabled by setting
+ in the &smb.conf; file <parameter>syslog = 0</parameter>.</para></listitem>
+ <listitem><para>Logging can take place to the default log file (<filename>log.smbd</filename>)
+ for all loaded VFS modules just by setting in the &smb.conf; file
+ <parameter>log level = 0 vfs:x</parameter>, where x is the log level.
+ This will disable general logging while activating all logging of VFS
+ module activity at the log level specified.</para></listitem>
+ <listitem><para>Detailed logging can be obtained per user, per client machine, etc.
+ This requires the above together with the creative use of the
+ <parameter>log file</parameter> settings.</para>
+ <para>An example of detailed per-user and per-machine logging can
+ be obtained by setting
+ <smbconfoption name="log file">/var/log/samba/%U.%m.log</smbconfoption>.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ Auditing information often must be preserved for a long time. So that the log files do not get rotated
+ it is essential that the <smbconfoption name="max log size">0</smbconfoption> be set
+ in the &smb.conf; file.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="fakeperms">
+ <title>fake_perms</title>
+
+ <para>
+ This module was created to allow Roaming Profile files and directories to be set (on the Samba server
+ under UNIX) as read only. This module will, if installed on the Profiles share, report to the client
+ that the Profile files and directories are writeable. This satisfies the client even though the files
+ will never be overwritten as the client logs out or shuts down.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>recycle</title>
+
+ <para>
+ A Recycle Bin-like module. Where used, unlink calls will be intercepted and files moved
+ to the recycle directory instead of being deleted. This gives the same effect as the
+ <guiicon>Recycle Bin</guiicon> on Windows computers.
+ </para>
+
+ <para>
+ The <guiicon>Recycle Bin</guiicon> will not appear in <application>Windows Explorer</application> views of the network file system
+ (share) nor on any mapped drive. Instead, a directory called <filename>.recycle</filename> will be
+ automatically created when the first file is deleted. Users can recover files from the
+ <filename>.recycle</filename> directory. If the <parameter>recycle:keeptree</parameter> has been
+ specified, deleted files will be found in a path identical with that from which the file was deleted.
+ </para>
+
+ <para>Supported options for the <command>recycle</command> module are as follow:
+ <variablelist>
+ <varlistentry>
+ <term>recycle:repository</term>
+ <listitem><para>
+ Relative path of the directory where deleted files should be moved.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:keeptree</term>
+ <listitem><para>
+ Specifies whether the directory structure should be kept or if the files in the directory that is being
+ deleted should be kept separately in the recycle bin.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:versions</term>
+ <listitem><para>
+ If this option is set, two files
+ with the same name that are deleted will both
+ be kept in the recycle bin. Newer deleted versions
+ of a file will be called <quote>Copy #x of <replaceable>filename</replaceable></quote>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:touch</term>
+ <listitem><para>
+ Specifies whether a file's access date should be touched when the file is moved to the recycle bin.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:maxsize</term>
+ <listitem><para>
+ Files that are larger than the number of bytes specified by this parameter will not be put into the recycle bin.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:exclude</term>
+ <listitem><para>
+ List of files that should not be put into the recycle bin when deleted, but deleted in the regular way.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:exclude_dir</term>
+ <listitem><para>
+ Contains a list of directories. When files from these directories are
+ deleted, they are not put into the
+ recycle bin but are deleted in the
+ regular way.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:noversions</term>
+ <listitem><para>
+ Specifies a list of paths (wildcards such as * and ? are supported) for which no versioning should be used. Only useful when <emphasis>recycle:versions</emphasis> is enabled.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>netatalk</title>
+
+ <para>
+ A netatalk module will ease co-existence of Samba and netatalk file sharing services.
+ </para>
+
+ <para>Advantages compared to the old netatalk module:
+ <itemizedlist>
+ <listitem><para>Does not care about creating .AppleDouble forks, just keeps them in sync.</para></listitem>
+ <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>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>shadow_copy</title>
+ <warning>
+ <para>
+ <emphasis>THIS IS NOT A BACKUP, ARCHIVAL, OR VERSION CONTROL
+ SOLUTION!</emphasis></para>
+ <para>
+ With Samba or Windows servers, shadow copy is designed to be
+ an end-user tool only. It does not replace or enhance your
+ backup and archival solutions and should in no way be
+ considered as such. Additionally, if you need version
+ control, implement a version control system. You have been
+ warned.</para>
+ </warning>
+ <para>
+ The shadow_copy module allows you to setup functionality that
+ is similar to MS shadow copy services. When setup properly,
+ this module allows Microsoft shadow copy clients to browse
+ "shadow copies" on samba shares. You will need to install the
+ shadow copy client. You can get the MS shadow copy client
+ <ulink noescape="1"
+ url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">here.</ulink>.
+ Note the additional requirements for pre-Windows XP clients.
+ I did not test this functionality with any pre-Windows XP
+ clients. You should be able to get more information about MS
+ Shadow Copy <ulink noescape="1"
+ url="http://www.microsoft.com/windowsserver2003/techinfo/overview/scr.mspx">from
+ the Microsoft's site</ulink>.</para>
+ <para>
+ The shadow_copy VFS module requires some underlying file system
+ setup with some sort of Logical Volume Manager (LVM) such as
+ LVM1, LVM2, or EVMS. Setting up LVM is beyond the scope of
+ this document; however, we will outline the steps we took to
+ test this functionality for <emphasis>example purposes
+ only.</emphasis> You need to make sure the LVM implementation
+ you choose to deploy is ready for production. Make sure you
+ do plenty of tests.</para>
+ <para>
+ Here are some common resources for LVM and EVMS:
+ <itemizedlist>
+ <listitem>
+ <para><ulink noescape="1"
+ url="http://www.sistina.com/products_lvm_download.htm">Sistina's
+ LVM1 and LVM2</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://evms.sourceforge.net/">Enterprise
+ Volume Management System (EVMS)</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://tldp.org/HOWTO/LVM-HOWTO/">The LVM HOWTO</ulink></para>
+ </listitem>
+ <listitem>
+ <para>
+ See <ulink
+ url="http://www-106.ibm.com/developerworks/linux/library/l-lvm/">Learning
+ Linux LVM, Part 1</ulink> and <ulink
+ url="http://www-106.ibm.com/developerworks/library/l-lvm2.html">Learning
+ Linux LWM, Part 2</ulink> for Daniel Robbins' well
+ written a two part tutorial on Linux and LVM using LVM
+ source code and reiserfs.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <sect3>
+ <title>Shadow Copy Setup</title>
+ <para>
+ At the time of this writing, not much testing has been done.
+ I tested the shadow copy VFS module with a specific scenario
+ which was not deployed in a production environment, but more
+ as a proof of concept. The scenario involved a Samba 3 file
+ server on Debian Sarge with an XFS file system and LVM1. I
+ do NOT recommend you use this as a solution without doing
+ your own due diligence with regard to all the components
+ presented here. That said, following is an basic outline of
+ how I got things going.</para>
+ <orderedlist>
+ <listitem>
+ <formalpara>
+ <title>Installed Operating System </title>
+ <para>
+ In my tests, I used <ulink
+ url="http://www.debian.org/devel/debian-installer/">Debian
+ Sarge</ulink> (i.e. testing) on an XFS file system.
+ Setting up the OS is a bit beyond the scope of this
+ document. It is assumed that you have a working OS
+ capable of running Samba.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Install &amp; Configure Samba</title>
+ <para>
+ See the <link linkend="introduction">installation
+ section</link> of this HOWTO for more detail on this.
+ It doesn't matter if it is a Domain Controller or
+ Member File Server, but it is assumed that you have a
+ working Samba 3.0.3 or newer server running.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Install &amp; Configure LVM</title>
+ <para>
+ Before you can make shadow copies available to the
+ client, you have to create the shadow copies. This is
+ done by taking some sort of file system snapshot.
+ Snapshots are a typical feature of Logical Volume
+ Managers such as LVM, so we first need to have that
+ setup.</para>
+ </formalpara>
+ <itemizedlist>
+ <para>
+ The following is provided as an example and will be
+ most helpful for Debian users. Again, this was tested
+ using the "testing" or "Sarge" distribution.</para>
+ <listitem>
+ <para>
+ Install lvm10 and devfsd packages if you have not
+ done so already. On Debian systems, you are warned
+ of the interaction of devfs and lvm1 which requires
+ the use of devfs filenames. Running
+ <command>apt-get update &amp;&amp; apt-get install
+ lvm10 devfsd xfsprogs</command> should do the trick
+ for this example.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Now you need to create a volume. You will need to
+ create a partition (or partitions) to add to your
+ volume. Use your favorite partitioning tool
+ (e.g. Linux fdisk, cfdisk, etc.). The partition
+ type should be set to 0x8e for "Linux LVM." In this
+ example, we will use /dev/hdb1.</para>
+ <para>
+ Once you have the Linux LVM partition (type 0x8e),
+ you can run a series of commands to create the LVM
+ volume. You can use several disks and or
+ partitions, but we will use only one in this
+ example. You may also need to load the kernel
+ module with something like <command>modprobe lvm-mod
+ </command> and set your system up to load it on
+ reboot by adding it to
+ (<filename>/etc/modules</filename>). </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create the physical volume with <command>pvcreate
+ /dev/hdb1</command></para>
+ </listitem>
+ <listitem>
+ <para>
+ Create the volume group with and add /dev/hda1 to it
+ with <command>vgcreate shadowvol /dev/hdb1</command>
+ </para>
+ <para>
+ You can use <command>vgdisplay</command> to review
+ information about the volume group.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Now you can create the logical volume with something
+ like <command>lvcreate -L400M -nsh_test
+ shadowvol</command></para>
+ <para>
+ This creates the logical volume of 400MB's named
+ "sh_test" in the volume group we created called
+ shadowvol. If everything is working so far, you
+ should see them in
+ <filename>/dev/shadowvol</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Now we should be ready to format the logical volume
+ we named sh_test with <command>mkfs.xfs
+ /dev/shadowvol/sh_test</command></para>
+ <para>
+ You can format the logical volume with any file
+ system you choose, but make sure to use one that
+ allows you to take advantage of the additional
+ features of LVM such as freezing, resizing and
+ growing your file systems.</para>
+ <para>
+ Now we have an LVM volume where we can play with the
+ shadow_copy VFS module.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Now we need to prepare the directory with something
+ like <command>mkdir -p /data/shadow_share</command>
+ or whatever you want to name your shadow copy
+ enabled Samba share. Make sure you set the
+ permissions such that you can use it. If in doubt,
+ use <command>chmod 777 /data/shadow_share</command>
+ and tighten the permissions once you get things
+ working.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Mount the LVM volume using something like
+ <command>mount /dev/shadowvol/sh_test
+ /data/shadow_share</command></para>
+ <para>
+ You may also want to edit your
+ <filename>/etc/fstab</filename> so that this
+ partition mounts during the system boot.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Install &amp; Configure the shadow_copy VFS
+ Module</title>
+ <para>
+ Finally we get to the actual shadow_copy VFS module.
+ The shadow_copy VFS module should be available in
+ Samba 3.0.3 and higher. The smb.conf configuration is pretty
+ standard. Here is our example of a share configured
+ with the shadow_copy VFS module:</para>
+ </formalpara>
+ <para>
+ <smbconfexample id="vfsshadow">
+ <title>Share With shadow_copy VFS</title>
+ <smbconfsection name="[shadow_share]"/>
+ <smbconfoption name="comment">Shadow Copy Enabled Share</smbconfoption>
+ <smbconfoption name="path">/data/shadow_share</smbconfoption>
+ <smbconfoption name="vfs objects">shadow_copy</smbconfoption>
+ <smbconfoption name="writeable">yes</smbconfoption>
+ <smbconfoption name="browseable">yes</smbconfoption>
+ </smbconfexample>
+ </para>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Create Snapshots and Make Them Available to shadow_copy.so</title>
+ <para>
+ Before you can browse the shadow copies, you must
+ create them and mount them. This will most likely be
+ done with a script that runs as a cron job. With this
+ particular solution, the shadow_copy VFS module is
+ used to browse LVM snapshots. Those snapshots are not
+ created by the module. They are not made available by
+ the module either. This module allows the shadow copy
+ enabled client to browse the snapshots you take and
+ make available.</para>
+ </formalpara>
+ <para>
+ Here is a simple script used to create and mount the
+ snapshots:
+ <screen>
+#!/bin/bash
+# This is a test, this is only a test
+SNAPNAME=`date +%Y.%m.%d-%H.%M.%S`
+xfs_freeze -f /data/shadow_share/
+lvcreate -L10M -s -n $SNAPNAME /dev/shadowvol/sh_test
+xfs_freeze -u /data/shadow_share/
+mkdir /data/shadow_share/@GMT-$SNAPNAME
+mount /dev/shadowvol/$SNAPNAME /data/shadow_share/@GMT-$SNAPNAME -onouuid,ro
+ </screen>
+ Note that the script does not handle other things like
+ remounting snapshots on reboot.
+ </para>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Test From Client</title>
+ <para>
+ To test, you will need to install the shadow copy
+ client which you can obtain from the <ulink
+ url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">Microsoft
+ web site.</ulink> I only tested this with an XP client
+ so your results may vary with other pre-XP clients.
+ Once installed, with your XP client you can
+ right-click on specific files or in the empty space of
+ the shadow_share and view the "properties". If
+ anything has changed, then you will see it on the
+ "Previous Versions" tab of the properties
+ window. </para>
+ </formalpara>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
+
+</sect1>
+
+<sect1>
+<title>VFS Modules Available Elsewhere</title>
+
+<para>
+This section contains a listing of various other VFS modules that
+have been posted but do not currently reside in the Samba CVS
+tree for one reason or another (e.g., it is easy for the maintainer
+to have his or her own CVS tree).
+</para>
+
+<para>
+No statements about the stability or functionality of any module
+should be implied due to its presence here.
+</para>
+
+ <sect2>
+ <title>DatabaseFS</title>
+
+ <para>
+ URL: <ulink noescape="1" url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">http://www.css.tayloru.edu/~elorimer/databasefs/index.php</ulink>
+ </para>
+
+ <para>By <ulink url="mailto:elorimer@css.tayloru.edu">Eric Lorimer.</ulink></para>
+
+ <para>
+ I have created a VFS module that implements a fairly complete read-only
+ filesystem. It presents information from a database as a filesystem in
+ a modular and generic way to allow different databases to be used
+ (originally designed for organizing MP3s under directories such as
+ <quote>Artists,</quote> <quote>Song Keywords,</quote> and so on. I have since easily
+ applied it to a student
+ roster database.) The directory structure is stored in the
+ database itself and the module makes no assumptions about the database
+ structure beyond the table it requires to run.
+ </para>
+
+ <para>
+ Any feedback would be appreciated: comments, suggestions, patches,
+ and so on. If nothing else, hopefully it might prove useful for someone
+ else who wishes to create a virtual filesystem.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>vscan</title>
+
+ <para>URL: <ulink noescape="1" url="http://www.openantivirus.org/projects.php#samba-vscan">http://www.openantivirus.org/projects.php#samba-vscan</ulink></para>
+
+ <para>
+ samba-vscan is a proof-of-concept module for Samba, which
+ provides on-access anti-virus support for files shared using
+ Samba.
+ samba-vscan supports various virus scanners and is maintained
+ by Rainer Link.
+ </para>
+
+ </sect2>
+</sect1>
+
+</chapter>