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:

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:

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:

Date: Tue, 20 May 2008 22:08:19 +0800 (WST)
From: David Adam <Withheld>
To: Johannes Bauer <Withheld>
Subject: SambaScanner on FreeBSD

Hi Johannes,

I was trying to build SambaScanner 0.22 on FreeBSD 6.3, and discovered the configure script needs a little coaxing to compile everything properly on FreeBSD. Dunno why, I would have thought autotools handles all this sort of thing.

It needs to be run as CFLAGS=-I/usr/local/include LDFLAGS="-L/usr/local/lib" LIBS="-lintl -lpthread" ./configure

Also, libsmbclient can be installed with "cd /usr/ports/net/samba-libsmbclient && make install clean" though most FreeBSD users will know this.

[...]

Oh, and one more thing - in i18n/Makefile.am, the -D flag to install(1) is invalid on FreeBSD: I think the flag you want is -d but annoyingly that means something different in GNU install(1).

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 [~]:
Or, on older version, this:
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.

Version Changes Date
0.22
Download Source Code
  • Code cleanups
  • Changed structure of ProcessTable to use memory more efficiently
  • Fixed a bug which would cause SambaScanner to deadlock when processes executed in a very short period of time. This bug became visible as the improved structure of the ProcessTable increased performance and task execution times became lower
  • Removing duplicate hostnames/IP-Adresses
  • Restructured Hostlist
  • Fixed a small race condition in ProcessTable which might lead to a segmentation fault primarily on SMP systems
  • Added support for database frontend
  • Added automatical testcases
  • Added support for parsing configuration files (~/.sambascannerrc)
2007-10-29
0.21
Download Source Code
  • Fixed two tiny problems with uninialized memory
  • Sharelist and Hostlist are exportable by parameter
  • Incorporated patch by Ash Milsted which adds two command line paramers disallowing SambaScanner to make use of the Netbios name of hosts and another one disallowing SambaScanner to harvest discovered master browsers for other hosts
  • SambaScanner now definitely requires NPTL, as the LinuxThreads method of handling async signals and threads is just plain broken
2007-06-08
0.20
Download Source Code
  • IP patterns now omit the first and last address in subnet notation, as these are the network and broadcast address (e.g. in 192.168.1.0/24 now only 192.168.1.1-254 get scanned instead of 192.168.1.0-255)
  • When scanning an IP range the IP address also becomes part of the filelist
2007-04-30
0.19
Download Source Code
  • Fixed a bug when linking libsmbclient which was compiled with LARGEFILE-support and compiling SambaScanner without LARGEFILE-support (segfault on x86_32)
  • Fixed a bug which occoured when a thread was preemted right after termination of the process (removed out of ProcessTable too soon)
  • Introduced ADT (abstract data type) ProcessTable, which grants uniform, reentrant and thread/async-signal-safe access on the process list
  • Changed to autoconf/automake build system
  • Introduced a new debuglevel which gives incredibly verbose output
  • Destruction of Mutexes (saving of resources)
  • Tiny memory leak in smblister fixed
  • Changed removal of child processes from a polling thread to sigwait (signalling)
  • Changed polling in WaitFor-Function to condition variable
2007-04-28
0.18
Download Source Code
  • All threads are now started in detached state, this saves memory and fixes a bug which was caused when a lot of threads were being used (about 400)
  • More conservative timings for slow networks
  • Smblister now displays mtime and file size
  • Localization to German
  • sambaretrieve now retrieves to sane file permissions, additional sanity checks implemented
2007-04-20
0.17
Download Source Code
  • Actual share name is not written to filelist
  • Does not scan print$-shares by default now
  • Fixed a bug which would randomly (uninitialized memory) cause shares to be tried with username/password combinations
  • Improved debugging options
  • Added some sane error messages when the tools couldn't be found or the tmp-directory wasn't writeable (instead of creating an empty output file)
2007-04-17
0.16
Download Source Code
  • Modified Makefile and ebuild-file to comply to Gentoo Sunrise standards
