The Unofficial Samba HOWTO

David Lechnyr < david at hr dot uoregon dot edu >
$Id: samba.html, 2004/06/13 15:25:01 davidrl Exp $

The concept seems to be clear by now. It has been defined several times by examples of what it is not.

1. Introduction

Once long ago, there was a buzzword referred to as DCE/RPC. This stood for Distributed Computing Environment/Remote Procedure Calls and conceptually was a good idea. It was originally developed by Apollo/HP as NCA 1.0 (Network Computing Architecture) and only ran over UDP. When there was a need to run it over TCP so that it would be compatible with DECnet 3.0, it was redesigned, submitted to The Open Group, and officially became known as DCE/RPC. Microsoft came along and decided, rather than pay $20 per seat to license this technology, to reimplement DCE/RPC themselves as MS RPC. From this, the concept continued in the form of SMB (Server Message Block, or the "what") using the NetBIOS (Network Basic Input/Output System, or the "how") compatibility layer. You can run SMB (i.e., transport) over several different protocols; many different implementations arose as a result, including NBIPX (NetBIOS over IPX, NwLnkNb, or NWNBLink) and NBT (NetBIOS over TCP/IP, or NetBT). As the years passed, NBT became the most common form of implementation.

Samba is essentially a TCP/IP file and print server for Microsoft Windows clients. In fact, it can support any SMB/CIFS-enabled client. One of Samba's big strengths is that you can use it to blend your mix of Windows and Linux machines together without requiring a separate Windows server.

Perhaps this quote best describes the environment of SMB:

"Several megabytes of NT-security archives, random whitepapers, RFCs, the CIFS spec, the Samba stuff, a few MSknowledge-base articles, strings extracted from binaries, and packet dumps have been dutifully waded through during the information-gathering stages of this project, and there are *still* many missing pieces... While often tedious, at least the way has been generously littered with occurrences of clapping hand to forehead and muttering "crikey, what are they thinking?" -- Hobbit, CIFS: Common Insecurities Fail Scrutiny

2. Installing Samba

"All parts should go together without forcing. You must remember that the parts you are reassembling were disassembled by you. Therefore, if you can't get them together again, there must be a reason. By all means, do not use hammer." -- IBM maintenance manual, 1975

2.1 Downloading Samba

Samba is currently available in two flavors: Versions 2.2 and 3.0. The advantages to Samba 3.0 are that it's new, includes updated features, and is cutting edge. The advantages to Samba 2.2 are that it's stable, well-tested, and has been in use for a long time. We're hedging our bets on Samba 2.2 for the time being; only history will tell if it's a wise choice or not :-)

You can download Samba from Don't forget to download both the source code and the signature file. Once you've downloaded both files, you can use the signature file to verify that the source code has not been tampered with. You'll need gpg or a similar program to do this.

To configure and build Samba, you can try using something like:

$ tar xzvf samba-x.y.z.tar.gz
$ cd samba-x.y.z/source
$ ./configure --prefix=/usr/local/samba --with-smbmount
$ make
# make install

2.2 Update the System

First, verify that your /etc/services file includes the following definitions (chances are that they're already defined). Don't be suprised if you see entries for 137/tcp and so forth; IANA typically includes both tcp and udp entries regardless of whether or not the protocol requires it. The following entries correspond to

netbios-ns	137/udp		# NETBIOS Name Service
netbios-dgm 138/udp # NETBIOS Datagram Service
netbios-ssn 139/tcp # NETBIOS Session Service
microsoft-ds 445/tcp # Microsoft-DS

2.3 Samba Configuration File

Samba will typically look for it's configuration file in /etc/samba/smb.conf, assuming you've built Samba with the --with-configdir=/etc/samba parameter. The following won't do much other than allow you to run Samba (it doesn't even list any shares yet); however you'll need this file in order to run Samba and continue configuring it:

# Required to support Windows 98 or above
encrypt passwords = yes

# Files that have UNIX permissions that prohibit access are hidden from users
hide unreadable = yes

# We don't have any OS/2 clients
lm announce = no

# We log all activity to a single file for regular review
log file = /var/log/samba.log

# We want a minimum level of logging
log level = 1

# What NetBIOS name does our server call itself?
netbios name = ServerName

# We rely on username/password access methods
security = user

# What description should be shown in the share list?
server string = "Samba Server"

# These options are appropriate for most LAN's

# We never want Samba to decide for us where to put the password file
smb passwd file = /etc/samba/private/smbpasswd

# We support the NET TIME syntax from workstations
time server = yes

# We will provide NetBIOS name resolution (WINS) support for clients
wins support = yes

# This is our domain/workgroup name
workgroup = WORKGROUP

2.4 Running Samba

To actually run Samba, you can issue the following commands:

# /usr/local/samba/bin/smbd -D
# /usr/local/samba/bin/nmbd -D

To automatically start and stop Samba, you can use:


