The ultimate guide on using Samba filesharing on the Raspberry Pi with special tuning for Macs

Samba is a great all-rounder for mixed-OS environments if you need to share files between your Raspberry Pi and Windows or macOS computers.

Samba has been in development and use for over 30 years, making it a long-standing and widely used open-source software project. It continues to be actively developed and maintained, playing a crucial role in cross-platform network file sharing.

It’s super convenient for manually adding photos to your digital frame if you are not using a library management tool like e.g., Google Photos.

Although Samba is straightforward to use, the software is so powerful that a casual user is often overwhelmed by the various options and encounters errors that are easy to fix if one knows where to look.

So here is a little cheat sheet on everything that you need to know when using Samba on your Raspberry Pi.

Installing Samba

This is the easiest part, but always bring your system up to date first with

sudo apt update && sudo apt upgrade -y

Then install Samba with

sudo apt install samba -y

Samba User Management

To create a Samba user, you first need to make sure that the user exists as a system user on the Raspberry Pi.

If you use the Raspberry Pi Imager tool, you can define one user that is being installed. For this example, let’s assume that you have a first user, “pi” with the password “pi”.

To turn system user “pi” into a Samba user, assign a password by typing

sudo smbpasswd -a pi

and entering the Samba user password. Please note that this password is not synched automatically with the system user account “pi”.

There are ways to do this, but just be careful not to confuse the two for the moment. And yes, you can use the same password for both system and Samba users.

Here are a few useful commands:

To see which system users exist:

ls -l /home

If you only have “pi” as a system user, you will see this

ls -l /home

total 4

drwx------ 3 pi pi 4096 Dec 25 19:19 pi

To see which Samba users exist:

sudo pdbedit -L

or

sudo pdbedit -L -v

if you want to see additional information.

If you want to disable a Samba user without deleting their system user accounts, type

sudo smbpasswd -d username

To re-enable them:

sudo smbpasswd -e username

Samba Configuration File

Everything that happens in Samba is defined in the Samba configuration file, which is opened with

sudo nano /etc/samba/smb.conf

This file contains many options and plenty of notes, which makes it very unfocused and confusing.

I recommend deleting every line by typing CTRL + K first. Just hold down the keys until all lines are deleted.

Here is what is really important:

The Global Section

This paragraph defines the basic behavior of Samba on your Raspberry Pi.

The recommended minimum lines for a Raspberry Pi used for a digital picture frame are:

[global]
security = user
workgroup = WORKGROUP
server role = standalone server
map to guest = never

This basically means that you have to authenticate as a valid user to access the shared directory.

The Sharing Section

The second paragraph defines the “shared block” or directories and the rights that you grant users.

Each share block starts with the name of the share in square brackets ([]) and includes various configuration options below it. Here’s an example:

Typically, it would look like this:

[pi]
comment = Pi Directories
browseable = yes
path = /home/pi
read only = no
create mask = 0775
directory mask = 0775

This means that you are sharing your entire home folder of your Raspberry Pi and granting full read and write access to every file in this directory.

Since we are talking about a digital picture frame use case and not sensitive FBI material, this is probably what you want.

You can make the directory sharing much more granular by creating several sections.

Specifying “browseable = no“, will give users only access to your one shared directory.

Once you are done, save the config file.

Testing the Samba config file

It is a good idea to test your config file before going live.

Type

testparm

to check for any error messages. With the above settings, it returns

Load smb config files from /etc/samba/smb.conf
Loaded services file OK.
Weak crypto is allowed by GnuTLS (e.g. NTLM as a compatibility fallback)

Server role: ROLE_STANDALONE

Press enter to see a dump of your service definitions
 
# Global parameters
[global]
	security = USER
	server role = standalone server
	idmap config * : backend = tdb


[pi]
	comment = Pi Directories
	create mask = 0775
	directory mask = 0775
	path = /home/pi
	read only = No

“Loaded service file OK.” is what matters.

Restarting the Samba Service

Samba is a system service, and with any other system services in Linux, you have to restart the service to apply any changes. Type

sudo /etc/init.d/smbd restart

If you can’t see your shared network drives on your client’s Mac or PC, it may help to reboot them.

Configuring Samba for the Mac

There are some definitions in the Samba config file that are part of the vfs_fruit module in Samba, which provide enhanced compatibility with Apple SMB clients and AFP (Apple Filing Protocol). It solves especially the sometimes annoying issue with AppleDouble files.

Let’s go through each of these options:

fruit:aapl = yes

• This enables AAPL (Apple Application Layer) protocol extensions, which enhance compatibility and functionality with Apple SMB clients. These extensions provide features like better handling of macOS metadata, improved Spotlight search capabilities, and more.

vfs objects = catia fruit streams_xattr

• vfs objects specifies a list of Virtual File System (VFS) modules to be used with the share.
• catia: This module provides a way to map illegal characters that are not allowed in Windows file names to legal characters. This is useful when Samba serves files to both Windows and macOS clients.
• fruit: This is the main module for Apple SMB compatibility, providing features specific to macOS clients.
• streams_xattr: This module enables support for storing NTFS alternate data streams in extended attributes. This is important for macOS compatibility as it uses alternate data streams to store resource forks and Finder information.

fruit:metadata = stream

• This setting tells Samba to store AppleDouble metadata (used by macOS to store additional file information) as NTFS alternate data streams, which are more compatible with Windows clients and servers.

fruit:metadata = stream

• This setting tells Samba to store AppleDouble metadata (used by macOS to store additional file information) as NTFS alternate data streams, which are more compatible with Windows clients and servers.

fruit:model = RackMac

• This option sets the server’s model name string as reported to Apple clients. “RackMac” simulates a Mac server. It can affect how some software interacts with the server. And it shows a Rack icon!

fruit:posix_rename = yes

• Enables POSIX-compliant behavior of the rename operation in Samba. This can be important for compatibility with macOS file operations, particularly regarding how file renames are handled in the presence of existing files.

fruit:veto_appledouble = no

• Controls how AppleDouble files (used by macOS to store file resource forks and Finder metadata on non-Apple file systems) are handled. Setting this to no means Samba will not hide AppleDouble files. This can be important for certain applications or workflows that rely on access to these files.

fruit:wipe_intentionally_left_blank_rfork = yes

• This setting deals with how Samba handles empty resource forks, which are a type of AppleDouble file. Setting this to yes makes Samba remove empty resource forks, which can help reduce clutter and save space.

fruit:delete_empty_adfiles = yes

• This option, when set to yes, instructs Samba to delete AppleDouble files if they are empty. AppleDouble files are used by macOS to store additional metadata, and removing empty ones can help with the efficiency and cleanliness of the file system.

So, if you have a Mac, it can be quite useful to add this section to the Samba config file in global:

vfs objects = catia fruit streams_xattr
fruit:aapl = yes
fruit:metadata = stream
fruit:model = RackMac
fruit:posix_rename = yes
fruit:veto_appledouble = no
fruit:wipe_intentionally_left_blank_rfork = yes
fruit:delete_empty_adfiles = yes

Don’t forget to restart the Samba service with “sudo /etc/init.d/smbd restart” once you are done.

Conclusion

Samba is a very powerful tool, and combined with user and group management, it allows you to configure your system exactly as you want it.

This tutorial keeps in mind that you want to use Samba for your digital picture frame, and I hope that the commands here will be useful for your homebrewing project.

Thank you for your support and motivation.