summaryrefslogtreecommitdiff
path: root/docs/howto/VFS.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/howto/VFS.xml')
-rw-r--r--docs/howto/VFS.xml310
1 files changed, 310 insertions, 0 deletions
diff --git a/docs/howto/VFS.xml b/docs/howto/VFS.xml
new file mode 100644
index 0000000000..1e268a09e3
--- /dev/null
+++ b/docs/howto/VFS.xml
@@ -0,0 +1,310 @@
+<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>
+</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>writable</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>share</listitem>
+ <listitem>connect/disconnect</listitem>
+ <listitem>directory opens/create/remove</listitem>
+ <listitem>file open/close/rename/unlink/chmod</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 writable. 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>
+ Opposite of <parameter>recycle:versions</parameter>. If both options are specified, this one takes precedence.
+ </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>
+
+</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>