Recently, I decided to use a Raspberry Pi as a Time Machine backup server. After it was all set up and scripted, I set out to write a little informational blog post about it.

Only to find that someone else already made a pretty good job of it. And yet someone else, and still someone else. Broadening the search to “samba time machine” found yet more articles.

One thing perplexed me however: all articles copied variants of the smb.conf incantations needed for Time Machine to function, but almost none explained why they were needed. After some manual testing, and some documentation reading, I came to a startling conclusion:

They were all wrong.

No, not really. They all included support for file sharing features, obsolete compatibility features, and sometimes redundant default parameters. And in particular, none of them accounted for the fact that ever since it was possible to use SMB with Time Machine, Mac OS has been using sparse bundles to provide an abstraction over the networked filesystem. More on that later.

The various configuration recommendations I found on the web, and the official documentation pages were collected in the Samba Time Machine configuration survey

At the time of writing, the latest Samba version is 4.22.4. But the latest Raspberry Pi OS is currently based on Debian Bookworm, which packages Samba 4.17. So this is the version I used for testing.

The minimal additonal Samba configuration, in /etc/samba/smb.conf, for a single SMB share named, unimaginatively, “backup”, accessible by the unsurprisingly named “backupuser”, would be this:

[backup]
path = /media/backup
vfs objects = fruit
fruit:time machine = yes
valid users = backupuser
writeable = yes

• path = PATH — Filesystem root of the SMB mount point.
• vfs objects = fruit — Turn on support for Apple’s SMB2+ extension.
• fruit:time machine = yes — Advertise Time Machine support for this volume, and modify some low-level settings.
• valid users = backupuser — Restrict access to backupuser.
• writeable = yes — Grant write access.

The other things you see all over the internet: catia, and streams_xattr, and fruit:aapl = yes, and permission masks… some of them are useful when using Samba as an actual file server in Mac OS, but they do not appear needed when only using Time Machine.

I had more to say before, about sparse bundles: they have very simple requirements for the host filesystem. The file names are all ASCII and unsurprising, there is no extended attributes or forked files. The sparse bundle format provides a virtual disk, whose content is stored in relatively small (around 1GB) files called bands. This virtual disk contains an APFS filesystem, and this filesystem can have weird file names and large extended attributes (I did not mean it to sound corny), but to the SMB server this is all bytes in the band files.

A lot of the advice about using vfs_catia to deal with unusual file names, and vfs_streams_xattr to deal with large amount of extended attributes data, is relevant when using Samba as a file server. But when using Samba a Time Machine server, the only thing which might have a suprising file name is the sparse bundle directory itself, because it contains the name of the Mac used to create it.

One detail I had to test to be sure, was the use of vfs objects = fruit in a global section instead of within mount sections. According to the vfs_fruit man page:

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.

But testing showed that, after modifying smb.conf and running sudo service smbd reload, just retrying a Time Machine backup would detect a change in configuration. Today, SMB capabilities are not cached by Mac OS. So even that bit was not needed, you can put the vfs objects line in the global section, or in service sections.