This is an old revision of the document!



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: -

Setup Wishlist

I was considering setting up Samba in place of Netatalk for sharing with Mac, and I made a list of blockers that could prevent a stable, efficient setup. Here's the list. :)

  1. nas: Samba testing
    1. Setup a share that is not listed for guests (public, private)
    2. Setup SMB1 (NT1) max protocol – despite OS X using SMB2 by default, NT1 is far well supported, and has not had issues commonly reported.
    3. Test extended attributes
      1. Verified that deleting a file removes the file attributes file as well (._foo)
      2. Copying a file from OS X files sometimes (?) creates (and maybe copies?) an EA file
    4. Test running AFP and Samba in tandem
    5. Initial connect is slow (when selecting NAS from left nav in Finder) – looks like it's using Guest connect by default – also need to test when there is a save password for the connection
      1. Setting log level = 0 auth:3 in smb.conf helps display issues with Samba connections
      2. With username map empty (default Samba configuration), this error shows up in logs: check_ntlm_password: Authentication for user [GUEST] → [GUEST] FAILED with error NT_STATUS_NO_SUCH_USER
        1. Setting the username map to /etc/samba/smbusers, and on guest connect, it changes to this: Authentication for user [GUEST] → [nobody] FAILED with error NT_STATUS_NO_SUCH_USER
        2. Then, created a user nobody using smbasswd -a nobody with an empty password, and then it connects with no errors: sam authentication for user [GUEST] succeeded and authentication for user [GUEST] → [nobody] → [nobody] succeeded. However, I don't see any noticeable difference in latency for connecting an OS X client.
    6. Test using usermap to map user logins to public / private shares instead of using 'force user'
    7. Test situation when there are *no* guest shares available, but 'map to user = Bad Guest' still exists
    8. Figure out why 'force create mode = 644' is not working – new files are set to 744
    9. How to setup log files for each user or machine – %u.log creates an actual file named '%u.log'
    10. Look at security implications of using Samba over a WAN
    11. Test files with Word that have macros
    12. Talk to Jon and get some example files that he has problems viewing / updating with AFP
    13. What effects does disabling NetBIOS (added in smb.conf) have for displaying NAS in Network list? What about changing the avahi configuration?
      1. I have a possible theory that the network naming and avahi entries could be causing Finder to cycle through possible network connection options when accessing NAS for the first time. Get a closer look at the Samba logs to see what requests are happening client and server side.
    14. See if it is possible to connect as user “Full Name” as well as “shortname”. If it's not possible, then use usermap to map the long ones to the short ones.
    15. Debug OS X's behavior by opening the Console app in the Utilities folder.
    16. Test having default share be clients with user login – not required, as users can still connect manually, but it could be nice to have.
    17. Recommended to enable use sendfile

Also, here is the latest smb.conf file for NAS at the time of stopping research:

# 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