LFCE 69 🐧 Samba — Shares and Permissions - KandZ

⏱️ Estimated read: 13 min | |

Samba permissions are enforced at two layers that must both allow an operation. The first layer is the Samba configuration in smb.conf: the valid users, write list, and read only parameters determine who can connect to the share and what they can do. The second layer is the Linux filesystem permissions on the actual directory and files: the UID and GID that Samba maps the client to must have the corresponding read, write, or execute permission. When these two layers disagree, the client receives a permission-denied error even though one layer appears to grant access .

The previous chapter configured a basic Samba share with a guest-accessible directory. This chapter covers the options that control access for authenticated users: the valid users parameter that restricts who can connect, the write list parameter that grants write access to a subset of users on an otherwise read-only share, the create mask and directory mask parameters that control the permissions of new files and directories, and the force group parameter that ensures all files in a share belong to the same group. It also covers the Linux-side setup that must accompany the Samba-side configuration.

Key point: Both the Samba layer and the Linux filesystem layer must permit the operation. A share with read only = no and a directory owned by root with mode 755 is still read-only for a non-root Samba user, because the Linux permissions deny write access . The valid users parameter restricts who can authenticate to the share; the write list parameter overrides the read only = yes setting for specific users or groups. The force group parameter maps all file operations in the share to a specific group, which simplifies permission management when multiple users need to collaborate on the same files .

Why Samba permissions require both layers

The Samba-layer problem.

The valid users parameter restricts which users or groups can connect to the share. A user who is not in the list cannot authenticate, regardless of the Linux permissions. The write list parameter grants write access to specific users or groups even when the share is configured as read only = yes. The read only parameter sets the default write behavior for users who are not in the write list . These parameters are evaluated in the Samba process before the Linux filesystem is accessed.

The Linux-layer problem.

Once Samba has authenticated the user and determined that the share allows the operation, it performs the file operation as the Linux UID and GID that the user is mapped to. The Linux permissions on the directory and files determine whether the operation succeeds. A directory with mode 755 owned by root does not allow a non-root user to create files, even if the Samba share is configured with read only = no . The two layers are independent, and the most restrictive one wins.

The group-mapping problem.

When multiple users need to collaborate on the same files, the files must be owned by a group that all the users belong to. The force group parameter in the share configuration maps all file operations to a specific group, regardless of the primary group of the user who created the file. The create mask and directory mask parameters set the maximum permissions for new files and directories, and the setgid bit on the directory ensures that new files inherit the group .

a. The valid users and write list parameters

The valid users parameter restricts who can connect to the share. The write list parameter grants write access to specific users or groups on a share that is otherwise read-only.

# /etc/samba/smb.conf
[projects]
    comment = Development Projects
    path = /srv/samba/projects

    # Only members of the devteam group can connect
    valid users = @devteam

    # All devteam members have read/write access
    writable = yes

    create mask = 0660
    directory mask = 0770
    force group = devteam

The valid users = @devteam parameter restricts the share to members of the devteam Linux group. The @ prefix indicates a group name. The writable = yes parameter makes the share writable for the valid users. The create mask = 0660 parameter sets new files to be readable and writable by the owner and group, and inaccessible to others. The directory mask = 0770 parameter does the same for new directories. The force group = devteam parameter ensures that all files created in the share belong to the devteam group, even if the user’s primary group is different .

For a share where most users have read access and a subset has write access, the write list parameter is used.

[reports]
    comment = Shared Reports
    path = /srv/samba/reports

    # All staff can connect
    valid users = @staff

    # The share is read-only by default
    read only = yes

    # Managers can write despite the read-only setting
    write list = @managers

    create mask = 0664
    directory mask = 0775
    force group = staff

The read only = yes parameter makes the share read-only for everyone in the valid users list. The write list = @managers parameter overrides the read-only setting for the managers group. The create mask = 0664 parameter sets new files to be readable by everyone in the group and writable by the owner and group .

b. The create mask, directory mask, and force group parameters

The mask parameters control the permissions of new files and directories created through the share. The force group parameter controls the group ownership.

