FAQ

What is SambaScanner?

SambaScanner is a tool to scan Samba networks (commonly known as "Windows networks") and list all files. These can then easily be retrieved by a second tool which also is in the kit. It does the job of tools like "ShareScan" in the Windows world, with some differences:

• SambaScanner is free software. No need to pay big bucks to get cool software!
• In direct comparison, SambaScanner performs faster and is more reliable
• You get the sourcecode together with SambaScanner
• SambaScanner does its jobs the UNIX way of doing things: many distributed programs achive one great goal. It's beautiful ;-)

I can't wait any longer! Where can I get it?

You might scroll down to get the complete revision history or just grab it from right here.

Why do I need another tool?

SambaScanner is a highly multithreaded tool, making the scanning process incredibly fast. It also only relies on the Samba tools (smbclient, nmblookup) you probably already have. Through a somewhat smart detection of "hung" processes (which sadly occours often enough using smbclient) these processes are sent the appropriate kill signals automatically and do not inhibit the overall scanning process.

What license is SambaScanner released under?

SambaScanner is being released under the Version 2 of the GNU General Public License. This means you may modify the code and recompile it, redistribute it - whatever you like, as long as it doesn't violate the GPL-2.

SambaScanner is crap! It doesn't work at all! Screw you!

I happily accept any patches improving SambaScanner and will of course also give credit accordingly. If you think you found a bug and you're unable to fix it by yourself, feel free to send me an eMail. I can, however, not guarantee that I have the time or the possibility to fix it - some bugs might only occour in strange network configurations which I might be unable to reproduce.

What operating system/architecture does SambaScanner work with?

SambaScanner has been tested and known to work with the following operating systems:

• Gentoo Linux
• Ubuntu Linux
• Debian Linux
• FreeBSD

Supported platforms, which have been tested, are the x86 (IA-32) and x86-64 (AMD64 = EM64T = Intel64) architecture. Others should work (I put great effort into portability), but are untested. Please report back if you get it running on a MIPS, TriCore or some other obscure hardware :-)

How do I install SambaScanner?

Well, it's pretty easy. First, you need to extract it, after you downloaded the latest version:

acer joe [~]: tar xfj SambaScanner-0.22.tar.bz2
acer joe [~]: cd SambaScanner-0.22 
acer joe [~/SambaScanner-0.22]: ./configure --prefix=/usr
acer joe [~/SambaScanner-0.22]: make

After successful compilation, you might want to copy the files sambascanner, smblister and sambaretrieve to /usr/bin (you need to become root to have the privileges of doing so):

acer joe [~/SambaScanner-0.22]: make install

Now SambaScanner is installed and available to all users on your system.

...and how do I do it on FreeBSD?

As I do not use BSD myself, I do not know - but gladly I received an email from David Adam who told me how he got it working:

What if I get "cannot find -lsmbclient"?

If you're seeing something like this:

acer joe [~]: ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables... 
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking for style of include used by make... GNU
checking dependency style of gcc... gcc3
checking for pthread_create in -lpthread... yes
checking for smbc_init in -lsmbxclient... no
configure: error: libsmbclient was not found but is required for SambaScanner.
You might need to install development sources (header files).
acer joe [~]:

acer joe [~]: make
[...]
gcc -O2 -Wall -DDEFAULT_SMBCLIENT=\"/usr/bin/smbclient\" -DDEFAULT_NMBLOOKUP=\"/usr/bin/nmblookup\"
    -DDEFAULT_SMBLISTER=\"/usr/bin/smblister\" -lpthread -lsmbclient -o sambascanner
    sambascanner.c Parser.o Mutex.o Semaphore.o
/usr/bin/ld: cannot find -lsmbclient
collect2: ld returned 1 exit status
make: *** [sambascanner] Error 1
acer joe [~]: 

Then it probably means you're lacking libsmbclient. On Debian Linux, try:

acer joe [~]: apt-get install libsmbclient libsmbclient-dev

And it should work.

Can I see an example?

Sure. Here's how you scan a network:

