The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Show Samba version | smbd --version | View examples |
| Validate configuration | testparm --suppress-prompt /etc/samba/smb.conf | View examples |
| Inspect one share | testparm --suppress-prompt --section-name projects \
/etc/samba/smb.conf | View examples |
| List configured services | testparm --suppress-prompt --show-all-parameters \
/etc/samba/smb.conf | View examples |
| List server shares | smbclient --list=files1.example.net --user=alice | View examples |
| Open an SMB client | smbclient //files1.example.net/projects --user=alice | View examples |
| Connect with Kerberos | smbclient //files1.example.net/projects \
--use-kerberos=required --no-pass | View examples |
| Show active sessions | sudo smbstatus --shares | View examples |
| Show locked files | sudo smbstatus --locks | View examples |
| Reload configuration | sudo smbcontrol all reload-config | View examples |
| Add a Samba password | sudo smbpasswd -a alice | View examples |
| Disable a Samba account | sudo smbpasswd -d alice | View examples |
| Enable a Samba account | sudo smbpasswd -e alice | View examples |
| Read a share ACL | smbcacls //files1.example.net/projects / --user=alice | View examples |
| Read filesystem ACLs | getfacl --absolute-names /srv/samba/projects | View examples |
| Show protocol bounds | testparm --suppress-prompt \
--parameter-name='server min protocol' \
/etc/samba/smb.conf | View examples |
| Show signing policy | testparm --suppress-prompt \
--parameter-name='server signing' /etc/samba/smb.conf | View examples |
| Inspect SMB listeners | ss -ltnp 'sport = :445' | View examples |
| Read smbd logs | journalctl -u smb.service -u smbd.service --since today \
--no-pager | View examples |
| Mount an SMB share | sudo mount -t cifs //files1.example.net/projects \
/mnt/projects -o \
credentials=/root/.smb-projects,vers=3.1.1 | View examples |
Samba maps SMB identities and access checks onto Linux filesystems, so a successful connection can still fail at share, ACL, mode-bit, SELinux, or filesystem boundaries. Treat smb.conf as security policy, reject SMB1 unless a documented legacy exception requires it, never put passwords on command lines, and test changes with a non-administrative account before exposing TCP 445 beyond a trusted network.
Step by step
Detailed examples
Identify role, version, services, and listeners
A standalone file server, domain member, and Active Directory domain controller run different daemon combinations and identity paths. Record the packaged version and security support, active units, configured shares, and bound addresses before editing. Never expose SMB directly to the public Internet.
smbd --version
testparm --suppress-prompt /etc/samba/smb.conf
systemctl status smb.service smbd.service nmb.service winbind.service --no-pager
ss -ltnp 'sport = :445'Validate effective configuration, not merely syntax
testparm catches parsing errors and shows defaults but cannot prove a path exists, storage is writable, identities resolve, ACLs work, or firewall and SELinux policy permit access. Includes and registry shares can alter effective configuration. Build a candidate file, compare its normalized output, and retain a known-good rollback.
testparm --suppress-prompt /etc/samba/smb.conf
testparm --suppress-prompt --section-name projects /etc/samba/smb.conf
# Validate a staged candidate without installing it:
# testparm --suppress-prompt /root/change/smb.conf.candidateTest authentication and authorization as a real user
Administrative credentials can hide broken ordinary-user access. smbclient prompts securely by default; avoid -U user%password because process lists and histories can expose the secret. Kerberos tests require correct DNS, time, SPNs, and tickets. Test list, read, create, rename, and delete only in an approved scratch path.
smbclient --list=files1.example.net --user=alice
klist
smbclient //files1.example.net/projects --use-kerberos=required --no-pass --command='ls'Protect active clients and file locks
Reloading generally does not retrofit every setting onto existing connections, while restart disconnects users. Locks may protect databases and office documents; killing sessions or removing lock state can corrupt data. Inventory sessions, open files, durable handles, and maintenance owners before disruptive work.
sudo smbstatus --shares
sudo smbstatus --locks
sudo smbstatus --processes
# Coordinate with application owners before terminating any session.Reload only after validation and rollback preparation
smbcontrol reload-config asks running daemons to reread configuration, but existing clients can keep old settings until reconnect. Some global changes require restart, which is an outage. Validate the exact installed file, reload, re-run testparm, inspect logs, and test a new client connection before closing the change window.
testparm --suppress-prompt /etc/samba/smb.conf
# sudo smbcontrol all reload-config
# testparm --suppress-prompt /etc/samba/smb.conf
# journalctl -u smb.service -u smbd.service --since '-5 minutes' --no-pagerSeparate Unix accounts from Samba credentials
In local passdb deployments, smbpasswd -a expects an existing Unix account and creates separate SMB credential material. Domain-member deployments normally use directory identities instead. Disable before deletion when preserving ownership history, use strong passwords, and never share accounts or synchronize secrets through scripts.
getent passwd alice
sudo pdbedit --list --verbose alice
# Passdb-only workflow, prompts securely:
# sudo smbpasswd -a alice
# sudo smbpasswd -d aliceReconcile share policy with filesystem and security labels
Access is the intersection of share parameters, authentication, valid users, Windows ACLs, POSIX ACLs and modes, parent-directory traversal, filesystem features, and MAC policy such as SELinux. Broad chmod 777 masks design errors and creates exposure. Decide whether ACLs are managed from Windows or Unix and preserve required xattrs during backup.
testparm --suppress-prompt --section-name projects /etc/samba/smb.conf
namei -l /srv/samba/projects
getfacl --absolute-names /srv/samba/projects
ls -ldZ /srv/samba/projects
smbcacls //files1.example.net/projects / --user=aliceSet protocol and cryptographic policy intentionally
Disable SMB1 unless an isolated, time-bounded legacy exception is unavoidable. Signing protects integrity; encryption protects confidentiality but costs resources and must be negotiated by clients. Guest access, wide hosts allow rules, symlink-following behavior, and writable shares expand risk. Validate current-version defaults rather than copying old smb.conf advice.
testparm --suppress-prompt --parameter-name='server min protocol' /etc/samba/smb.conf
testparm --suppress-prompt --parameter-name='server signing' /etc/samba/smb.conf
testparm --suppress-prompt --parameter-name='smb encrypt' /etc/samba/smb.conf
testparm --suppress-prompt --parameter-name='map to guest' /etc/samba/smb.confMount SMB without placing secrets in fstab
Use a root-owned mode-0600 credentials file or Kerberos rather than inline username and password options. Explicit dialect selection can prevent downgrade but must match the server. CIFS mounts can hang workloads during outages; test ownership mapping, permissions, cache semantics, reconnect behavior, and unmount recovery before production.
# /root/.smb-projects must be root-owned mode 0600 and contain username/domain secrets.
# sudo mount -t cifs //files1.example.net/projects /mnt/projects -o credentials=/root/.smb-projects,vers=3.1.1
# findmnt --target /mnt/projectsDiagnose negotiation, identity, permissions, and transport separately
A refused connection differs from failed dialect negotiation, bad credentials, denied share policy, and backing-filesystem denial. Capture bounded logs and client debug output, but sanitize usernames, addresses, share names, and tokens. Raising global log level indefinitely can expose sensitive metadata and exhaust storage.
testparm --suppress-prompt /etc/samba/smb.conf
ss -ltnp 'sport = :445'
sudo smbstatus --shares
journalctl -u smb.service -u smbd.service --since '-15 minutes' --no-pagerSources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.