[shared]
    comment = Shared Directory
    path = /srv/samba/shared

    valid users = @samba
    read only = no

    # New files: owner rw, group rw, others none
    create mask = 0660

    # New directories: owner rwx, group rwx, others none
    directory mask = 0770

    # All files belong to the samba group
    force group = samba

The create mask = 0660 parameter sets the maximum permissions for new files. The actual permissions are the mask ANDed with the permissions that the client requested, and then modified by the force create mode parameter if it is set. The directory mask = 0770 parameter does the same for new directories. The force group = samba parameter sets the group ownership of every file and directory created in the share to samba .

The Linux directory must be set up to match the Samba configuration. The directory should be owned by the group that the force group parameter specifies, and the setgid bit should be set so that new files inherit the group.

# Create the group and directory
sudo groupadd samba
sudo mkdir -p /srv/samba/shared

# Set ownership to root:samba
sudo chown root:samba /srv/samba/shared

# Set permissions: owner rwx, group rwx, others none
# The setgid bit (2) ensures new files inherit the samba group
sudo chmod 2770 /srv/samba/shared

# Add users to the group
sudo usermod -aG samba alice
sudo usermod -aG samba bob

The chmod 2770 parameter sets the setgid bit on the directory, which causes new files and subdirectories to inherit the samba group. The usermod -aG samba command adds the users to the group. The users must log out and log back in for the group membership to take effect .

c. Validating and testing the permissions

The testparm command validates the configuration, and the smbclient command tests the share from a client.

# Validate the configuration
sudo testparm

# Restart Samba
sudo systemctl restart smbd

# Test the share as a user
smbclient //localhost/projects -U alice
# Enter alice's SMB password
# smb: \> ls
# smb: \> put /etc/hostname test.txt

The smbclient command connects to the share as the specified user. The ls command lists the files, and the put command uploads a file. If the Linux permissions or the Samba configuration deny write access, the put command fails with an access-denied error .

The getfacl command shows the ACLs on the directory and files, which is useful for diagnosing permission issues.

# Check the directory permissions
ls -ldn /srv/samba/projects
# Output: drwxrws--- 2 root devteam ...

# Check the ACLs
getfacl /srv/samba/projects

The ls -ldn command shows the numeric UID and GID, which is useful when the names are not resolved correctly. The getfacl command shows the full ACL, including the setgid bit and any extended permissions.

Complete Example Session

# ============================================
# PART 1: CREATE THE GROUPS AND DIRECTORY
# ============================================
sudo groupadd devteam
sudo mkdir -p /srv/samba/projects

# ============================================
# PART 2: SET LINUX PERMISSIONS
# ============================================
sudo chown root:devteam /srv/samba/projects
sudo chmod 2770 /srv/samba/projects

# ============================================
# PART 3: ADD USERS TO THE GROUP
# ============================================
sudo useradd -M -s /usr/sbin/nologin alice
sudo useradd -M -s /usr/sbin/nologin bob
sudo usermod -aG devteam alice
sudo usermod -aG devteam bob
sudo smbpasswd -a alice
sudo smbpasswd -a bob

# ============================================
# PART 4: CONFIGURE THE SHARE
# ============================================
sudo tee -a /etc/samba/smb.conf > /dev/null <<'EOF'

[projects]
    comment = Development Projects
    path = /srv/samba/projects
    valid users = @devteam
    read only = no
    create mask = 0660
    directory mask = 0770
    force group = devteam
EOF

# ============================================
# PART 5: VALIDATE AND RESTART
# ============================================
sudo testparm
sudo systemctl restart smbd

# ============================================
# PART 6: TEST AS ALICE
# ============================================
smbclient //localhost/projects -U alice
# smb: \> put /etc/hostname alice-file.txt
# smb: \> ls
# smb: \> quit

# ============================================
# PART 7: CHECK THE FILE OWNERSHIP
# ============================================
ls -ln /srv/samba/projects/alice-file.txt
# Output: -rw-rw---- 1 1001 1002 ...
# The GID is the devteam group, not alice's primary group

# ============================================
# PART 8: TEST AS A NON-MEMBER
# ============================================
smbclient //localhost/projects -U charlie
# Enter charlie's SMB password
# Output: tree connect failed: NT_STATUS_ACCESS_DENIED
# charlie is not in the devteam group

