Table of Contents



When creating a user in Samba through Webmin, it will default to no password. You can set a user through Webmin then (plaintext) or use smbpasswd to set one. It will not use the Unix password by default.

You can setup User Synchronization in Webmin to create new Samba users as Unix ones are added, and more.


The smbd program provides file and printer network sharing, and includes the password authentication service for users.

smbd will listen on port 445 for SMB or CIFS protocol traffic. It can also listen on port 139 for NetBIOS traffic.

smbd configuration file

The configuration file is scanned for changes every three minutes.

You can reload the file manually if you like:

smbcontrol smbd reload-config
Display build options
smbd -b


nmbd provides NetBIOS name service and browsing. It handles lookup requests from SMB clients. If enabled, it will use UDP to broadcast on the local subnet.

Disabling nmbd will cause OS X to not display the server in Finder's Networking view.

Gentoo by default will run both smbd and nmbd. You only need smbd, and can change the services in /etc/conf.d/samba.


smbd listens on port 445 for CIFS connections, and does not support NetBIOS.


Finder Bugs

Finder has a large number of bugs related to Samba:

  • Guest access to shares does not work
  • Ejecting a share when only one share from the server is connected, the Shared server list will disconnect, but the shared list will still continue to show the eject button
  • If it cannot connect to a share because of user permissions, will throw an error. However, it will also throw the same error for any shares you try to connect to after that. Disconnect completely and try again.
  • When disconnecting from the server, it will automatically try to reconnect and fail
  • Selecting the server from the Shared menu will take a long time and then fail if there is not a default share set in Samba
  • Finder will sometime cache the mDNS entry for the Samba service, and will not disappear even if avahi is stopped, or if Samba is stopped. Only rebooting the OS X client will clear the cache.

The best way to setup Samba for finder is have a default share that users log into, and / or to allow guests to view the shares.

Connect as username

When connecting to a Samba share, you cannot use the long name “User Account” because Samba is performing the authentication against its own user database. Connect as “user” instead.

Debug OS X

You can debug OS X's behavior by opening the Console app in the Utilities folder.


Setting up Samba's configuration can be tricky, so this is a small walkthrough that goes from a basic, empty Samba configuration.

For this setup, I'm using Gentoo Linux and the latest Samba 3.x security release, 3.6.23.

Before starting, there is one thing to keep in mind – Samba's configuration allows for multiple directives that have the same effect. For example, read only = no is the same as writable = yes. In order to have standardization across the board, use testparm to clean up the configuration, and use their terms.

Use testparm to display current configuration, standardized:

testparm -s

For the record: You can display the full configuration directives that Samba is using by running testparm -v. This is helpful to determine what defaults Samba is using in debugging configuration issues. I wouldn't recommend dumping the defaults to a file to help readability or configuration or anything else. Letting Samba fill in the defaults is sufficient.

Okay, to start with, let's do a barebones, completely empty configuration file.

touch /etc/samba/smb.conf

Use testparm to see what it's interpreting it as, and go ahead and update smb.conf to display that as well.

        idmap config * : backend = tdb

For the next step, let's set up guest access. This will allow us to connect to the Samba server while we are testing. Without any network shares configured, however, we will not be able to browse the filesystem. For now, though, we are just looking at establishing a connection.

Samba maps local usernames on the server to Samba user names with the /etc/samba/smbusers file. Here's the default configuration on Gentoo, minus the comments:

root = Administrator admin
nobody = guest pcguest smbguest

Users root and nobody already exist on the server. You can verify this by running id nobody on the server.

uid=65534(nobody) gid=65534(nobody) groups=65534(nobody)

Next, configure Samba to map users who log in as guests, or users who attempt to access the server with no usernames. The directive is map to guest and the smb.conf man page defines the four options it can be set to: Never, which is the default, Bad User, Bad Password and Bad UID.

The Bad User configuration meets our requirement: “Means user logins with an invalid password are rejected, unless the username does not exist, in which case it is treated as a guest login and mapped into the guest account.”

The wording can seem a bit confusing, so to clarify, if a user tries to log in with a non-existent account on the server, Samba drops the login to a guest account.

This configuration is required to enable guest access using OS X. In my experience, Linux clients work fine without it.