acer joe [~]: sambascanner
Looking up workgroup...
Retrieving master browsers in workgroup 'MATRIX'...
Revealing share content of 4 shares in 3 host...
acer joe [~]:

Now a file exists called "Filelist.txt", which contains the full name of all Samba files found (including the hostname, sharename and path). You can view this file directly by doing a "less Filelist.txt" or you might do a more sophisticated search using grep. Suppose you want all stuff conaining the words "paris" or "hilton", but you of course don't want her infamous sex tapes. You'd issue a:

acer joe [~]: grep -i "paris" Filelist.txt | grep -i "hilton" | grep -vi "sex"
smb://NEO/Picures/ParisHilton01.jpg
smb://NEO/Picures/ParisHilton02.jpg
smb://NEO/Picures/ParisHilton03.jpg
smb://NEO/Picures/ParisHilton04.jpg
smb://MORPHEUS/Stuff/Favorites/CommercialWithParisHilton.mpg
smb://TRINITY/Funny/HiltonParisParody1.mpg
smb://TRINITY/People/Hilton/Paris/01.jpg
smb://TRINITY/People/Hilton/Paris/01.txt
acer joe [~]:

Now suppose you want to get all these files you saw. You'd just redirect the grep output to a file called "Retrieve.txt" and then call the "retrieve" script:

acer joe [~]: grep -i "paris" Filelist.txt | grep -i "hilton" |
     grep -vi "sex" > Retrieve.txt
