samba - Jun 2025 - Documentation/Feature Clarification Request: Server Side Copy and VFS_FRUIT

There are two styles of SSC:
- the "normal" protocol style called copy-chunk, where the copy is 
requested in IO ranges by the client and performed server-side
- the Apple way enabled by fruit:copyfile where the client requests the 
*whole* file to be copied in one request to be performed by the server

The problem with the latter is that for large file the copy takes some 
time and meanwhile the client is blocked waiting for IO to complete. If 
the copy takes longer then the SMB request timeout time (iirc default 
30s) the requests times out and the client will disconnect the connection.

My recommendation is to stay away from fruit:copyfile for these reasons.

Hth!
-slow

-- 
SerNet Samba Team Lead https://sernet.de/
Samba Team Member      https://samba.org/
Samba Support and Dev  https://samba.plus/services/

On 5/20/25 6:17 PM, John T Davis via samba wrote:
> Hello,
> 
> I?m running TrueNAS 24.10.2.2, which uses Samba 4.20.5-truenas. I have a
mixture of Mac, Linux, and Windows SMB clients in my network that  talk to the
TrueNAS server over SMB.
> 
> Apologies in advance for the slightly long-winded setup to my question; I
wanted to explain how I got here.
> 
> I?d like to be able to use Server-Side Copy (SSC)
(https://wiki.samba.org/index.php/Server-Side_Copy) with my Mac clients to mange
files on the TrueNAS server. As noted on that wiki page, ?Note - not enabled for
OS X (Macs) unless server Samba includes vfs_fruit module and fruit:copyfile =
yes in smb.conf.?
> 
> iX Systems (the company that develops and ships TrueNAS) does not add this
flag to their default SMB configuration file. While I was trying to figure out
why, I came across this warning from the current VFS_FRUIT man page in TrueNAS.
> 
> "fruit:copyfile = yes | no
>      A global option whether to enable 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."
> 
> One of the iX devs explained on their forum that this is relevant to SSC
because when a SSC operation is in progress, TrueNAS?s Samba server is acting as
both the client and the server, which makes sense.
>   
> After talking with the iX devs and users on their forum, along with some
members of the MacSysAdmin subreddit, I?ve realized that no one seems to know
exactly what ?blocking the client? means in this context?though I?m guessing it
has something to do with Mac OS?s SMBX implementation not doing SSC the way the
Samba server expects.
> 
> In testing after adding the "fruit:copyfile = yes? line to the SMB
config on TrueNAS, SSC appears to work just fine without any obvious issues on a
Mac?but that doesn?t mean there?s not a problem, just that we don?t understand
how to trigger it.
> 
> I?ve spent about 4-6 hours on various forums and reading documentation, and
am still pretty confused about what?s going on here.
> 
> Request:
> 
> I'm trying to track down the potential performance and other
implications in the real world for having SSC enabled for Mac clients, but I
haven't been able to find anything concrete yet. So, I have a couple of
questions and suggestions for updates to the Samba documentation.
> The warning exists in the man page, but not the official Samba docs (e.g.,
the Wiki).
> Is it possible that the warning no longer applies, but the man page was
never updated?
> If so, could the man page be updated to remove this? This warning existing
is one reason that the feature is not enabled by default in TrueNAS?s Samba
build.
> If the underlying issue that led to the warning still exists, would it be
possible to update the wiki documentation to include the warning and also to
explain a bit more about what ?blocking the client? means in this context?
> For SSC operations, one client is the Samba server itself. Does the entire
Samba server experience an I/O lock when an SSC operation is initiated on a Mac?
Or is it the actual Mac client that can?t do additional SMB operations until the
SSC is completed? Or both?
> More generally, what does this ?blocking? look like to a human user and/or
automated scheduled tasks? What problems can it cause? There?s a big difference
between locking up the entire Samba server itself, and the Mac client that
initiated the SSC request just having to sit there and wait to do more SMB
things until the copy is done.
> 
> Thanks for your help.
> 
> -- -- --
> John T Davis
> johntdavis at johntdavis.info
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature.asc
Type: application/pgp-signature
Size: 840 bytes
Desc: OpenPGP digital signature
URL:
<http://lists.samba.org/pipermail/samba/attachments/20250521/87cd0625/OpenPGP_signature.sig>

Good morning!

Thanks so much for this explanation. That cleared up my confusion; I knew that
something must be getting a problematic lock put on it, but I couldn?t figure
out what. Would it be possible to add something similar to that language to the
wiki? It would clear up a lot of confusion and misinformation that?s floating
around about this, and I think help some people make more informed decisions
about whether they want to turn it on or leave it off.

Also, would you mind if I shared your message on the TrueNAS forums? There?s
several people there who?ve been talking about this who I think would find it
helpful.

(I?ve actually thought about installing Samba via Homebrew to get a more
consistent experience across Linux and Mac OS, but I don?t think it?s worth it
since the Mac OS GUI and programs that touch the Mac OS APIs would still use
SMBX.)

I had a couple of additional questions based on your explanation.

I assume that the ?normal? method does not have this issue because, at least in
part, the chunks are small enough to avoid an IO timeout? Does that mean that
there?s effectively a fixed limit, based on available network and storage
bandwidth, on the size of the file(s) a Mac client can move around via SSC
before the IO timeouts because there?s no way for that operation to complete in
time?

 > The problem with the latter is that for large file the copy takes some
time and meanwhile the client is blocked waiting for IO to complete. If the copy
takes longer then the SMB request timeout time (iirc default 30s) the requests
times out and the client will disconnect the connection.

Is ?the client? in this case the Mac that requested the SSC operation, or the
internal ?client? on the Samba server itself that?s actually doing the operation
server-side? In either case, the risk of the request timing out and data being
left in an unknown/inconsistent state is the same, but I wanted to make sure I
understood.

Given the weakness of the Apple approach, I think your recommendation is
definitely the way to go?even if SSC would be very convenient for some of my use
cases. I can always pop into a Windows VM (or properly configured Linux VM) if I
need to do work that would be benefit from SSC.

This sounds less like a bug in the Apple approach and more like a fundamental
design decision in the SMBX implementation led to a problematic implementation
of SSC. I haven?t looked at the SMBX implementation, but I?m guessing that using
the ?normal? approach would involve a very non-trivial amount of changes.

I suppose the other alternative from the Samba side might be to somehow detect
that a Mac client is trying to do SSC and extend the timeout somehow, but
there?s likely no real reliable way to do that.

-- -- --
John T Davis
johntdavis at johntdavis.info
> On May 21, 2025, at 2:46?AM, Ralph Boehme <slow at samba.org> wrote:
> 
> There are two styles of SSC:
> - the "normal" protocol style called copy-chunk, where the copy
is requested in IO ranges by the client and performed server-side
> - the Apple way enabled by fruit:copyfile where the client requests the
*whole* file to be copied in one request to be performed by the server
> 
> The problem with the latter is that for large file the copy takes some time
and meanwhile the client is blocked waiting for IO to complete. If the copy
takes longer then the SMB request timeout time (iirc default 30s) the requests
times out and the client will disconnect the connection.
> 
> My recommendation is to stay away from fruit:copyfile for these reasons.
> 
> Hth!
> -slow
> 
> -- 
> SerNet Samba Team Lead https://sernet.de/
> Samba Team Member      https://samba.org/
> Samba Support and Dev  https://samba.plus/services/
> 
> On 5/20/25 6:17 PM, John T Davis via samba wrote:
>> Hello,
>> I?m running TrueNAS 24.10.2.2, which uses Samba 4.20.5-truenas. I have
a mixture of Mac, Linux, and Windows SMB clients in my network that  talk to the
TrueNAS server over SMB.
>> Apologies in advance for the slightly long-winded setup to my question;
I wanted to explain how I got here.
>> I?d like to be able to use Server-Side Copy (SSC)
(https://wiki.samba.org/index.php/Server-Side_Copy) with my Mac clients to mange
files on the TrueNAS server. As noted on that wiki page, ?Note - not enabled for
OS X (Macs) unless server Samba includes vfs_fruit module and fruit:copyfile =
yes in smb.conf.?
>> iX Systems (the company that develops and ships TrueNAS) does not add
this flag to their default SMB configuration file. While I was trying to figure
out why, I came across this warning from the current VFS_FRUIT man page in
TrueNAS.
>> "fruit:copyfile = yes | no
>>     A global option whether to enable 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."
>> One of the iX devs explained on their forum that this is relevant to
SSC because when a SSC operation is in progress, TrueNAS?s Samba server is
acting as both the client and the server, which makes sense.
>>  After talking with the iX devs and users on their forum, along with
some members of the MacSysAdmin subreddit, I?ve realized that no one seems to
know exactly what ?blocking the client? means in this context?though I?m
guessing it has something to do with Mac OS?s SMBX implementation not doing SSC
the way the Samba server expects.
>> In testing after adding the "fruit:copyfile = yes? line to the SMB
config on TrueNAS, SSC appears to work just fine without any obvious issues on a
Mac?but that doesn?t mean there?s not a problem, just that we don?t understand
how to trigger it.
>> I?ve spent about 4-6 hours on various forums and reading documentation,
and am still pretty confused about what?s going on here.
>> Request:
>> I'm trying to track down the potential performance and other
implications in the real world for having SSC enabled for Mac clients, but I
haven't been able to find anything concrete yet. So, I have a couple of
questions and suggestions for updates to the Samba documentation.
>> The warning exists in the man page, but not the official Samba docs
(e.g., the Wiki).
>> Is it possible that the warning no longer applies, but the man page was
never updated?
>> If so, could the man page be updated to remove this? This warning
existing is one reason that the feature is not enabled by default in TrueNAS?s
Samba build.
>> If the underlying issue that led to the warning still exists, would it
be possible to update the wiki documentation to include the warning and also to
explain a bit more about what ?blocking the client? means in this context?
>> For SSC operations, one client is the Samba server itself. Does the
entire Samba server experience an I/O lock when an SSC operation is initiated on
a Mac? Or is it the actual Mac client that can?t do additional SMB operations
until the SSC is completed? Or both?
>> More generally, what does this ?blocking? look like to a human user
and/or automated scheduled tasks? What problems can it cause? There?s a big
difference between locking up the entire Samba server itself, and the Mac client
that initiated the SSC request just having to sit there and wait to do more SMB
things until the copy is done.
>> Thanks for your help.
>> -- -- --
>> John T Davis
>> johntdavis at johntdavis.info
>

Hi,

On Wed, 21 May 2025 09:46:34 +0200, Ralph Boehme via samba wrote:
> There are two styles of SSC:
> - the "normal" protocol style called copy-chunk, where the copy
is
> requested in IO ranges by the client and performed server-side
> - the Apple way enabled by fruit:copyfile where the client requests the 
> *whole* file to be copied in one request to be performed by the server
> 
> The problem with the latter is that for large file the copy takes some 
> time and meanwhile the client is blocked waiting for IO to complete. If 
> the copy takes longer then the SMB request timeout time (iirc default 
> 30s) the requests times out and the client will disconnect the connection.
APFS is a copy-on-write filesystem, according to Wikipedia. Assuming it
supports clones / reflinks, a 30s client timeout wouldn't appear
unreasonable.
Similarly for Linux, we could choose to only enable copyfile if the
underlying FS supports FICLONE (i.e. Btrfs, XFS v5 and perhaps ZFS).
Do Apple clients fallback to read/write on copyfile failure?

Cheers, David

On Wed, May 21, 2025 at 1:47?AM Ralph Boehme via samba <
samba at lists.samba.org> wrote:
> There are two styles of SSC:
> - the "normal" protocol style called copy-chunk, where the copy
is
> requested in IO ranges by the client and performed server-side
> - the Apple way enabled by fruit:copyfile where the client requests the
> *whole* file to be copied in one request to be performed by the server
>
>
Ralph, I looked at MacOS client code recently and saw they're using a
compounded CREATE /  FSCTL_SRV_REQUEST_RESUME_KEY / CLOSE to determine
whether copy-chunk is supported on the SMB server during mount_smbfs
operations. Samba is failing with the compounded request with
STATUS_INTERNAL_ERROR because of going async in a compounded request. This
causes MacOS client to flag samba as not supporting server-side copy. A
fairly trivial change to set the defer time for
FSCTL_SRV_REQUEST_RESUME_KEY to zero results in MacOS properly identifying
support for copy-chunk and server-side copy to work. I'll make a merge
request later today.

- Andrew