6. Troubleshooting

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

Among the many troubleshooting issues people have asked me about, here are the three frequent solutions that fix nine out of ten problems:

1. Do you have firewall protection (e.g., iptables) on your Samba server? If so, try turning this entirely 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 in this document.
2. Is your smb.conf file longer than 20 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. 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.

Additionally, these troubleshooting items might be of benefit. If one or more of these doesn't work, but others do, then you can help to isolate where the problem is coming from.

• Try pinging your Samba server from itself (i.e., not across the network) using the loopback address
• Try pinging your Samba server from itself (i.e., not across the network) using its IP address
• Try pinging your Samba server from itself (i.e., not across the network) using its FQDN (Fully Qualified Domain Name)
• Try pinging your Samba server from another machine using the loopback address
• Try pinging your Samba server from another machine using its IP address
• Try pinging your Samba server from another machine using its FQDN (Fully Qualified Domain Name)
• Make sure you are running the latest stable version of Samba.
• Run the testparm(1) command to validate the syntax of your smb.conf file.
• Verify that both smbd and nmbd are running.
• From the Samba server, verify that you can query the nmbd server for its own NetBIOS name using "nmblookup -Bmyserver __SAMBA__"
• From the Samba server, verify that you can query the nmbd server for any NetBIOS client name using "nmblookup -B example-client '*'"
• From the Samba server, verify that you can query your subnet for any NetBIOS client name using "nmblookup -d 2 '*'"
• From the Samba server, try generating a list of valid shares using "smbclient -L example-server".
• From a Windows client, try generating a list of valid shares using "NET VIEW \\myserver"
• From the Samba server, verify that you can query the Domain Master Browser (probably itself) for the Samba server's IP address using "nmblookup -M myworkgroup"
• From the Samba server, try connecting to one of its own shares using "smbclient //myserver/myshare -Umyusername"
• From a Windows Client, try connecting to one of the shares using "NET USE X: \\myserver\myshare"
• Try diagnosing what's going on by using tcpdump(1) with something like: "tcpdump -ln -vv host 192.168.1.1 | tee dumpfile"

Logfiles

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:

• log level = 3 Enables logging at the level of detail specified by an integer. The default is 0; to gather anything meaningful you'll want to use at least 1. A level of 3 is useful for brief, problem-specific troubleshooting. A level of 10 is typically used for diagnosing the SMB protocol.
• debug hire timestamp = yes Use microseconds,instead of seconds, in printing out the timestamps in the log messages. Chances are you won't need this unless you're doing massive debugging.
• debug pid = yes Add the process-id of the specific samba process to the log files. This can help you if you're trying to determine which process outputs which log message. Requires the debugtimestamp parameter to be enabled as well.
• debug timestamp = no Actually, this is the default setting and is generally quite useful. You might want to set this to 'no' if you're running at a high debug level and don't want the timestamps to be printed out as well, which can be distracting. It's also helpful when comparing log files with diff(1), although one caveat is that you don't get the name and function of the code that is generating the message (catch-22).
• debug uid = yes Print out the effective uid (euid), effective gid (egid), uid and gid along with the the timestamp message headers in the log files. Since Samba runs as root and at other times runs as the connected user, this can be helpful for certain cases. Requires the debug timestamp parameter to be enabled as well.
• debug level This is a synonym for log level
• log file = %m.log The name and location of the Samba log file. The '%m' allows you to log machine-specific connection information in different log files.
• max log size = 5000 This option allows you to specify the maximum size the log files can grow to. Files exceeding this value (in kilobytes) are renamed with a '.old' extension. Setting this value to '0' disables the log limit.

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.