acer joe [~]: sambaretrieve Retrieve.txt
[...Some lines appear, it's fetching all files...]
acer joe [~]:

The files you wanted to retrieve now are in the "files/" directory structure; hostnames have been mapped to directories, so have share names:

acer joe [~]: find files/
files/NEO/Pictures/ParisHilton01.jpg
files/NEO/Pictures/ParisHilton02.jpg
files/NEO/Pictures/ParisHilton03.jpg
files/NEO/Pictures/ParisHilton04.jpg
files/MORPHEUS/Stuff/Favorites/CommercialWithParisHilton.mpg
files/TRINITY/Funny/HiltonParisParody1.mpg
files/TRINITY/People/Hilton/Paris/01.txt
files/TRINITY/People/Hilton/Paris/01.jpg
acer joe [~]:

Broken Samba networks

Sometimes there are Samba environments with poorly configured clients - usually they're running Windows. This can result in an unbrowsable "Network Neighbourhood": every time you try to display the neighbourhood, you get some weird, stupid and most of all meaningless error message telling you you "don't have permission" to browse or that the "resource is unavailable at the moment". Well, screw them! If you know some computers by name, you can tell SambaScanner and it'll work anyways. More even: it will query the computers you supplied on the command line and will also query computers which are known to the ones you entered! Let's suppose you know there are three computers in your environment, called "NEO", "TRINITY" and "MORPHEUS", but there's a sucky Windows computer "SMITH" which ruins the master browsing feature:

acer joe [~]: sambascanner -c neo -c trinity -c morpheus

Or you can even include Smith in the search and also select what the workgroup name is that you'd like to browse:

acer joe [~]: sambascanner -w matrix -c neo -c trinity -c morpheus -c smith

This should at least be a cool workaround until the solution becomes effective (i.e. all Windows PCs have been replaced by some computers running a real OS).

Also, as of version 0.15 a new feature has been added: the scanning of whole IP segments or ranges:

acer joe [~]: sambascanner -w matrix -i 192.168.1.0/24

Would (quite intuitively) scan the whole 192.168.1.1-192.168.1.254 network, while another syntax:

acer joe [~]: sambascanner -w matrix -i 192.168.1-3.20-30

Would (also quite intuitively) scan 192.168.1.20 through 192.168.1.30, 192.168.2.20 through 192.168.2.30 and 192.168.3.20 through 192.168.3.30.

Password protected networks

As of version 0.15 the feature of trying to guess some default passwords has been added. SambaScanner now tries common combination such as "Administrator/admin", "admin/admin", "Administrator/root" by default. This feature can be deactivated with the "-a" or "--no-passwd" command line switch. Also, well-defined passwords can be tried for each host:

acer joe [~]: sambascanner -w matrix -u neo,theone -a

Which would scan the whole "matrix" workgroup using no default passwords but only tries "neo" as a username and "theone" as a password.

SambaScanner crashes/segfaults/does something stupid

If there is any unusual behaviour, please help me improve SambaScanner by sending me a coredump or an exact way to reproduce the error. Please turn on full debugging (-d 5) for this purpose and also send the temporary files created during the scanning process (to preserver those, use the -p command line switch). Really the best way to help me is first compiling SambaScanner with debug symbols/code:

acer joe [~/SambaScanner-0.22]: make clean
rm -f sambascanner
rm -f Parser.o Mutex.o Semaphore.o CommandLine.o String.o Threads.o Tools.o Processes.o IP_Range.o PremiseCheck.o
rm -f smblister semaphore_test Filelist.txt Retrieve.txt
acer joe [~/SambaScanner-0.22]: ./configure --enable-debug >> make

Then removing all temporary files from /tmp:

acer joe [~/SambaScanner-0.22]: rm -f /tmp/sambascanner*

And scanning with these options:

acer joe [~/SambaScanner-0.22]: ./sambascanner -l src/smblister -d 5 -p > out 2>&1

Then send me the following files per eMail: Coredump (if applicable), the /tmp/sambascanner* files and the "out" file. Make a .tar.gz ball out of everything beforehand, please.

SambaScanner doesn't find any files

Maybe the master browser in your network neighbourhood is broken. If that happens, first try scanning an IP-range (see above). If that doesn't work either it might be that the network is responding too slowly and SambaScanner falsely interprets the computers in question as inresponsive. Then try using the "-t"-Option which will multiply the hard-coded timeouts by a float value given on command line. To see if it has any effect, start SambaScanner with "-t 10" and see if it changes. If if does, decrease the value until you find the minimal value which works for you. If you're a developer (having halfways knowledge of editing text files should be sufficient for this purpose) you can also do the following: edit "sambascanner.h". At the bottom you see a couple of defines which define timeouts for certain stages of the scanning-process. Enlarge the "TERM" times until you get a nice result without the "-t" option. When you have optimized the values (and found out exactly which timeout causes SambaScanner to find nothing), please send them to me via eMail, so I can incorporate them into the next release.

Conclusion

For me, SambaScanner is an incredibly useful and powerful tool. Especially in combination with grep and alikes it can tremendously help you retrieve files scattered around your network. Have fun and tell your friends about it when you like it!

Warning

There was a bug with older implementations of libsmbclient which might in special cases cause some processes to hang up and hog more and more memory (until they die). This is quite unforunate, but not a problem of SambaScanner! Please do not report bugs for SambaScanner when this occours to you.

Revision History

Please do not forget to check for the authenticity of the files available for download by checking my GPG signatuture on this SHA1SUM-file.

Gentoo EBuilds

The following files are all Gentoo EBuilds which automatically install SambaScanner on your Gentoo Linux system. To use them, do the following (as root):

acer [~]: mkdir -p /usr/local/portage/net-misc/sambascanner
acer [~]: cp sambascanner-0.22.ebuild /usr/local/portage/net-misc/sambascanner/
acer [~]: cd /usr/local/portage/net-misc/sambascanner/
acer [/usr/local/portage/net-misc/sambascanner]: ebuild sambascanner-0.22.ebuild digest
[...]
acer [/usr/local/portage/net-misc/sambascanner]: cd /etc/portage/
acer [/etc/portage]: echo "=net-misc/sambascanner-0.22    ~x86" >> package.keywords
acer [/etc/portage]: emerge sambascanner
[...]

Pay attention that in the /etc/make.conf file you have set the environment variable "PORTDIR_OVERLAY" set to "/usr/local/portage". When you have tried the EBuild out (not matter wheter it did or did not work for you), please leave feedback at Gentoo Bugzilla.