Fix MacOS Finder problems with Samba file shares

Aug 3, 2024

tl;dr: The changes below fix bizarre problems that MacOS Finder has while working with large Samba file shares.

Using MacOS’s Finder to work with large file share directories on my FreeBSD Samba server was sometimes giving me very strange, erratic behavior. It felt like the server had amnesia or was having hallucinations.

Symptoms included:

Directory contents would take a very long time to load.
Directory contents would disappear after browsing between sibling folders.
Directories would show the contents of different sibling folders.

The problem was really annoying and took me quite a while to figure out.

At first, I thought it was an issue with Finder. The internet is full of people’s complaints about Finder sure, but I spend a lot of time in Finder and want to try and fix the problem there if possible. I did try using third-party file managers like Commander One and Marta, but even those programs weren’t totally immune to the issues either. That indicated the issue must be with something at a deeper system level. But, was it an issue with the server, the client, or a combination of problems on both sides?

Since I built the file server myself, I assumed it must be a problem I inadvertently caused. Perhaps some setting I had misconfigured, or some configuration value I had overlooked.

These issues didn’t happen on non-SMB protocols (FTP and SSH were working), so I figured it was an issue with Samba. But, non-MacOS clients didn’t have connection issues (Windows, Linux, and FreeBSD clients were working).

Some articles online suggested that Samba itself was to blame, or that MacOS’s implementation of the Samba client was buggy and hopelessly beyond repair. I even considered switching away from Samba to some other protocol, but that wouldn’t be ideal.

After doing a lot of reading and testing, I learned that Finder rather aggressively caches directory listings, and that cache system can be unreliable with large fileshares over Samba. And I also learned that out-of-the-box Samba configurations need to be tweaked slightly to improve connections for MacOS clients.

The fixes below were scoured from many places on the web, including Reddit posts, blog posts, Github repos, and a deep dive of the Samba configuration documentation. It’s taken me a few months to test out various settings combinations, and now things are working properly.

I’ve been working with these new settings for more than two weeks and have not experienced any further issues. Feels like the right time to document and publish the fix!

Server changes

On the server, make the following changes to smb.conf:

[global]

# Enforce a minimum of Samba v2 (Vista / Server 2008) for client connections
min protocol = SMB2
server min protocol = SMB2

# Improve compatibility with Macs
vfs objects = catia fruit streams_xattr
fruit:aapl = yes
fruit:nfs_aces = no
fruit:zero_file_id = yes
fruit:metadata = stream
fruit:encoding = native
spotlight backend = tracker

readdir_attr:aapl_rsize = no
readdir_attr:aapl_finder_info = no
readdir_attr:aapl_max_access = no

fruit:model = MacSamba
fruit:posix_rename = yes
fruit:veto_appledouble = no
fruit:wipe_intentionally_left_blank_rfork = yes
fruit:delete_empty_adfiles = yes

# (OPTIONAL) Don't allow MacOS clients to write .DS_Store files to server shares
veto files = /.snap/.sujournal/._.DS_Store/.DS_Store/.Trashes/.TemporaryItems/
delete veto files = yes

Spotlight searching of Samba shares is disabled by default, but you can add this line to each of your Samba share definitions in smb.conf to be absolutely sure:

[yourshare]
spotlight = no

Client changes

On the MacOS client computers, create /etc/nsmb.conf:

[default]

# Disable SMB v1
protocol_vers_map=6

# Disable NetBIOS
port445=no_netbios

# Use NTFS streams if supported
streams=yes

# Disable directory caching
dir_cache_max_cnt=0
dir_cache_max=0
dir_cache_off=yes

# Disable packet signing
signing_required=no

# Disable multi-channel connections and prioritize the wired ethernet connection
mc_prefer_wired=yes
mc_on=no

# Disable SMB session signing
validate_neg_off=yes

Applying the changes

Restart the Samba service on the server.
Restart each client computer.

When you reconnect to the server shares on your machines, these issues shouldn’t occur anymore.