diff options
Diffstat (limited to 'docs/Samba3-HOWTO/TOSHARG-VFS.xml')
| -rw-r--r-- | docs/Samba3-HOWTO/TOSHARG-VFS.xml | 631 |
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 & 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 & 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 & 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 && 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 & 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> |