Debian Codegraph @

upstream/opensuse-tumbleweed/man8/vfs_fruit.8

raw
1 '\" t
2 .\" Title: vfs_fruit
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 05/26/2026
6 .\" Manual: System Administration tools
7 .\" Source: Samba 4.23.8-git.477.f78166bceedSUSE-oS16.9-x86_64
8 .\" Language: English
9 .\"
10 .TH "VFS_FRUIT" "8" "05/26/2026" "Samba 4\&.23\&.8\-git\&.477\&.f78166bcee" "System Administration tools"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 vfs_fruit \- Enhanced OS X and Netatalk interoperability
32 .SH "SYNOPSIS"
33 .HP \w'\ 'u
34 vfs objects = fruit
35 .SH "DESCRIPTION"
36 .PP
37 This VFS module is part of the
38 \fBsamba\fR(7)
39 suite\&.
40 .PP
41 The
42 vfs_fruit
43 module provides enhanced compatibility with Apple SMB clients and interoperability with a Netatalk 3 AFP fileserver\&.
44 .PP
45 The module should be stacked with
46 vfs_catia
47 if enabling character conversion and must be stacked with
48 vfs_streams_xattr, see the example section for the correct config\&.
49 .PP
50 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
51 vfs_streams_xattr
52 which must be loaded together with
53 vfs_fruit\&.
54 .PP
55 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\&.
56 .PP
57 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\&.
58 .PP
59 The OS X metadata and resource fork stream can be stored in a way compatible with Netatalk 3 by setting
60 fruit:resource = file
61 and
62 fruit:metadata = netatalk\&.
63 .PP
64 OS X maps NTFS illegal characters to the Unicode private range in SMB requests\&. By setting
65 fruit:encoding = native, all mapped characters are converted to native ASCII characters\&.
66 .PP
67 Finally, share access modes are optionally checked against Netatalk AFP sharing modes by setting
68 fruit:locking = netatalk\&.
69 .PP
70 This module is not stackable other than described in this manpage\&.
71 .SH "GLOBAL OPTIONS"
72 .PP
73 The following options must be set in the global smb\&.conf section and won\*(Aqt take effect when set per share\&.
74 .PP
75 fruit:aapl = yes | no
76 .RS 4
77 A
78 \fIglobal\fR
79 option whether to enable Apple\*(Aqs SMB2+ extension codenamed AAPL\&. Default
80 \fIyes\fR\&. This extension enhances several deficiencies when connecting from Macs:
81 .RS
82 .sp
83 .RS 4
84 .ie n \{\
85 \h'-04'\(bu\h'+03'\c
86 .\}
87 .el \{\
88 .sp -1
89 .IP \(bu 2.3
90 .\}
91 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\&.
92 .RE
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04'\(bu\h'+03'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP \(bu 2.3
101 .\}
102 The ability to query and modify the UNIX mode of directory entries\&.
103 .RE
104 .sp
105 .RE
106 There\*(Aqs a set of per share options that come into play when
107 \fIfruit:aapl\fR
108 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:
109 .RS
110 .sp
111 .RS 4
112 .ie n \{\
113 \h'-04'\(bu\h'+03'\c
114 .\}
115 .el \{\
116 .sp -1
117 .IP \(bu 2.3
118 .\}
119 readdir_attr:aapl_rsize = yes | no
120 .RE
121 .sp
122 .RS 4
123 .ie n \{\
124 \h'-04'\(bu\h'+03'\c
125 .\}
126 .el \{\
127 .sp -1
128 .IP \(bu 2.3
129 .\}
130 readdir_attr:aapl_finder_info = yes | no
131 .RE
132 .sp
133 .RS 4
134 .ie n \{\
135 \h'-04'\(bu\h'+03'\c
136 .\}
137 .el \{\
138 .sp -1
139 .IP \(bu 2.3
140 .\}
141 readdir_attr:aapl_max_access = yes | no
142 .RE
143 .sp
144 .RE
145 See below for a description of these options\&.
146 .RE
147 .PP
148 fruit:nfs_aces = yes | no
149 .RS 4
150 A
151 \fIglobal\fR
152 option whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled, default
153 \fIyes\fR\&.
154 .RE
155 .PP
156 fruit:copyfile = yes | no
157 .RS 4
158 A
159 \fIglobal\fR
160 option whether to enable OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata\&.
161 .sp
162 WARNING: the copyfile request is blocking the client while the server does the copy\&.
163 .sp
164 The default is
165 \fIno\fR\&.
166 .RE
167 .PP
168 fruit:model = MacSamba
169 .RS 4
170 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\&.
171 .sp
172 The default is
173 \fIMacSamba\fR\&.
174 .RE
175 .SH "OPTIONS"
176 .PP
177 The following options can be set either in the global smb\&.conf section or per share\&.
178 .PP
179 fruit:resource = [ file | xattr | stream ]
180 .RS 4
181 Controls where the OS X resource fork is stored\&.
182 .sp
183 Due to a spelling bug in all Samba versions older than 4\&.6\&.0, this option can also be given as
184 \fIfruit:ressource\fR, ie with two s\&.
185 .sp
186 Settings:
187 .RS
188 .sp
189 .RS 4
190 .ie n \{\
191 \h'-04'\(bu\h'+03'\c
192 .\}
193 .el \{\
194 .sp -1
195 .IP \(bu 2.3
196 .\}
197 file (default)
198 \- use a \&._ AppleDouble file compatible with OS X and Netatalk
199 .RE
200 .sp
201 .RS 4
202 .ie n \{\
203 \h'-04'\(bu\h'+03'\c
204 .\}
205 .el \{\
206 .sp -1
207 .IP \(bu 2.3
208 .\}
209 xattr
210 \- 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
211 .RE
212 .sp
213 .RS 4
214 .ie n \{\
215 \h'-04'\(bu\h'+03'\c
216 .\}
217 .el \{\
218 .sp -1
219 .IP \(bu 2.3
220 .\}
221 stream (experimental)
222 \- pass the stream on to the next module in the VFS stack\&.
223 \fIWarning: \fR
224 this option should not be used with the
225 \fIstreams_xattr\fR
226 module due to the extended attributes size limitations of most filesystems\&.
227 .RE
228 .sp
229 .RE
230 .RE
231 .PP
232 fruit:time machine = [ yes | no ]
233 .RS 4
234 Controls if Time Machine support via the FULLSYNC volume capability is advertised to clients\&.
235 .RS
236 .sp
237 .RS 4
238 .ie n \{\
239 \h'-04'\(bu\h'+03'\c
240 .\}
241 .el \{\
242 .sp -1
243 .IP \(bu 2.3
244 .\}
245 yes
246 \- Enables Time Machine support for this share\&. Also registers the share with mDNS in case Samba is built with mDNS support\&.
247 .RE
248 .sp
249 .RS 4
250 .ie n \{\
251 \h'-04'\(bu\h'+03'\c
252 .\}
253 .el \{\
254 .sp -1
255 .IP \(bu 2.3
256 .\}
257 no (default)
258 Disables advertising Time Machine support\&.
259 .RE
260 .sp
261 .RE
262 This option enforces the following settings per share (or for all shares if enabled globally):
263 .RS
264 .sp
265 .RS 4
266 .ie n \{\
267 \h'-04'\(bu\h'+03'\c
268 .\}
269 .el \{\
270 .sp -1
271 .IP \(bu 2.3
272 .\}
273 durable handles = yes
274 .RE
275 .sp
276 .RS 4
277 .ie n \{\
278 \h'-04'\(bu\h'+03'\c
279 .\}
280 .el \{\
281 .sp -1
282 .IP \(bu 2.3
283 .\}
284 kernel oplocks = no
285 .RE
286 .sp
287 .RS 4
288 .ie n \{\
289 \h'-04'\(bu\h'+03'\c
290 .\}
291 .el \{\
292 .sp -1
293 .IP \(bu 2.3
294 .\}
295 kernel share modes = no
296 .RE
297 .sp
298 .RS 4
299 .ie n \{\
300 \h'-04'\(bu\h'+03'\c
301 .\}
302 .el \{\
303 .sp -1
304 .IP \(bu 2.3
305 .\}
306 posix locking = no
307 .RE
308 .sp
309 .RE
310 .RE
311 .PP
312 fruit:time machine max size = SIZE [K|M|G|T|P]
313 .RS 4
314 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\&.
315 .sp
316 \fIIMPORTANT\fR: This is an approximated calculation that only takes into account the contents of Time Machine sparsebundle images\&. Therefore you
317 \fIMUST NOT\fR
318 use this volume to store other content when using this option, because it would NOT be accounted\&.
319 .sp
320 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\&.
321 .RE
322 .PP
323 fruit:metadata = [ stream | netatalk ]
324 .RS 4
325 Controls where the OS X metadata stream is stored:
326 .RS
327 .sp
328 .RS 4
329 .ie n \{\
330 \h'-04'\(bu\h'+03'\c
331 .\}
332 .el \{\
333 .sp -1
334 .IP \(bu 2.3
335 .\}
336 netatalk (default)
337 \- use Netatalk compatible xattr
338 .RE
339 .sp
340 .RS 4
341 .ie n \{\
342 \h'-04'\(bu\h'+03'\c
343 .\}
344 .el \{\
345 .sp -1
346 .IP \(bu 2.3
347 .\}
348 stream
349 \- pass the stream on to the next module in the VFS stack
350 .RE
351 .sp
352 .RE
353 .RE
354 .PP
355 fruit:locking = [ netatalk | none ]
356 .RS 4
357
358 .RS
359 .sp
360 .RS 4
361 .ie n \{\
362 \h'-04'\(bu\h'+03'\c
363 .\}
364 .el \{\
365 .sp -1
366 .IP \(bu 2.3
367 .\}
368 none (default)
369 \- no cross protocol locking
370 .RE
371 .sp
372 .RS 4
373 .ie n \{\
374 \h'-04'\(bu\h'+03'\c
375 .\}
376 .el \{\
377 .sp -1
378 .IP \(bu 2.3
379 .\}
380 netatalk
381 \- use cross protocol locking with Netatalk
382 .RE
383 .sp
384 .RE
385 .RE
386 .PP
387 fruit:encoding = [ native | private ]
388 .RS 4
389 Controls how the set of illegal NTFS ASCII character, commonly used by OS X clients, are stored in the filesystem\&.
390 .sp
391 \fIImportant:\fR
392 this is known to not fully work with
393 \fIfruit:metadata=stream\fR
394 or
395 \fIfruit:resource=stream\fR\&.
396 .RS
397 .sp
398 .RS 4
399 .ie n \{\
400 \h'-04'\(bu\h'+03'\c
401 .\}
402 .el \{\
403 .sp -1
404 .IP \(bu 2.3
405 .\}
406 private (default)
407 \- store characters as encoded by the OS X client: mapped to the Unicode private range
408 .RE
409 .sp
410 .RS 4
411 .ie n \{\
412 \h'-04'\(bu\h'+03'\c
413 .\}
414 .el \{\
415 .sp -1
416 .IP \(bu 2.3
417 .\}
418 native
419 \- store characters with their native ASCII value\&.
420 \fIImportant\fR: this option requires the use of
421 \fIvfs_catia\fR
422 in the VFS module stack as shown in the examples section\&.
423 .RE
424 .sp
425 .RE
426 .RE
427 .PP
428 fruit:veto_appledouble = yes | no
429 .RS 4
430 \fINote:\fR
431 this option only applies when
432 \fIfruit:resource\fR
433 is set to
434 \fIfile\fR
435 (the default)\&.
436 .sp
437 When
438 \fIfruit:resource\fR
439 is set to
440 \fIfile\fR, vfs_fruit may create \&._ AppleDouble files\&. This options controls whether these \&._ AppleDouble files are vetoed which prevents the client from accessing them\&.
441 .sp
442 Vetoing \&._ files may break some applications, e\&.g\&. extracting Mac ZIP archives from Mac clients fails, because they contain \&._ files\&.
443 rsync
444 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\&.
445 .sp
446 Setting this option to false will fix this, but the abstraction leak of exposing the internally created \&._ files may have other unknown side effects\&.
447 .sp
448 The default is
449 \fIyes\fR\&.
450 .RE
451 .PP
452 readdir_attr:aapl_rsize = yes | no
453 .RS 4
454 Return resource fork size in SMB2 FIND responses\&.
455 .sp
456 The default is
457 \fIyes\fR\&.
458 .RE
459 .PP
460 readdir_attr:aapl_finder_info = yes | no
461 .RS 4
462 Return FinderInfo in SMB2 FIND responses\&.
463 .sp
464 The default is
465 \fIyes\fR\&.
466 .RE
467 .PP
468 readdir_attr:aapl_max_access = yes | no
469 .RS 4
470 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\&.
471 .sp
472 The default is
473 \fIyes\fR\&.
474 .RE
475 .PP
476 fruit:wipe_intentionally_left_blank_rfork = yes | no
477 .RS 4
478 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
479 \(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\&.
480 .sp
481 The default is
482 \fIno\fR\&.
483 .RE
484 .PP
485 fruit:delete_empty_adfiles = yes | no
486 .RS 4
487 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\&.
488 .sp
489 The default is
490 \fIno\fR\&.
491 .RE
492 .PP
493 fruit:zero_file_id = yes | no
494 .RS 4
495 Whether to return zero to queries of on\-disk file identifier if the client has negotiated AAPL\&.
496 .sp
497 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\&.
498 .sp
499 The default is
500 \fIyes\fR\&.
501 .RE
502 .PP
503 fruit:convert_adouble = yes | no
504 .RS 4
505 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\&.
506 .sp
507 The default is
508 \fIyes\fR\&.
509 .RE
510 .PP
511 fruit:validate_afpinfo = yes | no
512 .RS 4
513 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\*(Aqs 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
514 \fIno\fR\&.
515 .sp
516 The default is
517 \fIyes\fR\&.
518 .RE
519 .PP
520 fruit:posix_opens = yes | no
521 .RS 4
522 When
523 \fIfruit:posix_opens\fR
524 is set to
525 \fIyes\fR, 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\&.
526 .sp
527 The default is
528 \fIyes\fR\&.
529 .RE
530 .PP
531 fruit:ignore_zero_aces = yes | no
532 .RS 4
533 When
534 \fIfruit:ignore_zero_aces\fR
535 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\&.
536 .sp
537 This problematic behaviour has been reported for latest macOS versions and this new option allows to work around it\&.
538 .sp
539 The default is
540 \fIyes\fR\&.
541 .RE
542 .SH "EXAMPLES"
543 .sp
544 .if n \{\
545 .RS 4
546 .\}
547 .nf
548 \fI[share]\fR
549 \m[blue]\fBvfs objects = catia fruit streams_xattr\fR\m[]
550 \m[blue]\fBfruit:resource = file\fR\m[]
551 \m[blue]\fBfruit:metadata = netatalk\fR\m[]
552 \m[blue]\fBfruit:locking = netatalk\fR\m[]
553 \m[blue]\fBfruit:encoding = native\fR\m[]
554 .fi
555 .if n \{\
556 .RE
557 .\}
558 .SH "AUTHOR"
559 .PP
560 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\&.