New structure for the docs:

 - Same name for a doc everywhere (howto -> Samba-HOWTO-Collection, etc)
 - Shorter and more clearly structured Makefile
 - Make it possible to change the paths for the images
(This used to be commit 96f6c05f25acc8a9bb1977b8bd5cc97ce511b6b1)

1 files changed, 602 insertions, 0 deletions

diff --git a/docs/Samba-HOWTO-Collection/VFS.xml b/docs/Samba-HOWTO-Collection/VFS.xml
new file mode 100644
index 0000000000..d73f55380a
--- /dev/null
+++ b/docs/Samba-HOWTO-Collection/VFS.xml
@@ -0,0 +1,602 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+  <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
+  %global_entities;
+]>
+
+<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</name></smbconfoption> 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>[audit]</smbconfsection>
+<smbconfoption><name>comment</name><value>Audited /data directory</value></smbconfoption>
+<smbconfoption><name>path</name><value>/data</value></smbconfoption>
+<smbconfoption><name>vfs objects</name><value>audit recycle</value></smbconfoption>
+<smbconfoption><name>writeable</name><value>yes</value></smbconfoption>
+<smbconfoption><name>browseable</name><value>yes</value></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</name><value>vscan-clamav recycle</value></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>[test]</smbconfsection>
+<smbconfoption><name>comment</name><value>VFS TEST</value></smbconfoption>
+<smbconfoption><name>path</name><value>/data</value></smbconfoption>
+<smbconfoption><name>writeable</name><value>yes</value></smbconfoption>
+<smbconfoption><name>browseable</name><value>yes</value></smbconfoption>
+<smbconfoption><name>vfs objects</name><value>example:example1 example example:test</value></smbconfoption>
+<smbconfoption><name>example1: parameter</name><value>1</value></smbconfoption>
+<smbconfoption><name>example:  parameter</name><value>5</value></smbconfoption>
+<smbconfoption><name>test:	  parameter</name><value>7</value></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</name></smbconfoption> 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">Creation / Deletion</entry></row>
+			<row><entry align="center">1</entry><entry align="left">Create / Delete / Rename / Permission Changes</entry></row>
+			<row><entry align="center">2</entry><entry align="left">Create / Delete / Rename / Perm Change / Open / Close</entry></row>
+			</tbody>
+		</tgroup>
+		</table>
+
+	</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>[shadow_share]</smbconfsection>
+		<smbconfoption><name>comment</name><value>Shadow Copy Enabled Share</value></smbconfoption>
+		<smbconfoption><name>path</name><value>/data/shadow_share</value></smbconfoption>
+		<smbconfoption><name>vfs objects</name><value>shadow_copy</value></smbconfoption>
+		<smbconfoption><name>writeable</name><value>yes</value></smbconfoption>
+		<smbconfoption><name>browseable</name><value>yes</value></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/">http://www.openantivirus.org/</ulink></para>
+
+		<para>
+		<filename>samba-vscan</filename> is a proof-of-concept module for Samba, which
+		uses the VFS (virtual file system) features of Samba 2.2.x/3.0
+		alphaX. Of course, Samba has to be compiled with VFS support. 
+		<filename>samba-vscan</filename> supports various virus scanners and is maintained 
+		by Rainer Link.
+		</para>
+
+	</sect2>
+</sect1>
+
+</chapter>