VFS_FRUIT(8)

📦
version 4.24.7 · 27 versions
, in ubuntu stonking

💖 VFS_FRUIT ✨ (that's the VFS_FRUIT(8) jam, from the System Administration tools crew, bestie) 🍓

🌸 NAME 🌸

vfs_fruit — enhanced OS X and Netatalk interoperability, aka the module that makes your Mac friends stop side-eyeing your Samba server 💅

🦋 SYNOPSIS 🦋

vfs objects = fruit

👑 DESCRIPTION 👑

okay so. This VFS module is part of the samba(7) suite, hi bestie 🫶. What vfs_fruit does is give you enhanced compatibility with Apple SMB clients plus interoperability with a Netatalk 3 AFP fileserver. it's giving bilingual. it's giving bridge-builder.

The module should be stacked with vfs_catia if you're enabling character conversion, and it must be stacked with vfs_streams_xattr — check the example section for the correct config, no cap 🌈.

It turns on alternate data streams (ADS) support for a share, intercepts the OS X special streams "AFP_AfpInfo" and "AFP_Resource", and handles them in a very special way 💅. Every other named stream? Deferred to vfs_streams_xattr, which has to be loaded together with vfs_fruit. They're a package deal, iykyk.

🙈 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. one bad tcon and the whole vibe is cancelled, literally.

Having shares with ADS support enabled for OS X clients is genuinely worthwhile — 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. main character energy, honestly.

The OS X metadata and resource fork stream can be stored in a way that's compatible with Netatalk 3 by setting fruit:resource = file and fruit:metadata = netatalk 🎀.

OS X maps NTFS illegal characters to the Unicode private range in SMB requests. By setting fruit:encoding = native, all mapped characters get converted to native ASCII characters. slay.

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

💀 This module is not stackable other than described in this manpage. We said what we said.

🧚 GLOBAL OPTIONS 🧚

These following options must be set in the global smb.conf section and won't take effect when set per share. Per-share? girl no. Global only 💜.

  • fruit:aapl = yes | no — a global option for whether you want to enable Apple's SMB2+ extension codenamed AAPL. Default is yes. This extension fixes several deficiencies when connecting from Macs:
    • directory enumeration gets enriched with Mac relevant filesystem metadata (UNIX mode, FinderInfo, resource fork size and effective permission) — so as a result, the Mac client doesn't need to fetch this metadata individually per directory entry, which results in an often tremendous performance increase 🔥. it's giving glow-up.
    • the ability to query and modify the UNIX mode of directory entries ✨.

There's a set of per share options that come into play when fruit:aapl is enabled. These options, listed below, can be used to disable the computation of specific Mac metadata in the directory enumeration context — all of them are enabled by default 🫶:

  • readdir_attr:aapl_rsize = yes | no
  • readdir_attr:aapl_finder_info = yes | no
  • readdir_attr:aapl_max_access = yes | no

See below for a description of these options 👀.

  • fruit:nfs_aces = yes | no — a global option for whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled. Default is yes.
  • fruit:copyfile = yes | no — a global option for whether to enable the OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata 🍓.
😭 WARNING: the copyfile request is blocking the client while the server does the copy. your client is just standing there. waiting. respectfully.

The default is no.

  • fruit:model = MacSamba — this option defines the model string inside the AAPL extension, and it will determine the appearance of the icon representing the Samba server in the Finder window 🎀. aesthetics matter.

The default is MacSamba.

✨ OPTIONS ✨

okay bestie, every single one of these can live in the global smb.conf section or be set per share — your call, both are valid 💅

  • fruit:resource = [ file | xattr | stream ] — decides where the OS X resource fork gets stored 🍎

little historical tea: due to a spelling bug in all Samba versions older than 4.6.0, you can also write this option as fruit:ressource, ie with two s 😭 (the typo is canon, we respect it)

Settings:

  • file (default) — use a ._ AppleDouble file compatible with OS X and Netatalk ✨
  • xattr — use a xattr, which 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 💅
  • stream (experimental) — pass the stream on to the next module in the VFS stack.
Warning: this option should not be used with the streams_xattr module due to the extended attributes size limitations of most filesystems. do not do this, bestie 🙈
  • fruit:time machine = [ yes | no ] — controls whether Time Machine support via the FULLSYNC volume capability is advertised to clients ⏰
    • yes — enables Time Machine support for this share. Also registers the share with mDNS in case Samba is built with mDNS support 🎀
    • no (default) — disables advertising Time Machine support.

turning this on enforces the following settings per share (or for all shares if enabled globally), no takebacks:

  • durable handles = yes
  • kernel oplocks = no
  • kernel share modes = no
  • posix locking = no
  • fruit:time machine max size = SIZE [K|M|G|T|P] — lowkey a lifesaver for Time Machine: it limits the reported disksize, which stops Time Machine from eating your entire real disk for backup 🫶 The option takes a number plus an optional unit.
IMPORTANT: this is an approximated calculation that only takes into account the contents of Time Machine sparsebundle images. Therefore you MUST NOT use this volume to store other content when using this option, because it would NOT be accounted. fr fr, it will not see it 😭

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. math is the moment ✨

  • fruit:metadata = [ stream | netatalk ] — controls where the OS X metadata stream gets stored 🦋
    • netatalk (default) — use Netatalk compatible xattr
    • stream — pass the stream on to the next module in the VFS stack
  • fruit:locking = [ netatalk | none ]
    • none (default) — no cross protocol locking
    • netatalk — use cross protocol locking with Netatalk 🔒
  • fruit:encoding = [ native | private ] — controls how the set of illegal NTFS ASCII characters, commonly used by OS X clients, are stored in the filesystem 🌸
Important: this is known to not fully work with fruit:metadata=stream or fruit:resource=stream. noted, moving on 💀
  • private (default) — store characters as encoded by the OS X client: mapped to the Unicode private range
  • native — store characters with their native ASCII value.
Important: this option requires the use of vfs_catia in the VFS module stack as shown in the examples section 👑
  • fruit:veto_appledouble = yes | no — note: this option only applies when fruit:resource is set to file (the default).

When fruit:resource is set to file, vfs_fruit may create ._ AppleDouble files. This option controls whether these ._ AppleDouble files are vetoed, which prevents the client from accessing them 🚫

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. yeah. it's giving consequences 😭

Setting this option to false will fix this, but the abstraction leak of exposing the internally created ._ files may have other unknown side effects. pick your poison bestie 💀

The default is yes.

  • readdir_attr:aapl_rsize = yes | no — return resource fork size in SMB2 FIND responses.

The default is yes.

  • readdir_attr:aapl_finder_info = yes | no — return FinderInfo in SMB2 FIND responses.

The default is yes.

  • readdir_attr:aapl_max_access = yes | no — return the user's effective maximum permissions in SMB2 FIND responses. This is an expensive computation, setting this to off pretends the use has maximum effective permissions 💸

The default is yes.

  • fruit:wipe_intentionally_left_blank_rfork = yes | no — 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 “This resource fork intentionally left blank”, 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 🧹

The default is no.

  • fruit:delete_empty_adfiles = yes | no — 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 🗑️

The default is no.

  • fruit:zero_file_id = yes | no — whether to return zero to queries of on-disk file identifier if the client has negotiated AAPL.

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's 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 🌀

The default is yes.

  • fruit:convert_adouble = yes | no — 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 🦋

The default is yes.

  • fruit:validate_afpinfo = yes | no — Apple clients use the AFP_AfpInfo stream to store structured file metadata. As part of the marshaled data stored in the stream the first eight bytes contain some header information. Apple's SMB server as well as Samba will validate this header bytes processing a client write request on this stream, and, if the validation fails, fail the write. While this validation is generally correct, in some data migration scenarios clients may try to migrate data from 3rd-party SMB servers to Samba servers where the header information is broken for whatever reason. To allow migration and header fix-up in these scenarios, the validation can be temporarily disabled by setting this option to no 🛠️

The default is yes.

  • fruit:veto_localized = yes | no — when fruit:veto_localized is set to yes, vfs_fruit will automatically veto any attempts to access the .localized file or directory. These can be created in order to let Mac OS provide localized translations for folder names (typically for localized versions of Desktop, Music, etc.). When very large directories are listed a Mac client might do queries for the presence of the .localized file for each and every entry in that directory listing. In combination with clustered filesystems this might have a significant impact on the overal directory listing performance. When potential folder name translation is not desired this option allows to avoid the additional network overhead by not letting the server go down to the filesystem layer for any queries 🚀

The default is no.

  • fruit:posix_opens = yes | no — when fruit:posix_opens is set to yes, vfs_fruit will internally translate all filesystem semantics to use POSIX behaviour instead of Windows behaviour. As Macs are closer to POSIX than Windows with regard to filesystem semantics, this improves access semantics for a lot of corner cases 💅

The default is yes.

  • fruit:ignore_zero_aces = yes | no — when fruit:ignore_zero_aces is enabled, attempts to modify filesystem permissions fail if the ACL sent over the wire contains no ACEs. This is completely valid client behaviour, but it means subsequently no further access is possible to the file, unless permissions get fixed by an administrator 😬

This problematic behaviour has been reported for latest macOS versions and this new option allows to work around it.

The default is yes.

🌈 EXAMPLES 🌈

here's the whole vibe, copy responsibly bestie:

                   [share]
                vfs objects = catia fruit streams_xattr
                fruit:resource = file
                fruit:metadata = netatalk
                fruit:locking = netatalk
                fruit:encoding = native

💜 AUTHOR 💜

The original Samba software and related utilities were created by Andrew Tridgell — king behavior, honestly 👑 Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed. it's giving community, it's giving legacy 🫶

and that's the whole page, bestie!! this was Samba 4.24.7-Ubuntu-4.24.7+dfs, dated 09/13/2026, and you just read VFS_FRUIT(8) — go forth and configure your shares, you absolute icon 🎀✨💅

📦 where this page comes from