samba-mirror/docs-xml/manpages/vfs_fruit.8.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<refentry id="vfs_fruit.8">

<refmeta>
	<refentrytitle>vfs_fruit</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo class="source">Samba</refmiscinfo>
	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
	<refmiscinfo class="version">4.6</refmiscinfo>
</refmeta>


<refnamediv>
	<refname>vfs_fruit</refname>
	<refpurpose>Enhanced OS X and Netatalk interoperability</refpurpose>
</refnamediv>

<refsynopsisdiv>
	<cmdsynopsis>
		<command>vfs objects = fruit</command>
	</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
	<title>DESCRIPTION</title>

	<para>This VFS module is part of the
	<citerefentry><refentrytitle>samba</refentrytitle>
	<manvolnum>7</manvolnum></citerefentry> suite.</para>

	<para>The <command>vfs_fruit</command> module provides
	enhanced compatibility with Apple SMB clients and
	interoperability with a Netatalk 3 AFP fileserver.</para>

	<para>The module should be stacked with
	<command>vfs_catia</command> if enabling character conversion and
	must be stacked with <command>vfs_streams_xattr</command>, see the
	example section for the correct config.</para>

	<para>The module enables alternate data streams (ADS) support
	for a share, intercepts the OS X special streams "AFP_AfpInfo"
	and "AFP_Resource" and handles them in a special way. All
	other named streams are deferred to
	<command>vfs_streams_xattr</command> which must be loaded
	together with <command>vfs_fruit</command>.</para>

	<para>vfs_fruit requires "ea support = yes".</para>

	<para>Be careful when mixing shares with and without
	vfs_fruit. OS X clients negotiate SMB2 AAPL protocol
	extensions on the first tcon, so mixing shares with and
	without fruit will globally disable AAPL if the first tcon is
	without fruit.</para>

	<para>Having shares with ADS support enabled for OS X client
	is worthwhile because it resembles the behaviour of Apple's
	own SMB server implementation and it avoids certain severe
	performance degradations caused by Samba's case sensitivity
	semantics.</para>

	<para>The OS X metadata and resource fork stream can be stored
	in a way compatible with Netatalk 3 by setting
	<command>fruit:resource = file</command> and
	<command>fruit:metadata = netatalk</command>.</para>

	<para>OS X maps NTFS illegal characters to the Unicode private
	range in SMB requests. By setting <command>fruit:encoding =
	native</command>, all mapped characters are converted to
	native ASCII characters.</para>

	<para>Finally, share access modes are optionally checked
	against Netatalk AFP sharing modes by setting
	<command>fruit:locking = netatalk</command>.</para>

	<para>This module is not stackable other then described in
	this manpage.</para>

</refsect1>

