Learn Samba - User Management & smbpasswd

#Introduction

The [data] share from episode 4 is waiting for the right user. But with Samba, "creating a user" isn't just useradd — because Samba stores its own passwords, separate from /etc/shadow. In episode 5 we dissect user management: syncing system users with Samba passwords, the tdbsam database, smbpasswd, pdbedit, username map, and account flags. This understanding is what separates someone who can merely "share files" from an administrator who truly controls access.

#Syncing System Users and Samba Passwords

#Why Two Layers

Every Samba user must be a valid Linux user (remember episode 0: Samba maps to Unix users). But SMB authentication uses password hashes in the NTLM format, which can't be stored in a regular /etc/shadow. That's why Samba has its own password database. The correct user-creation flow:

Create a system user + register it with Samba

sudo useradd -m -s /bin/bash arman
sudo smbpasswd -a arman

smbpasswd -a arman adds user arman to the Samba password database and asks for an SMB password — which may differ from the Linux login password. After this, arman can log into the share with their SMB password.

#Password Database: tdbsam

By default Samba stores users in the tdbsam format — a TDB (Trivial Database) format database at /var/lib/samba/private/passdb.tdb. This replaces the legacy plain-text smbpasswd format. Its advantages: transactional consistency, secure, and it's the same foundation used by the pdbedit tool. You can check the exact location:

Passdb database location

ls -l /var/lib/samba/private/passdb.tdb

#pdbedit: A Window into the Password Database

#Viewing the User List

pdbedit is the primary tool for manipulating the password database. To list all Samba users:

List Samba users

sudo pdbedit -L

The output is a list of usernames, one per line. For full details including account flags:

Full user details

sudo pdbedit -L -v

#Account Flags

In the output of pdbedit -L -v, look at the Account Flags: section — abbreviations that describe the account status:

[U] — User: a normal account.
[D] — Disabled: account disabled, cannot log in.
[N] — No password: account with no password (rare for production).
[W] — Workstations: workstation trust account (used in AD).

Enable/disable accounts easily:

Temporarily disable an account

sudo smbpasswd -d arman      # disable
sudo smbpasswd -e arman      # enable

smbpasswd -d/-e toggles the D flag without deleting the user — good practice for a "temporary leave" instead of deleting the whole account (episode 15, least privilege).

#Other Commonly Used Operations

Change password and delete user

sudo smbpasswd arman                 # change password
sudo pdbedit -x -u arman             # remove from the Samba database
sudo userdel -r arman                # remove system user + home

The correct deletion order: pdbedit -x -u arman first (clean the Samba database), then userdel (remove the Linux user). If reversed, Samba keeps an "orphan user" mapped to a nonexistent identity — a source of confusion when auditing.

Important

Samba passwords and Linux login passwords are different systems. Changing the Linux password via passwd does not change the SMB password, and vice versa. For production environments, consider a synchronization mechanism — or point authentication to Active Directory via winbind (episode 10) so there's a single source of passwords.

#Username Map: Aliases for Names

#Aligning Names Across Two Worlds

Sometimes Windows usernames differ from Linux usernames (e.g. a client uses dpangestu while Linux uses arman). username map bridges the two through a mapping file:

/etc/samba/smb.conf [global]

[global]
   username map = /etc/samba/smbusers

Contents of /etc/samba/smbusers:

/etc/samba/smbusers

dpangestu = arman
admin = root
@devs = @developers

The format is client_name = linux_user. The first line makes connections as dpangestu be treated as arman; the last line shows group-to-group mapping. After editing, reload the configuration and test login with the alias:

Test the username alias

smbclient //localhost/data -U dpangestu

Warning

A username map targeting root (e.g. admin = root) is very risky: any share writing with force user = root will write as superuser. If you really must, restrict it with valid users and audit strictly. A safer alternative: create a dedicated Linux user with limited rights, not root.

#Full Verification

Here's the complete picture of the user management cycle:

Full user management cycle

sudo useradd -m -s /bin/bash arman
sudo smbpasswd -a arman
sudo pdbedit -L | grep arman
sudo pdbedit -L -v | grep -A1 "Account Flags"

The last three steps confirm the user exists, is registered, and is active ([U]). If pdbedit -L comes back empty, something went wrong in the sync step — go back to smbpasswd -a.

#Closing

Key takeaways:

A Samba user = a Linux user + an entry in the password database (tdbsam).
smbpasswd -a user registers a user; pdbedit -L reads the list; pdbedit -L -v shows account flags.
Account flags [U], [D], [N], [W] control account status; smbpasswd -d/-e toggles disable/enable.
username map maps client names to Linux users; avoid mapping to root.
SMB passwords and Linux passwords are not automatically synchronized.

In episode 6 next, we'll cover client access: Linux & Windows — mount -t cifs //host/share /mnt -o username=... and smbclient //host/share from the Linux side, then \\server\share, stored credentials, and network discovery from the Windows side. This is the episode where your shares finally get used from both worlds at once!