04 — Samba (File Sharing)¶

Samba provides network file shares accessible from Windows, macOS, and iOS using the SMB protocol. It's the engine behind your \\z2mini\files and \\z2mini\backup shares.

Current configuration¶

Three shares are defined:

Share name	Path on Z2	Mode	Access
`files`	`/data/files`	Read-write	gabriel only
`backup`	`/mnt/backup`	Read-only	gabriel only
`music`	`/data/music`	Read-write	gabriel only

Backup is intentionally read-only so backup snapshots can't be accidentally modified or deleted via the share. Music is read-write so the Navidrome library can be populated from the laptop / iOS Files / macOS Finder via drag-and-drop. See 12-navidrome.md for what consumes /data/music.

Installation (fresh setup)¶

sudo apt install -y samba

Verify the service:

sudo systemctl status smbd

Should be "active (running)."

Configuration file¶

Located at /etc/samba/smb.conf. A backup copy of the original is at /etc/samba/smb.conf.backup.

To edit:

sudo nano /etc/samba/smb.conf

After any change, validate the config and restart:

testparm
sudo systemctl restart smbd

testparm parses the config and reports errors before you restart the service — always run it first.

These are appended at the bottom of /etc/samba/smb.conf:

[files]
   comment = Gabriel's Files on Z2 Mini
   path = /data/files
   browseable = yes
   read only = no
   writable = yes
   valid users = gabriel
   force user = gabriel
   force group = gabriel
   create mask = 0664
   directory mask = 0775
   force create mode = 0664
   force directory mode = 0775
   vfs objects = catia fruit streams_xattr
   fruit:metadata = stream
   fruit:model = MacSamba
   fruit:posix_rename = yes
   fruit:veto_appledouble = no
   fruit:wipe_intentionally_left_blank_rfork = yes
   fruit:delete_empty_adouble = yes

[backup]
   comment = Backup snapshots (read-only)
   path = /mnt/backup
   browseable = yes
   read only = yes
   valid users = gabriel
   force user = gabriel
   force group = gabriel
   veto files = /lost+found/

[music]
   comment = Gabriel's Music Library on Z2 Mini
   path = /data/music
   browseable = yes
   read only = no
   writable = yes
   valid users = gabriel
   force user = gabriel
   force group = gabriel
   create mask = 0664
   directory mask = 0775
   force create mode = 0664
   force directory mode = 0775
   vfs objects = catia fruit streams_xattr
   fruit:metadata = stream
   fruit:model = MacSamba
   fruit:posix_rename = yes
   fruit:veto_appledouble = no
   fruit:wipe_intentionally_left_blank_rfork = yes
   fruit:delete_empty_adouble = yes

The [music] share is a verbatim mirror of [files] (same fruit/macOS settings, same gabriel-only access, same writable mode), just pointed at /data/music and labeled differently. Navidrome's container mounts the same path read-only as /music:ro — see 12-navidrome.md.

Key settings explained¶

valid users = gabriel — only this user can authenticate to the share
force user = gabriel — files created via the share are owned by gabriel regardless of who created them
vfs objects = catia fruit streams_xattr + fruit:* — Apple/macOS/iOS compatibility module, required for iOS Files to work properly with read-write. Without these, iOS Files often shows the share as read-only.
veto files = /lost+found/ — hides the ext4 filesystem's lost+found directory from Windows clients

Don't remove the fruit:* settings unless you're sure you no longer use iOS or macOS clients.

Samba authentication¶

Samba has its own user/password database, separate from Linux logins. Each user who needs share access requires both:

A Linux user account
A Samba password (set with smbpasswd)

To set/change the Samba password for gabriel:

sudo smbpasswd gabriel

To add a new user (if you ever do this):

sudo useradd -m newuser           # Create Linux account
sudo smbpasswd -a newuser         # Set Samba password
sudo smbpasswd -e newuser         # Enable Samba account

Common operations¶

Restart Samba (after config changes):

sudo systemctl restart smbd

See who's currently connected:

sudo smbstatus

Shows active connections, which shares are open, locked files, etc.

Test the config without restarting:

testparm

View the parsed config:

testparm -s

Troubleshooting¶

"Permission denied" errors from Windows/iOS:

Verify Samba password is set:
```
sudo pdbedit -L
```
Should list gabriel. If not, run sudo smbpasswd -a gabriel.
Verify Linux file permissions:
```
ls -la /data/files
```
The folder and contents should be owned by gabriel:gabriel.

If permissions are wrong, fix:

sudo chown -R gabriel:gabriel /data/files
sudo chmod -R u+rwX,g+rwX /data/files

iOS shows the share as read-only:

Almost always the fruit:* config block is missing or the service hasn't been restarted after adding it. Verify the share definition matches the config above and run sudo systemctl restart smbd.

Can't connect from any device:

sudo systemctl status smbd
sudo journalctl -u smbd --since "10 minutes ago"

Check that smbd is running and look at recent logs.

Connection works on home Wi-Fi but not when away:

Tailscale issue, not Samba. See 03-tailscale.md.

Files and locations¶

Purpose	Path
Main config	`/etc/samba/smb.conf`
Backup of original config	`/etc/samba/smb.conf.backup`
Samba password database	`/var/lib/samba/private/passdb.tdb` (don't edit directly)
Service logs	`journalctl -u smbd`