1 files changed, 536 insertions, 0 deletions
diff --git a/upstream/archlinux/man8/vfs_fruit.8 b/upstream/archlinux/man8/vfs_fruit.8
new file mode 100644
index 00000000..097d1579
--- /dev/null
+++ b/upstream/archlinux/man8/vfs_fruit.8
@@ -0,0 +1,536 @@
+'\" t
+.\"     Title: vfs_fruit
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/19/2024
+.\"    Manual: System Administration tools
+.\"    Source: Samba 4.19.5
+.\"  Language: English
+.\"
+.TH "VFS_FRUIT" "8" "02/19/2024" "Samba 4\&.19\&.5" "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\&.