LFCE 116 🐧 CIFS/SMB Mounts
CIFS/SMB mounts connect a Linux client to a share exported by a Windows server, a Samba server, or a NAS appliance. The protocol is the same one Windows uses for file sharing, and the Linux kernel’s cifs module implements the client side. The userspace helper mount.cifs, part of the cifs-utils package, handles the authentication negotiation and option parsing that the kernel module cannot do alone .
This chapter covers the complete mount workflow: installing the utilities, performing a manual mount with inline credentials, replacing those credentials with a protected file, writing a persistent /etc/fstab entry that does not hang the boot sequence when the server is unreachable, and understanding the options that control ownership, permissions, and protocol version. It also covers the failure modes that produce the most common errors—boot hangs, permission mismatches, and protocol negotiation failures.
Key point: A CIFS mount in /etc/fstab without _netdev and nofail is a boot hang waiting to happen. The network mount options are not optional decorations; they are what prevents an unreachable server from dropping the system to an emergency shell.
Why CIFS mounting has these requirements
The authentication delegation problem. The kernel’s cifs module does not read credential files. It receives the username and password as mount options. The mount.cifs helper is what opens the credentials file, extracts the values, and passes them to the kernel . This is why the credentials= option works even though the kernel ignores it: the helper processes it before the kernel ever sees the mount request. Understanding this split explains why the credentials file must be readable by the user running the mount command, typically root.
The boot ordering problem. /etc/fstab is processed during boot. A CIFS entry that points to an unreachable server will cause the mount attempt to block, and if the entry lacks nofail, the system drops to an emergency shell rather than completing the boot . The _netdev option tells systemd that the mount requires the network, and nofail tells it to continue booting even if the mount fails. Both are mandatory for any CIFS entry that is not explicitly marked noauto.
The identity mapping problem. SMB does not use POSIX UIDs and GIDs. A file on the server is owned by an SMB security identifier, not a Linux user ID. When the share is mounted, the kernel must map those identities to local users. The uid= and gid= options force every file on the mount to appear as owned by a specific local user and group, which is the simplest mapping strategy for shares that do not negotiate CIFS Unix extensions . Without these options, files may appear owned by root or by an unmapped numeric ID, and local users cannot write to them.
The protocol version problem. SMB has gone through three major versions, and the security and performance characteristics differ substantially. SMB1 is deprecated and disabled by default on modern Windows servers. SMB2 and SMB3 are the current standards. If the client and server cannot agree on a dialect, the mount fails with a protocol negotiation error. The vers= option pins the dialect and removes the negotiation uncertainty .
a. Installing the utilities and performing a manual mount
The cifs-utils package provides mount.cifs. On RHEL-family systems, samba-client provides smbclient for listing shares before attempting to mount.
# RHEL / CentOS / Oracle Linux
sudo dnf install -y cifs-utils samba-client
# Debian / Ubuntu
sudo apt install -y cifs-utils smbclientA manual mount with inline credentials is the fastest way to verify that the share is reachable and the credentials are correct. It is not the way to mount a share permanently.
# Create the mount point
sudo mkdir -p /mnt/smb-share
# Mount with inline credentials
sudo mount -t cifs //192.168.1.10/shared /mnt/smb-share \
-o username=smbuser,password=secret,vers=3.0If the mount succeeds, df -h /mnt/smb-share shows the share, and ls /mnt/smb-share lists its contents. If it fails, the error message indicates whether the problem is network reachability, authentication, or protocol negotiation.
b. Using a credentials file
Inline passwords appear in shell history, in process listings, and in /etc/fstab if the mount is made persistent. The credentials= option reads the username, password, and optional domain from a file instead.
# Create a root-owned credentials file
sudo install -d -m 700 /etc/samba
sudo tee /etc/samba/credentials-fileserver <<'EOF'
username=smbuser
password=secretpassword
domain=WORKGROUP
EOF
# Restrict permissions: the file contains a cleartext password
sudo chmod 600 /etc/samba/credentials-fileserver
sudo chown root:root /etc/samba/credentials-fileserverThe domain= line is optional for standalone Samba servers and required for Active Directory or Windows workgroup authentication . The chmod 600 is not a suggestion. A world-readable credentials file exposes the share password to every local user, and mount.cifs does not enforce the permission check itself .
# Mount using the credentials file
sudo mount -t cifs //192.168.1.10/shared /mnt/smb-share \
-o credentials=/etc/samba/credentials-fileserver,vers=3.0c. Persistent mounting with /etc/fstab
A persistent entry follows the standard fstab format: the UNC path, the mount point, cifs, the options, and 0 0 for dump and pass. The options string is where the network and identity mapping decisions live.
# Basic persistent entry
//192.168.1.10/shared /mnt/smb-share cifs credentials=/etc/samba/credentials-fileserver,_netdev,nofail 0 0The _netdev option tells systemd that the mount depends on the network. The nofail option ensures that a failed mount does not block the boot . For a mount that should only be attempted when accessed, x-systemd.automount creates an on-demand automount unit instead of mounting at boot, which means a server that is briefly offline does not delay the boot at all .
# Entry with ownership mapping, protocol pinning, and automount
//192.168.1.10/shared /mnt/smb-share cifs credentials=/etc/samba/credentials-fileserver,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,vers=3.0,_netdev,nofail,x-systemd.automount 0 0The uid= and gid= values are numeric IDs from the local system. The file_mode and dir_mode values set the permissions on files and directories as they appear locally, because the SMB server’s ACLs do not map directly to POSIX permission bits .
After editing fstab, run sudo mount -a to test the entry before rebooting. A typo in the options string surfaces at the prompt, not during the next boot.
Complete Example Session
# ============================================
# PART 1: INSTALL THE CIFS UTILITIES
# ============================================
sudo dnf install -y cifs-utils samba-client
# Verify the helper exists
which mount.cifs# ============================================
# PART 2: DISCOVER AVAILABLE SHARES
# ============================================
# List shares on the server (prompts for password)
smbclient -L //192.168.1.10 -U smbuser
# For guest-accessible servers
smbclient -L //192.168.1.10 -N# ============================================
# PART 3: MANUAL MOUNT WITH INLINE CREDENTIALS
# ============================================
sudo mkdir -p /mnt/smb-share
sudo mount -t cifs //192.168.1.10/shared /mnt/smb-share \
-o username=smbuser,password=secret,vers=3.0
# Verify
df -h /mnt/smb-share
ls /mnt/smb-share# ============================================
# PART 4: CREATE A PROTECTED CREDENTIALS FILE
# ============================================
sudo install -d -m 700 /etc/samba
sudo tee /etc/samba/credentials-fileserver <<'EOF'
username=smbuser
password=secretpassword
domain=WORKGROUP
EOF
sudo chmod 600 /etc/samba/credentials-fileserver
sudo chown root:root /etc/samba/credentials-fileserver
# Verify permissions
stat -c '%a %U %n' /etc/samba/credentials-fileserver
# Expected: 600 root /etc/samba/credentials-fileserver# ============================================
# PART 5: MOUNT WITH THE CREDENTIALS FILE
# ============================================
# Unmount the previous mount first
sudo umount /mnt/smb-share
sudo mount -t cifs //192.168.1.10/shared /mnt/smb-share \
-o credentials=/etc/samba/credentials-fileserver,vers=3.0
mount | grep cifs# ============================================
# PART 6: ADD OWNERSHIP AND PERMISSION MAPPING
# ============================================
# Remount with uid, gid, and mode options
sudo umount /mnt/smb-share
sudo mount -t cifs //192.168.1.10/shared /mnt/smb-share \
-o credentials=/etc/samba/credentials-fileserver,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,vers=3.0
# Files now appear owned by UID 1000
ls -ln /mnt/smb-share# ============================================
# PART 7: WRITE THE FSTAB ENTRY
# ============================================
# Back up fstab before editing
sudo cp /etc/fstab /etc/fstab.bak
# Append the entry
echo '//192.168.1.10/shared /mnt/smb-share cifs credentials=/etc/samba/credentials-fileserver,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,vers=3.0,_netdev,nofail 0 0' | sudo tee -a /etc/fstab# ============================================
# PART 8: TEST THE FSTAB ENTRY
# ============================================
# Unmount the manual mount
sudo umount /mnt/smb-share
# Test the fstab entry without rebooting
sudo mount /mnt/smb-share
# Verify
findmnt /mnt/smb-share
df -h /mnt/smb-share# ============================================
# PART 9: ADD AUTOMOUNT FOR ON-DEMAND ACCESS
# ============================================
# Edit the fstab entry to add x-systemd.automount
# //192.168.1.10/shared /mnt/smb-share cifs credentials=...,_netdev,nofail,x-systemd.automount 0 0
# Reload systemd and test
sudo systemctl daemon-reload
sudo mount -a
# The mount triggers on first access
ls /mnt/smb-share# ============================================
# PART 10: TROUBLESHOOT A FAILED MOUNT
# ============================================
# Verbose mount for debugging
sudo mount -v -t cifs //192.168.1.10/shared /mnt/smb-share \
-o credentials=/etc/samba/credentials-fileserver,vers=3.0
# Check kernel messages for the specific error
dmesg | tail -20
# Common error: "Host is down" (error 112)
# Cause: server unreachable or private endpoint anomalyThe ten parts covered installation, share discovery, manual mounting, credentials file creation, credential-based mounting, ownership mapping, fstab persistence, testing before reboot, automount configuration, and verbose troubleshooting.
Quick Reference
Required packages
| Distribution | Package | Provides |
|---|---|---|
| RHEL/CentOS | cifs-utils | mount.cifs helper |
| RHEL/CentOS | samba-client | smbclient for share discovery |
| Debian/Ubuntu | cifs-utils | mount.cifs helper |
| Debian/Ubuntu | smbclient | Share discovery |
Essential mount options
| Option | Purpose |
|---|---|
credentials=FILE | Read username/password/domain from file |
vers=3.0 | Pin SMB protocol version (2.0, 2.1, 3.0, 3.1.1) |
uid=N | Map all files to local user ID N |
gid=N | Map all files to local group ID N |
file_mode=MODE | Local file permissions (e.g., 0664) |
dir_mode=MODE | Local directory permissions (e.g., 0775) |
_netdev | Wait for network before mounting |
nofail | Continue boot if mount fails |
x-systemd.automount | Mount on demand, not at boot |
iocharset=utf8 | Correct non-ASCII filename handling |
Credentials file format
| Line | Example | Required |
|---|---|---|
username= | username=smbuser | Yes |
password= | password=secret | Yes |
domain= | domain=WORKGROUP | Optional (required for AD) |
Common errors
| Error | Likely cause | Fix |
|---|---|---|
Host is down (112) | Server unreachable or network issue | Verify network and server availability |
Permission denied | Wrong credentials or ACL | Verify credentials file and share permissions |
cifs filesystem not supported | cifs module not loaded | Install kernel-modules and modprobe cifs |
| Boot hang | Missing _netdev or nofail | Add both options to fstab entry |
Files owned by root | Missing uid/gid options | Add uid= and gid= to mount options |
Best Practices
✅ Do This:
# Store credentials in a 0600 root-owned file
chmod 600 /etc/samba/credentials-fileserver # ✅# Always include _netdev and nofail in fstab
//server/share /mnt cifs credentials=...,_netdev,nofail 0 0 # ✅# Pin the SMB protocol version
vers=3.0 # ✅# Map ownership with uid and gid
uid=1000,gid=1000 # ✅# Test fstab entries with mount -a before rebooting
sudo mount -a # ✅❌ Don’t Do This:
# Put passwords directly in /etc/fstab
//server/share /mnt cifs username=user,password=secret 0 0 # ❌# Omit nofail from a network mount entry
//server/share /mnt cifs credentials=... 0 0 # ❌ (boot hang)# Assume the cifs module is loaded
mount -t cifs //server/share /mnt # ❌ (may fail)# Leave credentials file world-readable
chmod 644 /etc/samba/credentials-fileserver # ❌# Use SMB1 on a modern server
vers=1.0 # ❌ (deprecated, often disabled)Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Boot drops to emergency shell | CIFS fstab entry lacks nofail | Add _netdev,nofail; test with mount -a |
| Files owned by root or unmapped UID | No uid/gid mapping | Add uid= and gid= to mount options |
Host is down error | Server unreachable, firewall, or endpoint issue | Verify network path and server status |
cifs filesystem not supported | cifs kernel module not loaded | Install kernel-modules, run modprobe cifs |
| Authentication fails despite correct password | Missing domain= in credentials file | Add domain=WORKGROUP or the AD domain |
| Mount is slow at boot | Server offline and no automount | Add x-systemd.automount for on-demand mounting |
| File permissions cannot be changed | SMB server ACLs not mapped to POSIX | Use file_mode/dir_mode; accept server-side ACLs |
Real-World Examples
1. Manual mount with inline credentials
sudo mount -t cifs //192.168.1.10/shared /mnt/smb -o username=user,password=pass,vers=3.02. Mount with credentials file
sudo mount -t cifs //192.168.1.10/shared /mnt/smb -o credentials=/etc/samba/creds,vers=3.03. fstab entry with ownership mapping
//192.168.1.10/shared /mnt/smb cifs credentials=/etc/samba/creds,uid=1000,gid=1000,_netdev,nofail 0 04. fstab entry with automount
//192.168.1.10/shared /mnt/smb cifs credentials=/etc/samba/creds,_netdev,nofail,x-systemd.automount 0 05. Credentials file contents
username=smbuser
password=secret
domain=WORKGROUP6. Restrict credentials file permissions
chmod 600 /etc/samba/credentials-fileserver7. List shares on a server
smbclient -L //192.168.1.10 -U smbuser8. Mount read-only
sudo mount -t cifs //server/share /mnt/smb -o credentials=/etc/samba/creds,ro,vers=3.09. Kerberos mount
sudo mount -t cifs //server/share /mnt/smb -o sec=krb5,cruid=$(id -u),vers=3.010. Verbose troubleshooting
sudo mount -v -t cifs //server/share /mnt/smb -o credentials=/etc/samba/creds,vers=3.0Visual
The mount.cifs and kernel split
┌─────────────────────────────────────────────────────────────┐
│ WHO HANDLES WHAT │
│ │
│ mount.cifs (userspace helper) │
│ ├── Opens credentials= file │
│ ├── Extracts username, password, domain │
│ ├── Parses option string │
│ └── Passes values to kernel as mount options │
│ │
│ kernel cifs module │
│ ├── Receives username and password │
│ ├── Negotiates SMB protocol version │
│ ├── Establishes session │
│ └── Maps remote identity to uid/gid │
│ │
│ The kernel never reads the credentials file. │
│ The helper does. That is why credentials= works. │
└─────────────────────────────────────────────────────────────┘fstab boot ordering
┌─────────────────────────────────────────────────────────────┐
│ WITHOUT _netdev AND nofail │
│ │
│ Boot ──► fstab processed ──► CIFS mount attempted │
│ │ │
│ ▼ │
│ Server unreachable │
│ │ │
│ ▼ │
│ Mount blocks │
│ │ │
│ ▼ │
│ EMERGENCY SHELL │
│ │
│ WITH _netdev AND nofail │
│ │
│ Boot ──► network.target ──► CIFS mount attempted │
│ │ │
│ ├── success ──► mount │
│ │ │
│ └── failure ──► skip │
│ (boot continues)│
└─────────────────────────────────────────────────────────────┘Identity mapping
┌─────────────────────────────────────────────────────────────┐
│ SMB IDENTITY TO POSIX MAPPING │
│ │
│ Without uid/gid: │
│ Server ACL: S-1-5-21-... (SID) │
│ Local view: uid=0 (root) or unmapped numeric ID │
│ User cannot write to files │
│ │
│ With uid=1000,gid=1000: │
│ Server ACL: S-1-5-21-... (SID) │
│ Local view: uid=1000, gid=1000 │
│ User can write according to file_mode/dir_mode │
│ │
│ The mapping is forced, not negotiated. │
│ It is the simplest strategy for shares that do not │
│ negotiate CIFS Unix extensions. │
└─────────────────────────────────────────────────────────────┘Protocol version pinning
┌─────────────────────────────────────────────────────────────┐
│ SMB DIALECTS │
│ │
│ vers=1.0 │
│ Deprecated, disabled by default on modern Windows │
│ Do not use unless the server requires it │
│ │
│ vers=2.0 / 2.1 │
│ Older SMB2, supported by most NAS appliances │
│ │
│ vers=3.0 │
│ Encryption support, commonly recommended │
│ │
│ vers=3.1.1 │
│ Newest, strongest encryption │
│ │
│ If omitted, kernel negotiates. Pin it to avoid surprises. │
└─────────────────────────────────────────────────────────────┘Summary
| Item | Value |
|---|---|
| Package (RHEL) | cifs-utils, samba-client |
| Package (Debian) | cifs-utils, smbclient |
| Mount helper | mount.cifs |
| Kernel module | cifs |
| Credentials file option | credentials=/path/to/file |
| Credentials file permissions | 0600, root-owned |
| Protocol pinning | vers=3.0 (or 2.1, 3.1.1) |
| Ownership mapping | uid=N, gid=N |
| Permission mapping | file_mode=0664, dir_mode=0775 |
| Network boot ordering | _netdev |
| Boot failure protection | nofail |
| On-demand mounting | x-systemd.automount |
Key takeaways:
- The credentials file is a security requirement, not a convenience. Passwords in
/etc/fstabare world-readable. A0600root-owned file referenced withcredentials=is the minimum safe configuration. _netdevandnofailare mandatory for fstab entries. Without them, an unreachable server at boot time can drop the system to an emergency shell.x-systemd.automountgoes further by deferring the mount until first access.- The kernel does not read the credentials file.
mount.cifsreads it and passes the values to the kernel. This is why the helper must run as a user who can read the file, typically root. uid=andgid=force identity mapping. Without them, files may appear owned by root or an unmapped ID, and local users cannot write. The mapping is not negotiated; it is imposed by the mount options.- Protocol version should be pinned.
vers=3.0avoids the negotiation uncertainty that can produce cryptic mount failures on servers with multiple dialects enabled. - Test with
mount -abefore rebooting. A typo in the fstab options string surfaces at the prompt withmount -a; it surfaces during boot with a hang or an emergency shell.
Remember: CIFS mounting on Linux is a collaboration between a userspace helper and a kernel module. The helper handles credentials and option parsing; the kernel handles protocol negotiation and identity mapping. The mount options in /etc/fstab are not advisory—they determine whether the system boots, whether local users can write to the share, and whether the server’s ACLs appear as something the client can interpret. The three options that cause the most trouble when omitted are credentials=, _netdev, and nofail. Add uid= and gid= if the share does not negotiate CIFS Unix extensions. Pin vers= if the server supports multiple dialects. And always test the entry with mount -a before trusting it to survive a reboot.
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!