# ============================================
# PART 9: VERIFY THE WRITE LIST
# ============================================
# Add a read-only share with a write list
sudo tee -a /etc/samba/smb.conf > /dev/null <<'EOF'

[reports]
    path = /srv/samba/reports
    valid users = @devteam
    read only = yes
    write list = alice
    force group = devteam
EOF
sudo mkdir -p /srv/samba/reports
sudo chown root:devteam /srv/samba/reports
sudo chmod 2770 /srv/samba/reports
sudo testparm
sudo systemctl restart smbd

# ============================================
# PART 10: CLEAN UP
# ============================================
# Remove the test shares and users if needed

The ten parts demonstrate the permissions configuration: the group creation, the Linux permissions, the user creation, the share configuration, the validation, the client test, the file ownership check, the non-member test, the write-list configuration, and the cleanup. The critical verification is Part 7: the file created by alice is owned by the devteam group, not by alice‘s primary group, which confirms that force group is working.

Quick Reference

Access-Control Parameters

Parameter	Purpose	Example
`valid users`	Who can connect	`@devteam`
`invalid users`	Who is denied	`contractor1`
`read only`	Default write behavior	`yes` or `no`
`write list`	Who can write despite read-only	`@managers`
`hosts allow`	Allowed client IPs	`192.168.1.0/24`
`hosts deny`	Denied client IPs	`ALL`

Permission Parameters

Parameter	Purpose	Example
`create mask`	Max permissions for new files	`0660`
`directory mask`	Max permissions for new directories	`0770`
`force group`	Group ownership for new files	`devteam`
`force user`	User ownership for new files	`nobody`
`inherit permissions`	Inherit from parent directory	`yes`

Linux Setup Commands

Command	Purpose
`chown root:group /path`	Set ownership
`chmod 2770 /path`	Set permissions and setgid
`usermod -aG group user`	Add user to group
`smbpasswd -a user`	Add Samba user

Verification Commands

Command	Purpose
`testparm`	Validate configuration
`smbclient //server/share -U user`	Test the share
`ls -ldn /path`	Check numeric ownership
`getfacl /path`	Check ACLs

Best Practices

✅ Do This:

# Restrict access with valid users
valid users = @devteam                                        # ✅

# Use write list for read-only shares with specific writers
read only = yes
write list = @managers                                        # ✅

# Force the group for collaboration
force group = devteam                                         # ✅

# Set the setgid bit on the directory
chmod 2770 /srv/samba/projects                                # ✅

# Match the mask to the group permissions
create mask = 0660
directory mask = 0770                                         # ✅

# Validate before restarting
testparm                                                      # ✅

❌ Don’t Do This:

# Set read only = no without Linux write permissions
read only = no
# Directory is owned by root with mode 755                    # ❌

# Use valid users without adding users to the Linux group
valid users = @devteam
# Users are not in the devteam group                          # ❌

# Forget the setgid bit
chmod 770 /srv/samba/projects    # New files get the user's primary group # ❌

# Use a mask that denies group write
create mask = 0644    # Group cannot write                   # ❌

# Restart without validation
systemctl restart smbd    # Syntax error prevents start       # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Permission denied despite `read only = no`	Linux permissions deny write	`chown` and `chmod` the directory
User cannot connect	Not in `valid users` or Linux group	Add to group; update `valid users`
New files have wrong group	Setgid bit not set	`chmod 2770` on the directory
Write list ignored	`read only = yes` and user not in list	Add user to `write list`
Mask prevents group access	Mask too restrictive	Use `0660`/`0770`
Service fails to start	Syntax error	`testparm` reports the error

Real-World Examples

1. Group-only share

[projects]
path = /srv/samba/projects
valid users = @devteam
read only = no
create mask = 0660
directory mask = 0770
force group = devteam

2. Read-only with write list

[reports]
path = /srv/samba/reports
valid users = @staff
read only = yes
write list = @managers

3. Public share

[public]
path = /srv/samba/public
guest ok = yes
read only = no

4. Linux directory setup

chown root:devteam /srv/samba/projects
chmod 2770 /srv/samba/projects

5. Add user to group

usermod -aG devteam alice

6. Add Samba user

smbpasswd -a alice

7. Validate configuration

