This document provides a detailed explanation of common Samba configuration syntax found in /etc/samba/smb.conf.
It is intended to help administrators understand what each directive does, why it is used, and when it is appropriate.
Table of Contents
Example Configuration
[global]
workgroup = WORKGROUP
server string = Samba File Server
netbios name = FILESERVER
security = user
map to guest = bad user
encrypt passwords = yes
passdb backend = tdbsam
interfaces = lo eth0
bind interfaces only = yes
log file = /var/log/samba/log.%m
max log size = 1000
socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192
use sendfile = yes
[Public]
path = /srv/samba/public
browseable = yes
writable = yes
guest ok = yes
create mask = 0664
directory mask = 0775
[Private]
path = /srv/samba/private
browseable = yes
read only = no
valid users = @staff
write list = @staff
create mask = 0660
directory mask = 0770
force group = staff
[homes]
browseable = no
read only = no
1. Global Settings
The [global] section defines server-wide behavior and security policies.
- a. Server Identity
| Syntax | Description |
|---|---|
| workgroup = WORKGROUP |
Defines the Windows workgroup name. Default for most Windows networks is WORKGROUP. |
| server string = Samba File Server |
Human-readable server description shown in network browsers. |
| netbios name = FILESERVER | NetBIOS hostname visible in Windows Explorer |
- b. Security Settings
| Syntax | Description |
|---|---|
security = user |
Standard authentication mode. Clients must authenticate using a Samba username and password. |
map to guest = bad user |
If a username does not exist, the connection is mapped to a guest account. |
encrypt passwords = yes |
Required for modern Windows versions (Windows 7–11). |
passdb backend = tdbsam |
Stores Samba user credentials in a local TDB database (/var/lib/samba/passdb.tdb). |
- c. Networking & Interface Binding
| Syntax | Description |
|---|---|
interfaces = lo eth0 |
Limits Samba to listen only on specific network interfaces. |
bind interfaces only = yes |
Prevents Samba from listening on any other interfaces (improves security). |
- d. Logging Configuration
| Syntax | Description |
|---|---|
log file = /var/log/samba/log.%m |
Creates a separate log file per client (%m = client hostname). |
max log size = 1000 |
Limits log file size to 1000 KB per client. |
- e. Performance Optimazitation
| Syntax | Description |
|---|---|
socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192 |
Optimizes TCP performance and reduces latency. |
use sendfile = yes |
Enables zero-copy transfers for better performance when serving large files (e.g. video, ISO). |
Note: Modern Samba versions may ignore some socket options, but they are still commonly documented.
2. Share Settings (Per Folder)
Each share defines access rules for a specific directory.
- a. [Public] – Public Share Example
[Public]
path = /srv/samba/public
browseable = yes
writable = yes
guest ok = yes
create mask = 0664
directory mask = 0775
Explanation
path = /srv/samba/public |
Physical directory on the server. |
|---|---|
browseable = yes |
Share is visible in network browsing. |
writable = yes |
Clients are allowed to write files. |
guest ok = yes |
Allows access without authentication. |
create mask = 0664 |
Default permission for new files. |
directory mask = 0775 |
Default permission for new directories. |
Public shares should be used only in trusted networks.
- b.[Private] - User & Group Restricted Share
| Syntax | Function |
|---|---|
valid users = @staff |
Only users in the staff group can access the share. |
write list = @staff |
Only the staff group is allowed write access. |
force group = staff |
Files created in this share will always belong to group staff. |
create mask = 0660 |
New files: rw-rw----. |
directory mask = 0770 |
New directories: rwxrwx---. |
3. Special Share: [homes]
[homes]
browseable = no
read only = no
Function
- Automatically creates a personal share for each authenticated user
- Maps directly to
/home/usernameExplanation
| Syntax | Function |
|---|---|
browseable = no |
Hides home directories from network browsing. |
read only = no |
Allows users to write to their own home directory. |
4. VFS Modules (Optional)
to enable a Recycle Bin (Trash) feature:
vfs objects = recycle
recycle:repository = .recycle
recycle:keeptree = yes
recycle:versions = yes
What It Does
- Deleted files are moved to
.recycleinstead of being removed permanently - Preserves directory structure
- Keeps multiple versions of deleted files
5. Variables (Macros)
Macros allow dynamic and automated configurations.
| Macro | Meaning |
|---|---|
%U |
Authenticated username |
%G |
Primary group |
%H |
User home directory |
%m |
Client hostname |
%I |
Client IP address |
%N |
Server NetBIOS name |
| Example Usage |
log file = /var/log/samba/%U.log
Creates one log file per user.
6. Important Samba Commands
| Command | Description |
|---|---|
testparm |
Validates Samba configuration syntax. |
systemctl restart smbd |
Restarts the Samba service. |
smbpasswd -a username |
Adds a Samba user. |
smbclient -L localhost -U user |
Lists available shares for testing. |
Conclusion
Understanding Samba syntax is essential for building a secure, stable, and maintainable file server. By properly configuring global settings, share permissions, and user access, Samba can scale from home labs to enterprise environments.