This article has been reprinted from TechProGuild. If you find this article helpful, subscribe to TechProGuild to get access to all our in-depth technical articles. Sign up now for a FREE 30-day trial. All the articles on our site that include a green $ icon are available only to TechProGuild members.

Like most things, when Samba is working, it’s great. It has it all—fast file sharing and simple interoperability between Windows and Linux. However, also like most things, troubleshooting Samba can be a frustrating experience. One of Samba’s strengths is its flexibility. One of its limitations is that it’s almost too flexible. With a simple or inadvertent change to the smb.conf file, it’s entirely possible to make it impossible for clients to connect.

Before you start cursing Andrew Tridgell for ever creating Samba in the first place, there are a few things you need to look into. Here are some basic troubleshooting steps and some diagnostic tools that you can use to resolve your differences with Samba.

Verifying the configuration
Writing an smb.conf file seems simple enough, until it’s late in the morning, and you’re painfully short of sleep. Although Samba has been kind enough to include some misspelled attributes that map to a properly spelled counterpart, they can’t provide translations for every possible misspelling. That’s where you need a tool to check the smb.conf file for syntax errors. Luckily, Samba includes a configuration verification tool named testparm.

Just type testparm at a command prompt and watch the information about your configuration file show up. Be on the lookout for lines that start with Unknown Parameter Encountered. Those are the lines that most likely have a typo in them.

If you don’t get any errors, then your problem probably isn’t caused by a syntax error in your configuration file. Although, it might still be caused by a logical error where you’ve not enabled an interface, or the user you’re testing with isn’t authorized to a share. Either way, the next step is to observe what Samba is doing.

Is Samba started?
Before trying to figure out what’s wrong, you have to make sure that Samba is started. The easiest way to do that is to enter ps –ea | grep smbd at a command prompt. If you get a line back that shows you the process number for the smbd process, then Samba is running. If you don’t see the line, then Samba isn’t even started, so connecting with it will be difficult. You can start Samba by typing smbd. Next up in your troubleshooting journey is to take a quick look for errors in the log files.

Look before you leap
Whenever Samba starts up, it creates log files that record what happened, when, and by whom. It’s like a game of Clue with all of the answers. In the /var/log/samba directory you’ll find a set of files that log different activities with aspects of the Samba system.

The files that start with log. are the service logs. These logs record when a service is started or stopped. If the logging level is turned up, as described later, they can record substantially more information. Turned all the way up, Samba will record an obscene amount of information to the log.

Files that end in .log are one of two types of files. The first type is a file that is created by commands, such as the log file created by smbmount when a SMB share is mounted. The other type of log file is the log file for a workstation. When a workstation connects with the Samba server, Samba creates a log file with the NetBIOS host name. This is useful in identifying and resolving problems with specific workstations.

Your first stop in troubleshooting after verifying the configuration file should be to look through these files to see if the cause of your problem is explained. Barring some inspiration from the log files, it is time to eliminate the network and try a local connection.

Testing locally
It is possible to use Samba to map from the system back to the same system. This has the benefit of eliminating all sorts of network problems that may be preventing connectivity but aren’t related to the configuration of Samba. Testing Samba is as simple as trying to mount one of the locally hosted shares to a mount point. So let’s say you have a share named test and a mount point of /mnt/smb, you should be able to execute the command mount //localhost/test /mnt/smb. If everything is working as it should, you will be prompted for a password. Once you have entered the correct password, the share will be mounted.

If you can’t make this work locally, you have a core problem in the configuration or setup of Samba. You’ll have to work your way back through the configuration file looking for options that may be causing challenges. Don’t forget to check the log files again to see if any new errors popped up.

Back to the basics
If Samba is working locally but you still can’t get it to work remotely, it’s time to get back to the basics of network connectivity so that you can make sure that there aren’t any connectivity problems that are the real root cause of your Samba problems.

Ping by IP address
The starting point with network connectivity is to ping the server by IP address. In a command prompt on the client workstation, type ping address, where address is the IP address of the Samba server. If you get ping responses back, you know that basic connectivity is working. If you don’t get ping responses, then you know that there’s a basic networking problem.

Ping by name
If the basic connectivity is working, the next step is to check name resolution. This is as easy as keying the name after ping instead of the IP address. If ping name works, then you know that name resolution is working fine. If it doesn’t, you know that you have a name resolution problem.

Telnet to a Port
If you know your basic connectivity works and that name resolution is working, it’s time to make sure that you’re able to connect to one of the ports that Samba needs to work. To do this test, you can use telnet. By typing telnet name 139, where name is the name of the server, you’ll start a connection to TCP port 139—an important part of SMB communications. If you get a connection-timed-out message, then you can’t communicate on port 139.

If you can’t communicate on port 139, then you may not have allowed Samba to talk to your network or you may have a device, such as a firewall, preventing communications. The first problem is easy enough to solve. You’ll need to add a hosts allow statement to your smb.conf file, or add the host you’re testing from to the hosts allow statement that is already in your smb.conf file. It’s also possible that you’ve added a bind interfaces only statement to your smb.conf file. This limits Samba’s ability to communicate freely. For your debugging, at least, it should be removed.

If you did make a connection, you can break it by pressing [Ctrl] and typing a closing bracket ([Ctrl] ]), and then typing quit. This will close telnet and return you to a command prompt.

Turning up the volume on logging
If you’ve still not found the source of your problem, it may be time to turn up the volume. To do this, you can add a Log Level statement to the global section of your smb.conf file. The Log Level command tells Samba how noisy to be. A Log Level setting of three should be sufficient for debugging purposes, but you can push the level all the way up to 10. Although, if you turn the level up that high, you should have plenty of disk space available and a few hours of time to read through all of the information that will be generated.