Add the configuration directive to the smb.conf file. Here's what it will look like at this point:

        map to guest = Bad User
        idmap config * : backend = tdb

Based on your client, you may or may not be able to connect to the Samba server. Since there are no shares, it may kick you immediately out (OS X does this). Guest access is enabled, though.

Now, let's create a sample share with guest access, so that we can start connecting and verifying access.

For this example, we'll use the system's temporary directory and use that as the first share path:

        path = /tmp

Restart Samba, and try connecting with your client.

There's a bug here with OS X and Finder when connecting to the server. Finder will connect to the server and display Connected as: Guest in the header, and the tmp share will display as a directory. However, clicking on the tmp folder will open a dialog window saying The operation can't be completed because the original item for “tmp” can't be found., and Finder will close the window. (OS X Mavericks)

To fix guest access, specifically enable guest access in the share. Add guest ok = Yes, and this is what the new Samba configuration will look like:

        map to guest = Bad User
        idmap config * : backend = tdb

        path = /tmp
        guest ok = Yes

Restart Samba, and re-connect with Finder, and it will successfully connect as guest and display the share now.

Now, the next step is to let the user write to the file share. Update Samba to allow writes to the filesystem using read only directive:

read only = No

Here's the updated smb.conf, again using the formatting and order of testparm output:

        map to guest = Bad User
        idmap config * : backend = tdb

        path = /tmp
        read only = No
        guest ok = Yes

Connect as the client, and make some changes to the share. Create a new folder, copy some files in, whatever you feel like, and Samba will save them to the filesystem.

I'm going to use Finder to create a new folder, and use it's default name of untitled folder.

Look at the files or folders created on the filesystem, and you will see that they are created by user nobody – the user that guest access is mapped to on the server.

# stat /tmp/untitled\ folder/
  File: ‘/tmp/untitled folder/’
  Size: 4096            Blocks: 8          IO Block: 4096   directory
Device: 803h/2051d      Inode: 62600       Links: 2
Access: (0755/drwxr-xr-x)  Uid: (65534/  nobody)   Gid: (65534/  nobody)
Access: 2014-04-03 21:31:18.699968718 +0000
Modify: 2014-04-03 21:31:18.699968718 +0000
Change: 2014-04-03 21:31:18.699968718 +0000
 Birth: -
# Samba configuration
# * Guest access for OS X
# * Require NT1 protocol support, allow newer SMB2 support
# * User security level (default)
# * Default to 'images' share
# * and more ..
# See

        # Needed to allow Guest access for OS X and connecting to the server
        # without needing to connect to an actual share.
        map to guest = Bad User
        # likewise, have a default share so that when connecting, it can have
        # somewhere to go
        default service = images

        # SMB2 is native to OS X, but there have been reports that it is slow.
        # All the reports I've found online were back in late 2013, and since
        # Mavericks has had a lot of updates since then (April 2014 at time of
        # writing), I'm enabling it.
        # max protocol = SMB2
        max protocol = SMB2
        # The default minimum protocol is CORE, which is really old.  NT1 is
        # the same as SMB1.
        min protocol = NT1

        # Enabling keepalives as a preliminary precaution.  Samba docs say that
        # it is not necessary *IF* socket options have SO_KEEPALIVE attirbute
        # enabled, which it does not.
        # The default socket options are "TCP_NODELAY"
        keepalive = 600
        log level = 0 auth:3

        # Disabling printer support
        load printers = no

        # Cosmetics
        comment = nas

        # Possibly relevant if debugging
        # deadtime = 15

        # Disable old NETBIOS support
        disable netbios = yes

        # Keep a log for each individual
        # log file = /var/log/samba/users/log.%m

        # Map usernames (for guest accounts)
        # This could also be useful for 'forcing' clients / company access as well
        username map = /etc/samba/smbusers
        path = /var/nas/images
        read only = No
        guest ok = Yes

        comment = Software for all OSes

        path = /var/samba/images/osx/VirtualBox/
        guest only = Yes
        guest ok = Yes

        comment = OS X VirtualBox Images

        path = /var/samba/public

        path = /var/samba/private

        path = /var/samba/testing
        read only = No
        guest ok = No
        comment = Testing Samba EA
        ea support = yes
        force create mode = 0644
        force directory mode = 0755