• The following error occurred attempting to join the domain MYDOMAIN: The network path was not found.Ironically, this is usually a Windows XP specific error where it apparently attempts to contact your PDC via a stale (and incorrect) gateway/route entry in the registry. Change your IP address, subnet, and gateway to something different, and then change it back again. This usually removes any stale entries. It's unclear why this happens, but this behavior can be verified by a packet sniffer.
• The following error occurred attempting to join the domain MYDOMAIN: No mapping between account names and security IDs was done. This obscure error has reportedly been fixed by using lower-case names for the workstation name in/etc/passwd and smbpasswd and on the Windows XP client. It's unclear why this matters as Samba shouldn't care about this.
• The following error occurred attempting to join the domain MYDOMAIN: Access is denied. There isn't a machine account entered in smbpasswd for the computer you're attempting to have join the domain, or the machine account is currently disabled. It's also possible that you're trying to join the domain using an account name other than"root", which is required.
• The following error occurred attempting to join the domain MYDOMAIN: Logon failure: unknown user name or bad password. Either "root" doesn't exist in the smbpasswd database, or you've typed in an incorrect password.
• The following error occurred attempting to join the domain MYDOMAIN: The specified network password is not correct Use Window's Group Policy Editor (gpedit.msc) to make the following changes in the Local Computer Policy\ Computer Configuration\ Windows Settings\ Security Settings\ Local Policies\ Security Options branch: Domain member: Digitally encrypt or sign secure channel data (DISABLE) andDomain member: Digitally sign secure channel data when possible (DISABLE)
• System error 53 has occurred. The network path was not found. This error message can happen if you aren't running Windows XP Service Pack 1 and have disabled NetBIOS over TCP/IP (NetBT). See Microsoft Knowledge Base Article 308246.
• System error 6118 has occurred. The list of servers for this workgroup is not currently available. This behavior can occur if you have enabled Windows XP's built-in Internet Connection Firewall (ICF), which disables SMB ports by default. The Master Browser attempts to reconnect to the client computer to send the Browse list, but the firewall prevents this connection. See Microsoft Knowledge Base Article 298804.
• A domain controller for the domain MYDOMAIN could not be contacted. You've typed in a domain name,however it's not the one that your Samba server is using. You want to use the value of the "workgroup" parameter from smb.conf as the name of your domain. Another possibility is that nmbd is not running on your server, and therefore can't answer NetBIOS name queries.
• The Account Used is a Computer Account. Use Your Global User Account or Local User Account to Access the Server. This reportedly happens if the machine account information (account, UID, GID) in /etc/passwd does not match its same credentials in /etc/samba/private/smbpasswd. Usually, this is the result of modifying either /etc/passwd or smbpasswd for the machine account, and not syncing the changes in both. It can also be caused by using an account name that does not match the NetBIOS name of the Windows machine (thanks to Sherwood Botsford for the info!).
• The Messenger service terminated with service-specific error 2270. This behavior can occur if the computer's name is not unique on the network. In practice, it can also occur if your computer name, user name, and domain/workgroup name are not all set to unique (different) values. See Microsoft Knowledge Base Article 314094.

Troubleshooting Example

This is, perhaps, the best example of a real-life approach towards troubleshooting, which was posted on samba-technical in Jan 2003:

From: jmwhite@yahoo.com (Jean-Marie White)
Newsgroups: mailing.unix.samba-technical
Subject: Eureka! Slow Samba transfers resolved!
Date: Sun, 19 Jan 2003 18:07:31 +0000 (UTC)

I just spent so much time troubleshooting why *some types* of samba transfers
were slow that I thought I would share how I resolved the problem.

This problem had been going on for ever. As far as I could tell, it was only
happening with winamp (MP3 player). All my MP3s reside on my Linux box and I 
was trying to access them from my PC running Windows 2000. What was throwing 
me for a loopwas that Windows Media player seemed to be more successful at 
playing them ! What would happen is that Winamp would freeze and nothing would 
happen. I had then decided to just copy my MP3s back to my PC.

Then, last night I started using FrontPage for some reason or another, and when 
I tried to publish my web site to my Linux box, then behavior I had observed 
with my MP3s started plaguing FrontPage as well.

I went through all the troubleshooting guides, learned about every samba 
configuration options: I was able to successfully transfer a 100M file in either 
direction (linux->pc or pc->linux) using the File Explorer without any 
problem. But I just couldn't for the life of me understand why winamp and 
FrontPage were having problems.

Then I decided to use ethereal and try and understand what was actually 
happening on the wire. I realized that when winamp or FrontPage were trying to 
transfer files, Linux was ending up retransmitting the same frame over and over 
without ever receiving a TCP acknowledgment for it. Then the PC would eventually 
tear down the session and re-establish the session and restart the transfer. An 
article that I read 
(http://www.dd.iij4u.or.jp/~okuyamak/Documents/tuning.english.html) was talking 
about how Windows could mysteriously drop packets, and I started thinking that 
maybe packets were being lost due to some hardware problem.

So I looked at my PC network card configuration (Linksys LNE 100TX Fast Ethernet) 
and saw that the "Connection Type" was set to auto-detect. (My PC is connected to 
my Linux box through a Linksys 8-port Workgroup Switch - Ehterfast 10/100) So I 
thought, maybe having to ends that "auto-detect" each others speed is not good. So 
I changed my "Connection Type" to 100 TX Full Duplex and VOILA! All my problems 
solved, winamp is happily playing away and FrontPage can publish my whole web 
site in seconds.

I hope this will help.