testparm

8. Test the share

smbclient //localhost/projects -U alice

9. Check ownership

ls -ldn /srv/samba/projects

10. Check ACLs

getfacl /srv/samba/projects

Visual

Two-Layer Permission Check

┌──────────────────────────────────────────────────────────────┐
│  BOTH LAYERS MUST ALLOW THE OPERATION                        │
│                                                              │
│  Client request                                              │
│       │                                                      │
│       ▼                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Samba layer                                            │  │
│  │ ├── valid users?                                       │  │
│  │ ├── read only?                                         │  │
│  │ └── write list?                                        │  │
│  └──────────────────────────┬─────────────────────────────┘  │
│                             │ allowed                        │
│                             ▼                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Linux filesystem layer                                 │  │
│  │ ├── UID/GID match?                                     │  │
│  │ ├── owner/group/other permissions?                     │  │
│  │ └── directory write bit?                               │  │
│  └──────────────────────────┬─────────────────────────────┘  │
│                             │ allowed                        │
│                             ▼                                │
│                        File operation                       │
└──────────────────────────────────────────────────────────────┘

Force Group and Setgid

┌──────────────────────────────────────────────────────────────┐
│  FORCE GROUP ENSURES CONSISTENT GROUP OWNERSHIP              │
│                                                              │
│  Without force group:                                        │
│  alice (primary group: alice) creates file → alice:alice     │
│  bob (primary group: bob) creates file → bob:bob             │
│  → group permissions do not work for collaboration           │
│                                                              │
│  With force group = devteam:                                 │
│  alice creates file → alice:devteam                          │
│  bob creates file → bob:devteam                              │
│  → group permissions work for all devteam members            │
│                                                              │
│  The setgid bit on the directory ensures that new            │
│  subdirectories also inherit the devteam group.              │
└──────────────────────────────────────────────────────────────┘

Write List

┌──────────────────────────────────────────────────────────────┐
│  WRITE LIST OVERRIDES READ ONLY FOR SPECIFIC USERS           │
│                                                              │
│  [reports]                                                   │
│  read only = yes                                             │
│  write list = alice, @managers                               │
│                                                              │
│  alice: write allowed (in write list)                        │
│  bob (manager): write allowed (in @managers)                 │
│  charlie (staff): write denied (read only)                   │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Connect restriction	`valid users`
Default write	`read only`
Write override	`write list`
New file permissions	`create mask`
New directory permissions	`directory mask`
Group ownership	`force group`
Linux directory setup	`chown root:group`, `chmod 2770`
Add user to group	`usermod -aG group user`
Add Samba user	`smbpasswd -a user`
Validate	`testparm`
Test	`smbclient //server/share -U user`

Key takeaways:

Samba permissions and Linux permissions are independent layers. Both must allow the operation. A share with read only = no and a directory with mode 755 owned by root is still read-only for a non-root Samba user .
valid users restricts who can connect. The parameter accepts usernames and group names prefixed with @. A user who is not in the list receives an access-denied error before the Linux filesystem is accessed .
write list overrides read only = yes. The parameter grants write access to specific users or groups on a share that is otherwise read-only. It is the correct pattern for a share where most users read and a subset writes .
force group ensures consistent group ownership. The parameter maps all file operations to a specific group, regardless of the user’s primary group. The setgid bit on the directory ensures that new subdirectories also inherit the group .
The mask parameters control new file permissions. The create mask and directory mask parameters set the maximum permissions for new files and directories. A mask that denies group write (e.g., 0644) makes collaboration impossible even with force group .
The Linux directory must match the Samba configuration. The directory should be owned by the group that force group specifies, and the setgid bit should be set. The users must be members of the Linux group that valid users references.

Remember: Samba permissions are a two-layer system. The Samba layer decides who can connect and what they can do. The Linux layer decides whether the operation is allowed on the actual files. The valid users parameter restricts connection, the write list parameter grants write access, the create mask and directory mask parameters control new file permissions, and the force group parameter ensures consistent group ownership. The Linux directory must be set up with the correct group, permissions, and setgid bit. Validate with testparm, restart with systemctl restart smbd, and test with smbclient. A share that appears configured but denies access is usually a mismatch between the two layers.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!