<refsect1>
	<title>OPTIONS</title>

	<variablelist>

	  <varlistentry>
	    <term>fruit:resource = [ file | xattr | stream ]</term>
	    <listitem>
	      <para>Controls where the OS X resource fork is stored.</para>

	      <para>Due to a spelling bug in all Samba versions older then
	      4.6.0, this option can also be given as
	      <emphasis>fruit:ressource</emphasis>, ie with two s.</para>

	      <para>Settings:</para>

	      <itemizedlist>
		<listitem><para><command>file (default)</command> - use a ._
		AppleDouble file compatible with OS X and
		Netatalk</para></listitem>

		<listitem><para><command>xattr</command> - use a
		xattr, requires a filesystem with large xattr support
		and a file IO API compatible with xattrs, this boils
		down to Solaris and derived platforms and
		ZFS</para></listitem>

		<listitem><para><command>stream</command> - pass the
		stream on to the next module in the VFS
		stack</para></listitem>
	      </itemizedlist>

	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:metadata = [ stream | netatalk ]</term>
	    <listitem>
	      <para>Controls where the OS X metadata stream is stored:</para>

	      <itemizedlist>
		<listitem><para><command>netatalk (default)</command> - use
		Netatalk compatible xattr</para></listitem>

		<listitem><para><command>stream</command> - pass the
		stream on to the next module in the VFS
		stack</para></listitem>
	      </itemizedlist>

	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:locking = [ netatalk | none ]</term>
	    <listitem>
	      <para></para>
	      <itemizedlist>
		<listitem><para><command>none (default)</command> - no
		cross protocol locking</para></listitem>

		<listitem><para><command>netatalk</command> - use
		cross protocol locking with Netatalk</para></listitem>

	      </itemizedlist>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:encoding = [ native | private ]</term>
	    <listitem>

	      <para>Controls how the set of illegal NTFS ASCII
	      character, commonly used by OS X clients, are stored in
	      the filesystem:</para>

	      <itemizedlist>

		<listitem><para><command>private (default)</command> -
		store characters as encoded by the OS X client: mapped
		to the Unicode private range</para></listitem>

		<listitem><para><command>native</command> - store
		characters with their native ASCII
		value. <emphasis>Important</emphasis>: this option
		requires the use of <emphasis>vfs_catia</emphasis> in
		the VFS module stack as shown in the examples
		section.</para></listitem>

	      </itemizedlist>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:aapl = yes | no</term>
	    <listitem>
	      <para>A global option whether to enable Apple's SMB2+
	      extension codenamed AAPL. Default
	      <emphasis>yes</emphasis>. This extension enhances
	      several deficiencies when connecting from Macs:</para>

	      <itemizedlist>
		<listitem><para>directory enumeration is enriched with
		Mac relevant filesystem metadata (UNIX mode,
		FinderInfo, resource fork size and effective
		permission), as a result the Mac client doesn't need
		to fetch this metadata individuallly per directory
		entry resulting in an often tremendous performance
		increase.</para></listitem>

		<listitem><para>The ability to query and modify the
		UNIX mode of directory entries.</para></listitem>
	      </itemizedlist>

	      <para>There's a set of per share options that can be
	      used to disable the computation of specific Mac metadata
	      in the directory enumeration context, all are enabled by
	      default:</para>

	      <itemizedlist>
		<listitem><para>readdir_attr:aapl_rsize = true | false</para></listitem>
		<listitem><para>readdir_attr:aapl_finder_info = true | false</para></listitem>
		<listitem><para>readdir_attr:aapl_max_access = true | false</para></listitem>
	      </itemizedlist>

	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:nfs_aces = yes | no</term>
	    <listitem>
	      <para>Whether support for querying and modifying the
	      UNIX mode of directory entries via NFS ACEs is enabled,
	      default <emphasis>yes</emphasis>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:veto_appledouble = yes | no</term>
	    <listitem>
	      <para>Whether ._ AppleDouble files are vetoed which
	      prevents the client from seing and accessing internal
	      AppleDouble files created by vfs_fruit itself for the
	      purpose of storing a Mac resource fork.</para>
	      <para>Vetoing ._ files may break some applications, eg
	      extracting Mac ZIP archives from Mac clients failes,
	      because they contain ._ files. Setting this option to
	      false will fix this, but the abstraction leak of
	      exposing the internally created ._ files may have other
	      unknown side effects.</para>
	      <para>The default is <emphasis>yes</emphasis>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:copyfile = yes | no</term>
	    <listitem>
	      <para>Whether to enable OS X specific copychunk ioctl
	      that requests a copy of a whole file along with all
	      attached metadata.</para>
	      <para>WARNING: the copyfile request is blocking the
	      client while the server does the copy.</para>.
	      <para>The default is <emphasis>no</emphasis>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>fruit:posix_rename = yes | no</term>
	    <listitem>
	      <para>Whether to enable POSIX directory rename behaviour
	      for OS X clients. Without this, directories can't be
	      renamed if any client has any file inside it
	      (recursive!) open.</para>
	      <para>The default is <emphasis>yes</emphasis>.</para>
	    </listitem>
	  </varlistentry>

	</variablelist>
</refsect1>

<refsect1>
	<title>EXAMPLES</title>

<programlisting>
        <smbconfsection name="[share]"/>
	<smbconfoption name="ea support">yes</smbconfoption>
	<smbconfoption name="vfs objects">catia fruit streams_xattr</smbconfoption>
	<smbconfoption name="fruit:resource">file</smbconfoption>
	<smbconfoption name="fruit:metadata">netatalk</smbconfoption>
	<smbconfoption name="fruit:locking">netatalk</smbconfoption>
	<smbconfoption name="fruit:encoding">native</smbconfoption>
</programlisting>

</refsect1>

<refsect1>
	<title>AUTHOR</title>

	<para>The original Samba software and related utilities
	were created by Andrew Tridgell. Samba is now developed
	by the Samba Team as an Open Source project similar
	to the way the Linux kernel is developed.</para>

</refsect1>

</refentry>