path: root/upstream/opensuse-tumbleweed/man8/vfs_fruit.8

'\" t
.\"     Title: vfs_fruit
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/20/2024
.\"    Manual: System Administration tools
.\"    Source: Samba 4.19.5-git.342.57620c4f7eSUSE-oS16.9-x86_64
.\"  Language: English
.\"
.TH "VFS_FRUIT" "8" "02/20/2024" "Samba 4\&.19\&.5\-git\&.342\&." "System Administration tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
vfs_fruit \- Enhanced OS X and Netatalk interoperability
.SH "SYNOPSIS"
.HP \w'\ 'u
vfs objects = fruit
.SH "DESCRIPTION"
.PP
This VFS module is part of the
\fBsamba\fR(7)
suite\&.
.PP
The
vfs_fruit
module provides enhanced compatibility with Apple SMB clients and interoperability with a Netatalk 3 AFP fileserver\&.
.PP
The module should be stacked with
vfs_catia
if enabling character conversion and must be stacked with
vfs_streams_xattr, see the example section for the correct config\&.
.PP
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
vfs_streams_xattr
which must be loaded together with
vfs_fruit\&.
.PP
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\&.
.PP
Having shares with ADS support enabled for OS X client is worthwhile because it resembles the behaviour of Apple\*(Aqs own SMB server implementation and it avoids certain severe performance degradations caused by Samba\*(Aqs case sensitivity semantics\&.
.PP
The OS X metadata and resource fork stream can be stored in a way compatible with Netatalk 3 by setting
fruit:resource = file
and
fruit:metadata = netatalk\&.
.PP
OS X maps NTFS illegal characters to the Unicode private range in SMB requests\&. By setting
fruit:encoding = native, all mapped characters are converted to native ASCII characters\&.
.PP
Finally, share access modes are optionally checked against Netatalk AFP sharing modes by setting
fruit:locking = netatalk\&.
.PP
This module is not stackable other than described in this manpage\&.
.SH "GLOBAL OPTIONS"
.PP
The following options must be set in the global smb\&.conf section and won\*(Aqt take effect when set per share\&.
.PP
fruit:aapl = yes | no
.RS 4
A
\fIglobal\fR
option whether to enable Apple\*(Aqs SMB2+ extension codenamed AAPL\&. Default
\fIyes\fR\&. This extension enhances several deficiencies when connecting from Macs:
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\*(Aqt need to fetch this metadata individually per directory entry resulting in an often tremendous performance increase\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The ability to query and modify the UNIX mode of directory entries\&.
.RE
.sp
.RE
There\*(Aqs a set of per share options that come into play when
\fIfruit:aapl\fR
is enabled\&. These options, listed below, can be used to disable the computation of specific Mac metadata in the directory enumeration context, all are enabled by default:
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_rsize = yes | no
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_finder_info = yes | no
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_max_access = yes | no
.RE
.sp
.RE
See below for a description of these options\&.
.RE
.PP
fruit:nfs_aces = yes | no
.RS 4
A
\fIglobal\fR
option whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled, default
\fIyes\fR\&.
.RE
.PP
fruit:copyfile = yes | no
.RS 4
A
\fIglobal\fR
option whether to enable OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata\&.
.sp
WARNING: the copyfile request is blocking the client while the server does the copy\&.
.sp
The default is
\fIno\fR\&.
.RE
.PP
fruit:model = MacSamba
.RS 4
This option defines the model string inside the AAPL extension and will determine the appearance of the icon representing the Samba server in the Finder window\&.
.sp
The default is
\fIMacSamba\fR\&.
.RE
.SH "OPTIONS"
.PP
The following options can be set either in the global smb\&.conf section or per share\&.
.PP
fruit:resource = [ file | xattr | stream ]
.RS 4
Controls where the OS X resource fork is stored\&.
.sp
Due to a spelling bug in all Samba versions older then 4\&.6\&.0, this option can also be given as
\fIfruit:ressource\fR, ie with two s\&.
.sp
Settings:
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file (default)
\- use a \&._ AppleDouble file compatible with OS X and Netatalk
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
xattr
\- 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
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
stream (experimental)
\- pass the stream on to the next module in the VFS stack\&.
\fIWarning: \fR
this option should not be used with the
\fIstreams_xattr\fR
module due to the extended attributes size limitations of most filesystems\&.
.RE
.sp
.RE
.RE
.PP
fruit:time machine = [ yes | no ]
.RS 4
Controls if Time Machine support via the FULLSYNC volume capability is advertised to clients\&.
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
yes
\- Enables Time Machine support for this share\&. Also registers the share with mDNS in case Samba is built with mDNS support\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no (default)
Disables advertising Time Machine support\&.
.RE
.sp
.RE
This option enforces the following settings per share (or for all shares if enabled globally):
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
durable handles = yes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
kernel oplocks = no
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
kernel share modes = no
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
posix locking = no
.RE
.sp
.RE
.RE
.PP
fruit:time machine max size = SIZE [K|M|G|T|P]
.RS 4
Useful for Time Machine: limits the reported disksize, thus preventing Time Machine from using the whole real disk space for backup\&. The option takes a number plus an optional unit\&.
.sp
\fIIMPORTANT\fR: This is an approximated calculation that only takes into account the contents of Time Machine sparsebundle images\&. Therefore you
\fIMUST NOT\fR
use this volume to store other content when using this option, because it would NOT be accounted\&.
.sp
The calculation works by reading the band size from the Info\&.plist XML file of the sparsebundle, reading the bands/ directory counting the number of band files, and then multiplying one with the other\&.
.RE
.PP
fruit:metadata = [ stream | netatalk ]
.RS 4
Controls where the OS X metadata stream is stored:
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
netatalk (default)
\- use Netatalk compatible xattr
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
stream
\- pass the stream on to the next module in the VFS stack
.RE
.sp
.RE
.RE
.PP
fruit:locking = [ netatalk | none ]
.RS 4

.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
none (default)
\- no cross protocol locking
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
netatalk
\- use cross protocol locking with Netatalk
.RE
.sp
.RE
.RE
.PP
fruit:encoding = [ native | private ]
.RS 4
Controls how the set of illegal NTFS ASCII character, commonly used by OS X clients, are stored in the filesystem\&.
.sp
\fIImportant:\fR
this is known to not fully work with
\fIfruit:metadata=stream\fR
or
\fIfruit:resource=stream\fR\&.
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
private (default)
\- store characters as encoded by the OS X client: mapped to the Unicode private range
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
native
\- store characters with their native ASCII value\&.
\fIImportant\fR: this option requires the use of
\fIvfs_catia\fR
in the VFS module stack as shown in the examples section\&.
.RE
.sp
.RE
.RE
.PP
fruit:veto_appledouble = yes | no
.RS 4
\fINote:\fR
this option only applies when
\fIfruit:resource\fR
is set to
\fIfile\fR
(the default)\&.
.sp
When
\fIfruit:resource\fR
is set to
\fIfile\fR, vfs_fruit may create \&._ AppleDouble files\&. This options controls whether these \&._ AppleDouble files are vetoed which prevents the client from accessing them\&.
.sp
Vetoing \&._ files may break some applications, e\&.g\&. extracting Mac ZIP archives from Mac clients fails, because they contain \&._ files\&.
rsync
will also be unable to sync files beginning with underscores, as the temporary files it uses for these will start with \&._ and so cannot be created\&.
.sp
Setting this option to false will fix this, but the abstraction leak of exposing the internally created \&._ files may have other unknown side effects\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
fruit:posix_rename = yes | no
.RS 4
Whether to enable POSIX directory rename behaviour for OS X clients\&. Without this, directories can\*(Aqt be renamed if any client has any file inside it (recursive!) open\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
readdir_attr:aapl_rsize = yes | no
.RS 4
Return resource fork size in SMB2 FIND responses\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
readdir_attr:aapl_finder_info = yes | no
.RS 4
Return FinderInfo in SMB2 FIND responses\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
readdir_attr:aapl_max_access = yes | no
.RS 4
Return the user\*(Aqs effective maximum permissions in SMB2 FIND responses\&. This is an expensive computation, setting this to off pretends the use has maximum effective permissions\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
fruit:wipe_intentionally_left_blank_rfork = yes | no
.RS 4
Whether to wipe Resource Fork data that matches the special 286 bytes sized placeholder blob that macOS client create on occasion\&. The blob contains a string
\(lqThis resource fork intentionally left blank\(rq, the remaining bytes being mostly zero\&. There being no one use of this data, it is probably safe to discard it\&. When this option is enabled, this module truncates the Resource Fork stream to 0 bytes\&.
.sp
The default is
\fIno\fR\&.
.RE
.PP
fruit:delete_empty_adfiles = yes | no
.RS 4
Whether to delete empty AppleDouble files\&. Empty means that the resource fork entry in the AppleDouble files is of size 0, or the size is exactly 286 bytes and the content matches a special boilerplate resource fork created my macOS\&.
.sp
The default is
\fIno\fR\&.
.RE
.PP
fruit:zero_file_id = yes | no
.RS 4
Whether to return zero to queries of on\-disk file identifier if the client has negotiated AAPL\&.
.sp
Mac applications and / or the Mac SMB client code expect the on\-disk file identifier to have the semantics of HFS+ Catalog Node Identifier (CNID)\&. Samba provides File\-IDs based on a file\*(Aqs inode number which gets recycled across file creation and deletion and can therefore not be used for Mac client\&. Returning a file identifier of zero causes the Mac client to stop using and trusting the file id returned from the server\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
fruit:convert_adouble = yes | no
.RS 4
Whether an attempt shall be made to convert \&._ AppleDouble sidecar files to native streams (xattrs when using vfs_streams_xattr)\&. The main use case for this conversion is transparent migration from a server config without streams support where the macOS client created those AppleDouble sidecar files\&.
.sp
The default is
\fIyes\fR\&.
.RE
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
        \fI[share]\fR
	\m[blue]\fBvfs objects = catia fruit streams_xattr\fR\m[]
	\m[blue]\fBfruit:resource = file\fR\m[]
	\m[blue]\fBfruit:metadata = netatalk\fR\m[]
	\m[blue]\fBfruit:locking = netatalk\fR\m[]
	\m[blue]\fBfruit:encoding = native\fR\m[]
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.PP
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\&.