samba_start() {
echo "Starting Samba"
/usr/local/samba/bin/smbd -D
/usr/local/samba/bin/nmbd -D

samba_stop() {
echo "Stopping Samba"
killall smbd nmbd

samba_restart() {
sleep 1

case "$1" in
echo "Usage: $0 start|stop|restart"

3. Server Configuration

"How do you power off this machine?" -- Linus Torvalds, when upgrading, and after using the machine for several months

3.1 smb.conf

The smb.conf(5) file controls the behavior of Samba. By default, it's not created, so you'll have to make one up. Some examples are provided later on in this chapter. However, if you're going to run a Samba server, it's critical that you know where this configuration file is and how many unnecessary duplicate copies of this file exist. Common situations include someone installing Samba on a machine that had left over configuration files from a previous version of Samba. Which smb.conf file is the Administrator supposed to edit? Which one will Samba pay attention to? I think you get my drift. To make sure you're in the clear, run the following command as root:

# find / -name testparm -exec ls -Fla {} \;
-rwxr-xr-x 1 root root 440268 2004-02-09 09:19 /usr/local/samba/bin/testparm*

If all goes well, only one file will show up. Why are we searching for testparm(1) instead of smb.conf(5)? By default, no smb.conf configuration file is installed with Samba, but testparm (which checks the syntax of your smb.conf file) is. So if you've just installed Samba on a system with an existing version of Samba on it, you might have duplicate configuration files located in odd locations you'd never expect. If you find more than one testparm file, you'd better determine why this is and take corrective action before proceeding!

Now that we know where our testparm(1) file is located, let's run it:

# /usr/local/samba/bin/testparm
Load smb config files from /usr/local/samba/lib/smb.conf
params.c:OpenConfFile() - Unable to open configuration file "/usr/local/samba/lib/smb.conf":
No such file or directory
Error loading services.

Whether this gives us an error message or not is not the point; what's important is the first line of output that we receive. In this case, we have our answer: Samba will look for the smb.conf(5) file in /usr/local/samba/lib/smb.conf. This is where you should create/edit your smb.conf file (and your lmhosts file, if you really want this as well). This is probably the single most frequently asked question about Samba -- where should my smb.conf file be located?

3.2 Configuration Example: Webserver

On our public webserver at Human Resources, we allow our staff the ability to edit certain files. Here's our actual configuration along with rationale. Hopefully it will give you an idea or two:

# Reduce the overhead that Samba uses to scan for timeouts
change notify timeout = 300

# Open files with no connections are closed after 15 minutes
deadtime = 15

# We're not really in a domain; this just saves us the unnecessary
# log warnings from nmbd about being unable to contact a domain master
domain master = yes

# Files that have UNIX permissions that prohibit access are hidden from users
hide unreadable = yes

# We only allow access from these hosts
hosts allow =

# All other hosts are denied access
hosts deny = ALL

# The root user and the wheel group are not allowed access
invalid users = root @wheel

# All our computers are Windows XP
lanman auth = no

# We don't have any OS/2 clients
lm announce = no

# We log all activity to a single file for regular review
log file = /var/log/samba.log

# We want a minimum level of logging
log level = 1

# Again, all our clients are Windows XP
min protocol = NT1

# What NetBIOS name does our server call itself?
netbios name = HR

# We rely on username/password access methods
security = user

# We're (mostly) on a Local Area Network, so these settings are appropriate

# Do we provide WINS support?
wins support = yes

# What NetBIOS name does our server use for our domain/workgroup?
workgroup = HRWEBSVR

# We use a template so that we can repeat some of these values across multiple shares
# Testparm complains if this section has no path, so we give a default dummy path
path = /dev/null

# Many times a user will ask us who last changed a file and when. This allows us to
# record this information in the UNIX filesystem despite being anti-POSIX
dos filetimes = yes

# By default, all write access is created with the following mask. Note:
# The use of 7 instead of 6 is intentional -- the extra bit is used by Windows
# clients - go figure!
force create mode = 0774

# All directory creation is made with this UNIX mask.
force directory mode = 0775

# Regardless of the UNIX group a user is in, all file activity is done as this user
force group = +hrgroup

# The following files are hidden by default from the client
# In this case, any Windows XP preview files for icons are hidden for cosmetic reasons only
hide files = /Thumbs.db/

# The following files are not allowed access of any kind. This allows us to maintain PHP
# pages without being modified by non-programmers (*.php). Cascading style-sheets aren't
# accessible either (*.css), along with some other webserver-specific files (favicon.ico,
# robots.txt, & .htaccess). The remainder of the list prevents the creation of any of
# these (usually) harmful files -- usually this would happen if a PC got infected with a virus --
# we don't want to have any of these files created on our webserver whatsoever. The last item
# (*.{*}) prevents any registry specific files from being created as well.
veto files = /*.css/*.php/favicon.ico/robots.txt/.htaccess/*.bas/*.chm/*.cmd/*.com/*.cpl/*.crt/*.exe/*.hta/*.ins/*.isp/*.jsp/*.jse/*.msi/*.msp/*.mst/*.pl/*.reg/*.scr/*.swf/*.sct/*.shs/*.url/*.vbe/*.vbs/*.vb/*.wsc/*.wsf/*.wsh/*.ws/*.dll/*.{*}/

# Where is the main HR website located on the server?
path = /cifs/hr

# Copy the values from the above template section
copy = template

# This section is writeable as well as readable
read only = no

# Only users belonging to the following UNIX group are allowed access to this section
valid users = @hrsection

We have other sections, but it would be redundant as they are very similar to our main section.

3.3 Configuration Example: File Server

Here's the configuration we use for our file server at Human Resources:

# Reduce the overhead that Samba uses to scan for timeouts
change notify timeout = 300

# Open files with no connections are closed after 15 minutes
deadtime = 15

# Yes, we're a domain server (PDC), even though not all of our
# clients are domain members. We avoid it whenever possible.
domain master = yes

# Files that have UNIX permissions that prohibit access are hidden from users
hide unreadable = yes

# We only allow access from these hosts with one exception
hosts allow = EXCEPT

# All other hosts are denied access
hosts deny = ALL

# The root user and the wheel group are not allowed access
invalid users = root @wheel

# All our computers are Windows XP
lanman auth = no

# We don't have any OS/2 clients
lm announce = no

# We log all activity to multiple logfiles depending on the
# NetBIOS name of the computer
log file = /var/log/samba/%m.log

# We want a minimum level of logging
log level = 1

# Where is each user's home directory mapped to?
logon drive = p:

# Where is the user's home directory located?
logon home = \\HRSVR\%U

# Again, all our clients are Windows XP
min protocol = NT1

# What NetBIOS name does our server call itself?
netbios name = HRSVR

# We don't want to compete for browse master elections - we win always
os level = 255

# We want to initiate a browse master election (probably unnecessary)
# preferred master = yes

# We rely on username/password access methods
security = user

# We're on a Local Area Network, so these settings are appropriate

# We allow clients to set their clock to ours using the NET TIME parameter
time server = yes

# Do we provide WINS support?
wins support = yes

# What NetBIOS name does our server use for our domain/workgroup?
workgroup = HRGRP

# Our template section is very similar to the first example (above). No need to repeat ourselves
# here for this example.

# Copy all values from the template section, which in real life is actually filled in.
copy = template

# Each user's home directory uses this section automatically
# However, by default it's not browseable
browseable = no

# It's read/write
read only = no

# Only the individual user is allowed access to newly created files/directories
force create mode = 0700
force directory mode = 0700

# Where is this share located on the UNIX filesystem?
path = /cifs/hrfile

# What UNIX permissions are used for newly created files/directories? Again,
# the use of 7 instead of 6 for create mode is intentional.
create mode = 0760
directory mode = 0770

# Members of which UNIX group are allowed access?
valid users = +hrgrp

# It's read/write
read only = no

# Members who belong to a different initial group should still write to the files
# as the following group. This allows us to not have files/directories with world
# access permissions on them. Only members who are already in the following UNIX
# group qualify (the + symbol indicates this)
force group = +hrgrp

As with the last example, there are more shares. However, you get the idea.

3.4 Oplocks

Opportunistic locking essentially means that the client is allowed to download and cache the file on their hard drive while making changes; if a second client wants to access the file, the first client receives a break and must sync the file back to the server. This can give significant performance gains in some cases; in others, some programs insist on syncing back the contents of the entire file for a single change.Level1 Oplocks (aka just plain"oplocks") is another term for opportunistic locking.

Level2 Oplocks is a fancy way of saying that you are providing opportunistic locking for a file that will be treated as "read-only". Typically this is used on files that are read-only or on files that the client has no intention to write to (at least, not initially).

Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with Samba's oplocked files, although this is simplifying things a bit. SGI IRIX and Linux are the only two UNIX's that are oplock aware at the moment.Unless your system supports kernel oplocks, you should disable oplocks if you are accessing the same files from both Unix/Linux and Smb clients.

Regardless, oplocks should always be disabled if you are sharing a database file (e.g., Microsoft Access) between multiple clients, as any break the first client receives will result in the entire file needing to be sync'd (not just the single record), which will result in a noticeable performance delay and, more likely, problems accessing the database in the first place. Notably, Microsoft Outlook's personal folders (*.pst) react very badly to oplocks. If in doubt, disable oplocks and tune your system from that point.If client-side caching is desirable and reliable on your network, you will benefit from turning on oplocks. If your network is slow and/or unreliable, or you are sharing your files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people will be accessing the same files frequently, you probably will not benefit from the overhead of your client sending oplock breaks and will instead want to disable oplocks for the share.Another factor to consider is the perceived performance of file access. If oplocks provide no measurable speed benefit on your network,it might not be worth the hassle of dealing with them.

You can disable oplocks on a per-share basis with the following:

oplocks = False
level2oplocks = False

Alternately, you could disable oplocks on a per-file basis within the share:

veto oplock files = /*.mdb/*.MDB/

If you're having problems with oplocks as evidenced by Samba's log entries, you may want to play it safe and disable both oplocks and level2oplocks.

3.5 Sockets

Samba allows you to fine-tune how it works with your local network. This is primarily done by adjusting network sockets, which essentially tell Samba how to do low-level work with the local network. Since each network is different (wiring, switches, noise, etc), there is no "magic formula" that works for everyone. As a result, if you want to fine-tune Samba's performance for your specific network, you'll have to do some experimenting. For the diehard (and a great insomnia cure), you can read up on sockets via the manpage for socket(7).

Regardless, a good general starting point for you to try is:



These two options define the maximum size of the send and receive buffers for Samba. Smaller buffers means more fragmented packets; larger buffers (up to a point) mean less fragmentation.

A good way to determine what's best for you is to create both a single 100 MB dummy file and 100 multiple 1 MB dummy files and test the time involved in sending/receiving both sets of files to and from the server. You'll want to make sure to stop and restart Samba each time to prevent any memory caching, just in case. By charting out the different response times for SO_RCVBUF and SO_SNDBUF you can find the optimal value for your specific network.

To create a single 100 MB test file:

dd if=/dev/zero of=testfile count=10240 bs=10240

To create 100 multiple 1 MB test files:

until [ "$count" -gt 100 ]; do
let "count += 1"
dd if=/dev/zero of=testfile${count} count=1024 bs=1024

After you've gathered your data, you'll want to chart it to find the optimal values for your specific setting. Once done, you can adjust your smb.conf file to have something like:

socket options = SO_RCVBUF=8192 SO_SNDBUF=8192


If you're running Samba on your local network, using these options would be a good idea. Adjust your smb.conf file to include:



If you're running Samba across a wide-area network, you can try experimenting with this option:

socket options = IPTOS_THROUGHPUT


This enables the sending of "keep-alive" messages on connection-oriented (tcp) traffic. If your connections are timing out, you can try experimenting with this option.

socket options = SO_KEEPALIVE


You probably don't want to mess with these. If you're curious for more details, see the manpage on socket(7).

4. Passwords, Users & Groups

"I tried to get some documentation out of Digital on this, but as far as I can tell even _they_ don't have it;-)" --Linus Torvalds, in an article on a dnserver

4.1 smbpasswd

Regardless of the client operating system you use, you'll need to set up a list of valid username/passwords pairs that are allowed to access the Samba server. Much like the passwd(1) command changes a password in the system's passwd(5) database, the smbpasswd(8) command changes the smbpasswd(5) database. It's strongly recommended that you know where these files are located (to prevent headaches later on if duplicate versions of Samba ever get/were installed on the machine). To do this, we need to figure out where our two smbpasswd files exists. As root, run the first command (with the other lines being the output):

# find / -name smbpasswd -exec ls -Fla {} \;
-rw------- 1 root root 1160 2004-02-08 12:23 /usr/local/samba/private/smbpasswd
-rwxr-xr-x 1 root root 768080 2004-02-09 09:19 /usr/local/samba/bin/smbpasswd*

The first one is your smbpasswd(5) database (note the 600 permissions) and the second is your smbpasswd(8) command (note the 755 permissions). If you have more than these two, then you have more than one version of Samba installed on your machine, and you have an even bigger problem on your hands to deal with first! If you just installed Samba and you find that you don't have a smbpasswd(5) database yet, don't panic; this is normal.

4.2 Users

To add a user, as root run:

# smbpasswd -a username

You'll be prompted for a password, and the user will be added (-a) to the database.

4.3 Groups

While Samba relies on its own database to determine user/password pairs, it relies on the system's group(5) database for determining group membership(s). If you plan on using groups to allow/deny access to certain files or shares on your Samba server, you'll have to first make sure you've added the user(s) to your smbpasswd(5) database. Then, simply add them to your system's group(5) database using the vigr(8) command. For example:

# vigr

This will allow you to edit the /etc/group database file. You can create new groups as needed. For ease of administration, it's recommended that you create a single group that contains a list of all your Samba users and then create unique groups. For example:


Note that this won't take effect until any users added to the group file log out and back in to reestablish their group memberships!

4.4 Domains

The use of domains basically boils down to three recommendations:

5. Client Configuration

5.1 Windows 95

If you plan on using Windows 95, you need to be aware that it is not able to use encrypted passwords and, without adjusting Samba, will be unable to talk with it. Of course, the reverse is true: Tell Samba to use unencrypted passwords, and all your non-Windows 95 clients will not be able to connect.

To disable encrypted passwords with Samba, make the following change to your smb.conf file:

encrypt passwords = no

To finish configuring your Windows 95 machine, follow the instructions in the next section for Windows 98/ME.

5.2 Windows 98/ME

Fortunately, both Windows 98 and Windows ME use encrypted passwords by default. All that's left is to configure your Network properties in the Control Panel. Make sure you have Client for Microsoft Networks and TCP/IP installed along with your network adapter. If you're not using a DHCP server, you'll probably need to configure the TCP/IP settings as well.

Under the properties for Client for Microsoft Networks, check the box for Log on to Windows NT domain and specify the domain name that your Samba server is using:

Finally, under the second tab labeled Identification, give your computer a unique name and specify the name of the workgroup (which should match the name of the domain, although not strictly necessary):

5.3 Windows XP/2000

You'll need to enable TCP/IP on your system, as well as configure a WINS server, from the control panel. The IP address of the WINS server should be your Samba server (where the nmbd daemon is running):

To map a drive using the Windows GUI, open My Computer. On the toolbar are many options; look for one that provides a list that includes the phrase Map Network Drive (under Windows XP this option is under the Tools menu). Once selected, a new box will open up. In the Drive box, click a drive letter that you wish to use. In the Folder box, type the path for the server and path that you wish to connect to:

Alternately, from a Command Prompt, you can type:

NET USE P: \\niftyserver\pub /YES

5.4 Macintosh (OS X)

First, make sure that you've enabled SMB support in the Macintosh Directory Access Utility (in the Applications/Utility folder):

Select SMB and then click Configure. You can now enter in your preferred workgroup and WINS server information:

Next, activate the Finder (e.g., click on the Finder in the Dock). Select Go, then Connect to Server. In the Server Address field, type in your server address:

After clicking Connect, you may be prompted for your authentication:

If you're using Mac OS 10.3 or later, you might be interested in investigating the new Network Browsing option. You can find a good discussion of it at

5.5 Linux

If you're just planning on running Samba on your Linux box as a server only, you can skip this section. If, however, you plan to mount other SMB/Samba shares on your Linux box, you'll need to prepare a few things first.

First, you'll want to enable the SMB_FS option in your Linux kernel and recompile (see below). If you're planning on running only English, you can skip the option for setting a default NLS. The CIFS option is in a relatively early development stage and can safely be skipped for now.

Note: If you don't compile SMB or CIFS support into your kernel, you'll receive the error message, "mount: fs type smbfs not supported by kernel" when you attempt to mount the remote filesystem.

Second, you'll also need to install Samba on both machines, even though you won't be running it on one of them. On your second machine, you'll need to configure Samba with the --with-smbmount parameter. Why is this? Usually, your system's mount command requires no additional information about the type of filesystem you are attempting to mount. For a few types however (e.g., NFS, SMB/CIFS), additional code is necessary. Using this option automatically creates the smbmount and smbumount commands along with the file /sbin/mount.smbfs (which is actually just a soft link to smbmount).

Lastly, you'll need to add an entry for your Samba server in your system's /etc/hosts file if there's no entry for it in your organization's DNS zonefile, or alternately just use the server's IP address instead.

Once done, you can simply run:

# mount -t smbfs -o username=davidrl,password=mypass // /mnt

6. Primary Domain Controller

"Son, someday a man is going to walk up to you with a deck of cards on which the seal is not yet broken. And he is going to offer to bet you that he can make the Ace of Spades jump out of the deck and squirt cider in your ears. But son, do not bet this man, for you will end up with a ear full of cider." -- Sky Masterson's Father

6.1 Denial & Loss

So you've decided that after all this work, you'd like to embark on the quest of configuring a Primary Domain Controller (PDC). While not necessarily a Good Idea (tm), PDC's are, for the moment, here to stay. So what, exactly, is a PDC? The theory is that it's beneficial to be able to log on to a shared group of resources rather than a single server. This means that no matter where you go, there you are (with apologies).

Unfortunately, the experience of working with a PDC on Linux is somewhat of an emotional one. Typically, unseasoned sysadmins tend to describe their experience with PDC implementation using the Stages of Denial & Loss (with apologies to Kubler-Ross):

  1. Stage 1: Denial. We deny that we are no longer operating under the rules and methodology of Windows. Simply put, we ignore the signs of the loss during our transition from the Windows world to that of Linux. Magical thinking tends to become a frequently used tactic for survival.
  2. Stage 2: Bargaining. The mailing.unix.samba-technical mailing list becomes flooded with our anxious request for assistance. Frequently, such posts are light on details, and never receive a single response. On the odd occassion where an in-depth dissection of the problems encountered is done, a simple reply is usually sent back along the lines of 'RTFM'. Sadly, it is more often relevant advice than not. Hopes of a magical 'cure' to one's PDC woes continue to drift throughout the sysadmin's midnight sleep.
  3. Stage 3: Anger. We become angry with the Samba Team, ourselves, or with others over our loss. Oddly enough, we never become angry at Microsoft and the concept of closed-source technology. Sysadmins tend to become outraged and incensed over the steps that must be taken to compensate for the lack of PDC implementation. Scapegoats would be best made scarce during this particular stage.
  4. Stage 4: Despair. We wonder if we're just not simply bright enough to figure out the problem; perhaps sticking with Microsoft was the right solution all along, we think. Hope and belief in a possible solution are rarely seen. Ironically, the average sysadmin has yet to attempt to logically diagnose the symtoms and problems using all available tools, sticking with the wisdom gleamed from the Microsoft Knowledge Base or Windows GUI error boxes alone.
  5. Stage 5: Acceptance. If a sysadmin makes it to this stage, he/she is able to describe the terms and conditions involved in their loss: This is not a Microsoft world anymore; associated terms and concepts no longer necessarily need apply. We begin to cope with our loss and apply ourselves towards more productive endeavors.

So if you're evaluating whether or not to implement a Primary Domain Controller on your Samba server, how do you know what's the best course of action? Here's David's recommended list to evaluate whether or not it's worth your time and effort:

Conditions (meet at least one of the following):

* You have more than two people sharing a single workstation
* You are supporting clients running only Windows 95/98/ME

That's it. Simple and straight forward. If you're interested in advanced features like roaming profiles, centralized management, fame and glory, you're in for a rough ride. Remember: you've been warned ;-) If you're not discouraged yet, read on for the how bit regarding PDC implementation on Linux...

6.2 Important PDC Concepts

To effectively manage your Samba/Windows collection of computers, it is critical that you understand how Windows NT/2000/2003 Servers provide security through the use of Users and Groups. Specifically, you must be aware that there is a difference between the following four different types of Users and Groups:

Local Users

Local users are accounts that are unique to a single workstation. Each Windows 2000/XP workstation has two built-in Users: Administrator and Guest. Local Users are not available on Domain Controllers.

Local Groups

Local groups are groups that are unique to a single workstation. Each Windows 2000/XP workstation has several built-in Groups: Administrators have complete and unrestricted access to the workstation; Power Users have most administrative powers with some restrictions and can run legacy applications in addition to certified applications; Users are prevented from making accidental or intentional system-wide changes, and can run certified applications but not most legacy applications; the Guests Local Group actually has the same access permissions as the Users group (something that is often overlooked). Local Groups are not available on Domain Controllers.

Domain Users

Domain users are accounts that are created on a Windows NT/2000/2003 Server that is acting as a Primary Domain Controller. Samba mimics this behavior by treating every user in smbpasswd(8) as a Domain User. If the user root is defined in smbpasswd, it is equivalent to the Administrator account on Windows NT/2000/2003.

Domain Groups

Domain groups are created on a Windows NT/2000/2003 Server that is acting as a Primary Domain Controller. Samba technically only has two Domain Groups: the root user, and everyone else. However, Samba mimics additional group behavior by honoring filesystem permission restrictions using the group membership information in/etc/groups -- see groups(1) for more information. Note that starting with Samba 3.0 domain groups are recognized, however this behavior is in its early stages of development.

Samba has no knowledge of Windows 2000/XP Local Accounts; as far as it is concerned, there are only multiple users (defined in smbpasswd) and a single Administrator named root (if defined in smbpasswd). Samba also has no knowledge(nor does it care) about Windows 2000/XP Local Groups; all Samba group memberships are defined in /etc/groups.The reverse is also true -- Windows 2000/XP has no direct knowledge of Samba Domain Users or the /etc/groups file on the Samba box. Therefore,it is possible to log into the domain as root (not advised for the security conscious) yet not have any administrative authority over the Windows 2000/XP box!Under Windows NT/2000/2003 Servers, you can add Local Users, Global Users, and Global Groups to Local Groups. With Samba, you can add Local Users and Global Users to Local Groups. However, with both Windows NT/2000/2003 Servers and Samba Servers, you cannot add Local Users and Local Groups to Global Groups.One option to get around this is to select one account from Samba to add it to each Windows 2000/XP workstation's Administrators Local Group. This needs to be done on a per-workstation basis since Local Groups are just that -- local to the box itself, and to no one else.There is no way to do this from the Samba server (nor should there be) or even from a Windows 2000 Server.

6.3 Joining a PDC (Windows 2000/XP Pro)

To join a Samba Domain, you'll need to first enable a Samba password for the root account on your Samba box. Make sure to choose a secure password! You can accomplish this with something like the following (below). Note that if you have a directive like 'invalid users = root' in your smb.conf file, you're guilty of not thinking with your head!

# smbpasswd -a root

Next, make make the following changes to your Windows registry and reboot:


When establishing your machine as a member of a domain, you'll need to add each Windows machine into your Linux machine's password file using vipw(8) or an equivalent utility. Regardless, the final entry in /etc/passwd should look something like this:


It's important to note the addition of the dollar sign ($) at the end of the workstation name. For example, if your workstation's name is myworkstation, your entry in /etc/passwd should begin with myworkstation$. This is a commonly overlooked problem!

Next, make sure to add an entry into your system's /etc/shadow file using vipw -s or an equivalent utility. Regardless, the final entry in /etc/group should look something like this:


You'll also need to establish a group account for your workstation using vigr(8) or an equivalent utility. Regardless, the final entry in /etc/group should look something like this:


Finally, you need to add this account to the Samba password file. Note the lack of a dollar-sign here! I've never found a good answer as to why it's done this way. What does matter is that the -m switch will tell Samba that you are adding a machine account, so Samba will automatically append a dollar sign to the workstation's name for you. Note that this account won't have an initial password, so it's important to run this step immediately prior to having the workstation join your domain!

# smbpasswd -m -a myworkstation

It's worth noting that you'll want to map your user's primary UNIX groups to Samba's Domain Groups (a new behavior in Samba 3.0). Otherwise, you'll get error messages in your logfiles about "get_domain_user_groups: primary gid of user [someuser] is not a Domain group". You can do this with something like:

# net groupmap modify ntgroup="Domain Users" unixgroup=users

Next, log on to your Windows workstation as administrator. Do not use an account that has administrative rights with a different name -- this will save you possible headaches in the long run. Next, drop to a MS-DOS prompt and delete any existing NetBIOS connections. This will ensure that no lingering connections to any other server (including the often forgotten $IPC share):


In the Control Panel, open up System, locate the Computer Name section and click Change. From here, you can join your Samba domain, which is the "Workgroup" parameter from your smb.conf file. You'll be prompted for a name and password of an account with permissions to join the domain; only the user account "root" will work here, and the account must exist both on your Linux box (of course) and in your smbpasswd file.

It's recommended that you also disable roaming profiles to avoid most of the headaches that it (usually) causes. Use the Group Policy Editor (gpedit.msc) and enable "Computer Configuration\AdministrativeTemplates\System\User Profiles\Only allow local user profiles".

6.4 Troubleshooting PDC Joining Issues

If you can't seem to get your workstation to join your Samba domain, make sure you've reviewed the following checklist:

  1. Review all of the steps listed in 5.2, line by line.
  2. Make sure that there is not a firewall between you and your Samba server.
  3. Make sure that your Samba server is not blocking traffic between you and it. This includes ports 137/udp, 138/udp, 139/tcp, 445/tcp, and ICMP types 3 and 4.
  4. Stop and restart your Samba server by hand -- not by any fancy script or graphical administration tool. If in doubt, you'll need to read up on either man 1 kill or man 1 killall.
  5. Restart your Windows workstation -- this cannot be overstated enough.

If all of this still fails, increase the log level of your Samba server to either 2 or 3, and review the output. You don't need to understand everything the log is saying; but you do need to know enough about your server to be able to look for error messages.

6.5 PDC Roaming Profiles

If you'd like to enable roaming profiles for Windows 2000/XP, make the following changes to your smb.conf file (below). Note that this is strongly discouraged unless you know what you're doing (headache prevention)!

logon path = \\my-server\profile\%U

browseable = yes
create mode = 0600
directory mode = 0700
path = /home/profile
profile acls = yes
read only = no

But wait -- have you ever come across getting this error message before:

Windows cannot update your roaming profile.  Possible causes of this error 
include network problems or insufficient security rights. If this problem
persists, contact your network administrator.

This evil error message is the result of poor support for the issue of case sensitivity. If you examine the samba logfiles (debug level 3) and compare successful with unsuccessful roaming profiles, you'll see that some of the critical files (e.g., NTUSER.INI) are being transferred in lower case instead of upper. Why this makes a difference -- I'm not sure. Nor do I care. However, here is the solution that works (for us, at least). Your mileage may vary; let us know the results for you!

browseable = yes
create mode = 0600
directory mode = 0700
path = /home/profile
profile acls = yes
read only = no
default case = lower
preserve case = no
short preserve case = no
mangle case = yes
case sensitive = no

6.6 Login Scripts

If you're running your Samba server to act as a Primary Domain Controller (PDC) for Windows clients, you can have a batch file execute upon login. This can be enabled by adding the following to your smb.conf file:

logon script = logon.bat

path = /home/netlogon

All login scripts must reside in the [netlogon] share and should be formatted (CR LF) to be readable by your Windows clients (see below). Here's a sample script which I've found to be quite useful:

@echo off 
NET TIME \\example-server /SET /YES
NET USE F: \\example-server\PUBLIC /YES

Another issue to become aware of with login scripts (among other things) is line feeds. Windows computers expect login scripts to end each line with windows-style line breaks; Linux expects shell scripts to end each line with UNIX line breaks.

Architecture Hex Definition
DOS/Windows 0x0d 0x0a Carriage Return (CR), Line Feed (LF)
Macintosh 0x0d Carriage Return (CR)
UNIX 0x0a Line Feed (LF)

Technically, DOS files also end with a "\z" (0x22); but supposedly Windows discards or ignores this.

So why is this important? If you're working in a Linux/Windows mixed environment, you're bound to come across files that are littered with '^M' at the end of every line. This is the Windows command for 'newline', which uses a combination of a carriage-return (CR) and line-feed (LF), affectionately known as CR/LF. Linux uses just the single LF. A good example of this in practice is when creating a shell program for Linux from windows workstation. For example:

echo "Is It Not Nifty?"

If you wrote this with the Windows Notepad program, made it executable (chmod 755) and tried to run it under Linux ,you'd get the following error message as a result of the embedded control characters at the end of each line:

$ ./
: bad interpreter: Permission denied

The best solution is to never do this in the first place. The second best solution is to use Patrick Volkerding's excellent todos utility.

Alternately, to convert from DOS to Linux, you can use either of these tricks:

$ cat dosfile.txt | col -b > linuxfile.txt
$ perl -pi -e 's/\r\n?/\n/g' dosfile.txt > linuxfile.txt

It's worth noting that if you're running into this problem in the first place, it means you're working on a file that is being edited in both your Linux and Windows environments. As such, you should probably read the section on oplocks to prevent any data loss...

If you'd rather take care of things from the other side of the coin, you can simply use a text editor that can convert between DOS/Linux. For Windows, there's Jean-Pierre Menicucci's Editeur; for Macintosh, there's BBEdit.

7. Troubleshooting

"Your reasoning is excellent -- it's only your basic assumptions that are wrong."

  1. Determine who generated the error: Is this an error as a result of something happening (or not happening) on the client? On the server?
  2. Determine what has happened: Is it an error in a specific application or procedure? What is the specific Windows error message? What does the Samba logfile say about it? Have you tried increasing the logging level to get more specifics on what's happening?
  3. Determine where the error has happened: Is this an application error? Session error? Transport? Network? Remember to think in layers.
  4. Determine when the error happens: Is it a causal factor, or just a symptom of another agent? Can you reproduce it? Under what conditions?
  5. Determine why the error happens: Have you searched for the specific error message on Google? The Samba mailing list archives? The man pages and other included Samba documentation?

Common Issues

Despite all of this, here are some of the more common issues you may run across when troubleshooting Samba:

  1. Do you have firewall protection (e.g., iptables) on your Samba server? If so, try temporarily turning this off. Do the same to your Windows computer -- this includes any 3rd party firewall (e.g., Norton Firewall) and the built-in Internet Connection Firewall (ICF) on some versions of Windows. If things work fine, then you're guilty of using a tool without knowing how to use it ;-) Read up on the section on using Samba with iptables (earlier in this document).
  2. Is your smb.conf file longer than 30 lines? In fact, did you just start with the example that comes with the Samba source code? If so, you're guilty of the "cut and paste" syndrome and/or the "configuration overkill" habit. Trust me; avoid the headache and start over from scratch. Only include the items in smb.conf that you need. Only add items to your configuration file once everything is working.
  3. Did you configure Samba using SWAT? If so, shame on you. This tool causes more headaches than it solves.
  4. Are you getting an obscure Windows error message? Microsoft has never fully documented their error messages; instead, try increasing Samba's log level to either 2 or 3; restart Samba and examine the log output. The Samba Team has put a lot of effort into accurate logging of what's going on, and you'll get more diagnostic mileage out of it than you will Microsoft's snazzy simple yet unclear error message.

Common Strategies


To stand a chance of determining the answer to the classic question of "what went wrong" you'll need to understand how to enable Samba logging and how to decipher its cryptic log messages as well. First, here are a few of the smb.conf parameters that directly affect logging:

Common Error Messages

While it's not Samba's responsibility for managing ill-conceived error messages from Microsoft Windows,here are some of the more common ones you might encounter when trying to join a Samba domain. Please note that this is not a comprehensive list -- Windows has many error messages that are undocumented by Microsoft.


"It turned out that the worm exploited three or four different holes in the system. From this, and the fact that we were able to capture and examine some of the source code, we realized that we were dealing with someone very sharp, probably not someone here on campus." --Dr. Richard LeBlanc, associate professor of ICS, in George Tech's campus newspaper after the Internet worm


Microsoft Windows does not store or transmit passwords in clear text. Instead, it uses a hash of the user's password for authentication. A hash is essentially an algorithm where a piece of data (the password) is transformed by a mathematical formula (the hashing algorithm). Microsoft Windows implements three of these algorithms:

Although Windows NT & higher don't use the first algorithm (LM) anymore, for backwards compatibility they locally store these insecure password hashes in addition to the secure version. It's worth noting that since both the LMHash and the NTLM Hash are stored, the weaker of the two hashes becomes the weakest link. Therefore, the weakest link becomes the most optimal password (as anything stronger will be reduced in strength). Even the most complex password is therefore reduced to the effectiveness offered by a simple 7-digit single-case password.As a result, if your network does not include any Windows95/98/ME machines, you are strongly recommended to disable LM authentication on the Samba server and increase the minimum protocol by using the following global configuration in your smb.conf file:

lanman auth = no
lm announce = no
min protocol = NT1

Note that this only addresses the password issues on the server, not anything stored locally on the clients.

Host Access

If you run your samba server on a machine that has a valid IP address to the Internet, or an an untrusted LAN, you'll probably want to limit who can connect to your Samba shares.

Assuming your server runs on, your netmask is and you wish to deny access to a host in your network on, your smb.conf file should look like:

hosts allow = EXCEPT
hosts deny = ALL

If you're unclear as to why this is, or are confused by the '/24' bit, you should spend some time reading up on subnet masks. A nifty network calculator that lets you get your hands dirty is available at

It's also useful to limit the interfaces on which Samba will run, if you have a multi-homed (more than one IP address)server. A common mistake is to set the interfaces line to the specific IP address of the box, when it is actually the IPsubnet that your interface is on that you want to use. Assuming your server runs on and your netmask is255.255.255.0, your smb.conf file should look like:

interfaces =
bind interfaces only = Yes

Regardless of the security measures you incorporate into your Samba design, you should never run SMB services across an untrusted network (e.g., the Internet). The SMB/CIFS protocol is vulnerable to many attacks. Ports 135/UDP, 135/TCP, 137/uid,138/UDP, 139/TCP and 445/TCP should never be exposed to untrusted networks.

To prevent the administrative user from logging in, use:

invalid users = root @wheel

To prevent unreadable files (per Linux permissions) from being displayed, use:

hide unreadable = yes

To prevent browsing by default, use:

browseable = no

To prevent access to suspicious files (e.g., those that tend to become infected by virus'), use the following. The last bit prevents access to files with a CLSID in the file extension.

veto files = /*.exe/*.dll/*.pif/*.com/*.vbs/*.{*}/

To hide (but not prevent access to) files, you can use:

hide files = /example.txt/*.ico/


To filter traffic to your Samba server using iptables(8), you could try something like:

SERVER="" # Server IP Address
NETMASK="" # Server Netmask
NETWORK="" # Local area network
BROADCAST="" # Local area network Broadcast Address

iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT
iptables -A INPUT -p udp -s ${NETWORK}/${NETMASK} -d ${SERVER}/32 -m multiport --dports 137,138 -j ACCEPT
iptables -A INPUT -p tcp -s ${NETWORK}/${NETMASK} -d ${SERVER}/32 -m multiport --dports 139,445 -j ACCEPT
iptables -A INPUT -p udp -s ${NETWORK}/${NETMASK} -d ${BROADCAST}/32 --dport 137 -j ACCEPT
iptables -A INPUT -p udp -d ${SERVER}/32 -m multiport --dports 137,138 -j DROP
iptables -A INPUT -p tcp -d ${SERVER}/32 -m multiport --dports 139,445 -j DROP
iptables -A OUTPUT -s ${SERVER}/32 -d ${NETWORK}/32 -m state --state ESTABLISHED,RELATED -j ACCEPT

Additionally, ICMP type 3 code 4 (Fragmentation Needed) should never be blocked. Otherwise, your server/client will be unable to negotiate a valid MTU window size. A good rule of thumb is to avoid blocking ICMP traffic while tuning your Samba server.

Tunneling SMB via SSH

One method of encrypting SMB traffic over a network is to "tunnel" SMB through SSH using a method known as port forwarding. This is a frequently asked question by system administrators wishing to secure remote SMB traffic.While this is possible, it does have some serious drawbacks which we will touch on as well.It's important to be aware that running SMB by itself without SSH over a 56k dial-up line is still terribly slow to the point of frustration. If you don't have a high speed link or at least a lot of patience, you probably don't even want to deal with tunneling over SSH.The other unfortunate bit of news is that due to a design limitation in the GUI API of Windows 9x/ME, you'll only be able to perform your tunneled work in a MS-DOS window. Once you step outside of this and attempt to interact with your remote server via the GUI, you'll find 30-60 second periods where the computer will pause/hang, after which it will complain that the path is invalid or unavailable. One possible explanation is the 16/32-bit nature of this type of Windows OS, however there has yet to be a confirmation of this by either Microsoft or the Samba team. Those using the 32-bit Windows 2000/XP systems will not have this limitation whatsoever.That being said, the good news is that tunneling SMB through SSH is indeed possible. Name services, or anything relying on UDP, can't be forwarded via SSH due to a limitation in how SSH forwards ports (TCP only).So, we'll focus on port forwarding only TCP/port 139. Since UDP tunneling is not available under SSH, your first step involves adjusting the lack of WINS/broadcast name resolution.

Windows provides two different files, HOSTS and LMHOSTS. The former is for Hostname-to-IP Address resolution (similar to DNS), and the latter is for NetBIOS-name-to-IP Address resolution (similar to WINS). LMHOSTS originally stood for "LAN Manager". These files are provided as a "backup" in the case that DNS or WINS are not available. Since NetBIOS name resolution only works via UDP, which can't be tunneled via SSH, the first step is to edit the LMHOSTS file:

REM Under WinNT/2k/XP, this is c:\windows\system32\drivers\etc\LMHOSTS
REM Under Win9x/ME, this is c:\windows\LMHOSTS FAKENAME #PRE

Where FAKENAME is a bogus NetBIOS name that you will use to refer to your Samba server. The #PRE statement tells Windows that this name should be cached into memory, otherwise it won't always be read. The LMHOSTS file will not be processed by Windows until you reboot or you issue the following command, which forces a reload of the NetBIOS name cache (note the uppercase-R):


Configure your client's SSH program to forward port 139/TCP on the localhost to port 139/TCP on the server, and then connect via SSH. Once done, open up a Command Prompt and issue these commands:


Viola! Both commands work, and you can confirm the encryption with a packet filter. Possible error messages you might see include:

Secure Sockets (SSL)

For better or worse, SSL support has been removed from Samba as of version 3.0. The general consensus among the Samba team was that an SSL-enabled Samba could be better implemented by external tools. Add to that a batch of unmaintained and (mostly) unused code led to the final decision of the removal of SSL from Samba.

Important Definitions

SMB (Server Message Block)

This is an older, generic protocol for sharing files, printers, serial ports and communications abstractions such as named pipes and mail slots between computers. Microsoft implements their own form of the SMB Protocol, to provide file and printer sharing in all versions of Windows.

CIFS (Common Internet File System)

This is the new name for SMB. Around 1996, Microsoft apparently decided that SMB needed the word "Internet" in it, so they changed it to CIFS. CIFS provides better interoperability with newer servers including Windows Server 2003 and CIFS-based NAS appliances, is optimized for the current versions of the SMB/CIFS protocol and has better POSIX file I/O semantics. CIFS is built in to the Linux 2.6 kernel and is available currently as a patch for the 2.4 kernel.


This means to take variable data, serialize (i.e., place in order) it, and send it in transmittable form across a network or to a file. Unmarshalling is the reverse process. In DCE/RPC terminology, marshaling and unmarshalling refers to the flattening and unpacking of a data stream between a client and server. These two terms show up a lot when debugging with the Samba logfile.

NetBIOS (Network Basic Input/Output System)

This is standard, not a protocol. It can help to think of this in comparison your computer's BIOS -- it controls the essential functions of your input/output hardware -- whereas NetBIOS controls the essential functions of your input/output traffic via the network.Again, this is a bit of an exaggeration but it should help that paradigm shift. What is important to realize is that NetBIOS is a transport standard, not a protocol. Unfortunately, even technically brilliant people tend to interchange NetBIOS with terms like NetBEUI without a second thought; this will cause no end (and no doubt) of confusion.

NetBEUI (NetBIOS Extended User Interface)

This is a protocol, not a standard. It is also not routable, so traffic on one side of a router will be unable to communicate with the other side.Understanding NetBEUI is not essential to deciphering SMB; however it helps to point out that it is not the same as NetBIOS and to improve your score in trivia at parties. NetBEUI was originally referred to by Microsoft as "NBF", or "The Windows NT NetBEUI Frame protocol driver". It is not often heard from these days and, contrary to popular belief, is not required for using TCP/IP.

NBT (NetBIOS over TCP)

This allows the continued use of NetBIOS traffic over TCP/IP. As a result, NetBIOS names are made to IP addresses and NetBIOS name types are conceptually equivalent to TCP/IP ports. This is how file and printer sharing are accomplished in Windows 95/98/ME. They traditionally rely on three ports: NetBIOS Name Service (nbname) via UDP port 137, NetBIOS Datagram Service (nbdatagram) via UDP port 138, and NetBIOS Session Service (nbsession) via TCP port 139. All name resolution is done via WINS, NetBIOS broadcasts, and DNS. NetBIOS over TCP is documented in RFC 1001 (Concepts and methods) and RFC 1002 (Detailed specifications).

Additional Resources


"What's fundamentally wrong is that nobody ever had any taste when they did it. Microsoft has been very much into making the user interface look good, but internally it's just a complete mess. And even people who program for Microsoft and who have had years of experience, just don't know how it works internally. Worse, nobody dares change it. Nobody dares to fix bugs because it's such a mess that fixing one bug might just break a hundred programs that depend on that bug. And Microsoft isn't interested in anyone fixing bugs -- they're interested in making money. They don't have anybody who takes pride in Windows 95 as an operating system.People inside Microsoft know it's a bad operating system and they still continue obviously working on it because they want to get the next version out because they want to have all these new features to sell more copies of the system."

"The problem with that is that over time, when you have this kind of approach, and because nobody understands it, because nobody REALLY fixes bugs (other than when they're really obvious), the end result is really messy. You can't trust it because under certain circumstances it just spontaneously reboots or just halts in the middle of something that shouldn't be strange. Normally it works fine and then once in a blue moon for some completely unknown reason, it's dead, and nobody knows why. Not Microsoft, not the experienced user and certainly not the completely clueless user who probably sits there shivering thinking "What did I do wrong?" when they didn't do anything wrong at all."

"That's what's really irritating to me."

-- Linus Torvalds, BOOT Magazine, 9/98

Copyright © 2004 by David Lechnyr
This document is distributed in the hope it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation. A copy of the license is available at

Best Viewed with a Green Cheek Conure!