2007-04-16
0.15
Download Source Code
  • Scanning of IP addresses, whole subnets or IP address ranges now available using the '-i' option
  • Fixed a problem with leaking file descriptors
  • Fixed a memory overwriting bug which occoured when there were MANY hosts being found in the host discovery state
  • Fixed a bug in the StringExists function which would not detect a duplicate string if the duplicate was at position 0
  • Fixed a bug in smblister which would only traverse the root directory
  • Added the functionality of trying some default passwords
  • Added the functionality of specifying usernames/passwords manually
  • Fixed a silly bug which would cause success/error count to never increase
2007-04-16
0.14
Download Source Code
  • No more known bugs!
  • Cosmetic fixes in Makefile to comply with the Gentoo standards
2006-10-14
0.13
  • GPL header in every file
  • Cosmetic fixes in helpfile
Was never released
0.12
  • Now kills a process only if it doesn't received enough input for a certain while (not just solely based on the time running)
  • Fixed a race condition of stdout vs. stderr which sometimes used to clobber the output file
  • Rewrote semaphore implementation
  • Rewrote stringlist implementation
  • Fixed the VERY STUPID implemenation of waiting for remaining threads and replaced it by a semaphore-based concept
  • Major code cleanup
  • New Makefile
  • Added option to preserve tempfiles
  • Fixed a VERY unlikely-to-happen race condition by introducing the mutex "NumberMutex", which protects access to Hostlookup_Processes_Failed and Hostlookup_Processes_Succeeded
Was never released
0.11
  • Fixed a bug where processes would immediately get a SIGKILL instead first getting SIGTERM
  • Cleanup of option parsing
  • Correct calculation of term/killtime
  • KNOWN BUG: Sometimes enters the PID of the great parent into joblist, tries to kill it at some point in time
  • KNOWN BUG: Sometimes hangs itself up when trying to send SIGTERM to a process which is not in the list anymore
Was never released
0.10
  • Half-written files from aborted scannings now don't produce broken lines in the output file anymore
  • Small tweaks in the buffer size given to the fgets(3) call
  • Declared global variables static
  • Stupid deadlock fixed when parsing command line arguments
2006-06-28
0.09
Download Source Code
  • Memory leaks fixed
  • Replaced obsolete ftime(2) by newer gettimeofday(2), so it should work using OpenBSD again
2006-05-01
0.08
Download Source Code
  • Fixed a stupid bug which would sometimes cause SambaScanner to abort the waiting process, although they weren't done yet -> this caused sometimes the output files to be corrupt and temp files remaining in the system
  • Fixed another stupid bug where NetBios names were treated as case sensitive names, although they are in fact not
  • Added the command line parameter -r which allows to specify how many threads should be used during the scanning process (default is 30)
2006-04-24
0.07
Download Source Code
  • Added option to specify a computer on the network explicitly. This is useful when due to the crappy nature of the SMB/CIFS protocol there is currently no master browser available, which could automatically be detected.
  • Minor bugfixes
2006-03-12
0.06
Download Source Code
  • Changed license (only GPL-2, not any later versions)
  • Fixed a silly bug where sambascanner would segfault
  • Added the outfile-option
  • Improved output
  • Workaround for stupid behaviour of newer samba versions concerning debug output (debug level always set by smb.conf)
  • Made the retrieve-script more user-friendly and changed name to sambaretrieve
  • First submission of an ebuild to the Gentoo Portage tree
2005-09-02
0.05
  • Introduced ChangeLog ;-)
  • First publication
2005-06-03

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.

Version Date
0.22
Download Gentoo Ebuild
2007-10-29
0.21
Download Gentoo Ebuild
2007-06-08
0.20
Download Gentoo Ebuild
2007-04-30
0.19
Download Gentoo Ebuild
2007-04-28
0.18
Download Gentoo Ebuild
2007-04-20
0.17
Download Gentoo Ebuild
2007-04-17
0.16
Download Gentoo Ebuild
2007-04-16
0.15
Download Gentoo Ebuild
2007-04-16
0.14
Download Gentoo Ebuild
2006-10-14
0.10
Download Gentoo Ebuild
2006-06-28
0.09
Download Gentoo Ebuild
2006-05-01
0.08
Download Gentoo Ebuild
2006-04-24
0.07
Download Gentoo Ebuild
2006-03-12
0.06
Download Gentoo Ebuild
2006-01-16