INTRODUCTION

SMBSpider is a fast, lightweight search engine for indexing and browsing SMB
shares in the LAN. It features a web interface and an (optional) IRC interface
via eggdrop.

In order to install it, you need some basic UNIX knowledge; e.g. you need
to know how to edit files, set up a cron job, etc. You also need to have 
apache running with php4. SMBSpider was developed and tested under Linux,
but it should run on any UNIX where Python, PHP, and GNU grep are available.

No database is required. List files are stored in a standard format (ls -lR).


INSTALLATION

1. Put smbmounter.py in any dir of your choice (e.g. /usr/local/bin).
   smbmounter.py generates index files that the web-based search
   engine uses.

2. Edit the following variables in smbspider.py:

   WORKDIR="/home/tst/listfiles/"
    
   The main directory for smbspider (create it).

   SUBDIR="listen/"
   
   Subdirectory under WORKDIR where the actual list files
   will be located (create it, too).
   Make sure these directories can be WRITTEN by the user
   under which smbspider.py runs, and READ by the user
   under which apache runs.

   BROWSESERVER="192.168.0.75"
   
   IP of your WINS server
   
   UMOUNTCMD="smbumount"
   
   Don't mess with that, unless you know what you're doing
   (see comments in smbmounter.py)

3. Run smbspider.py manually, to check if it creates listfiles
   properly and in the right place.
   
4. Edit the crontab of the user under which you'd like to run 
   smbspider.py. For example, to update the index at 10:00,
   15:00, and 21:00, use the following line:
   
   0 10,15,21      * * *  /usr/local/bin/smbmounter.py >/dev/null 2>&1

   Then, add a line that will remove stale listfiles of servers
   that couldn't be indexed for a while (in the following example,
   seven days:
   
   0 0             * * *  find /home/tst/listfiles -ctime +7 | xargs rm >/dev/null 2>&1
   
5. Make sure you have set up apache with PHP4 support.

6. Put smbspider.php in a directory accessible via apache (e.g. /var/www)

7. Edit smbspider.php and set the following variable:

   $listfiledir="/home/tst/listfiles/listen";
   
   This must be equal to WORKDIR+SUBDIR from smbmounter.py
   
8. Copy smb-list, smb-get, and smb-search to a directory that is in the path
   of the apache user (note: /usr/local/bin isn't in the apache user's path
   on some distributions; put them in /usr/bin in that case!). 

8. Point your web browser to the URL of smbspider.php and start searching :-)


ADVANCED STUFF

Installation still wasn't complicated enough for you? There's more
waiting. In the "tools" subdirectory, you'll find cool little scripts:

1. smbstats - shell script that displays Top20 of the SMB biggest servers
   and sorts them by size, and shows number of files and amount of gigs
   on each server (mine is bigger!).
   
   Usage: edit smbstats - you just need to change the directory - and
   run it.

2. newdirs - shows newly created directories of today and yesterday,
   so that you can keep track of what content has recently been added
   to your LAN.
   Edit newdirs - just change the directory, then you can run it.

3. smbsearch - quick search for _directories_ from the shell
   Again, edit the script and change the directory to your list file dir.
   Usage: smbsearch <keyword>
   
4. IRC interface via eggdrop, for the _real_ nerds
   (I'll keep the instructions short here, since newbies usually
   don't run eggdrops ;)):
   
   Edit the "set binary" lines in smbsearch.tcl to point to
   the locations of smbstats / newdirs / smbsearch. Replace #samplechan
   by the chan to which you want the bot to report stuff.
   
   Then, install smbstuff.tcl in your eggdrop (edit config, .rehash).
   It will then respond to the following commands: !smbstats !newdirs
   and !smbsearch <keyword>
   
5. Compability with FileArchiveSearch (http://www.t-st.org/fas/)
   List files (which are nothing else than ls -lR piped to a file) are
   compatible between SMBSPider and FileArchiveSearch. You can mix them
   and use a combined index.

FULL INDEX SEARCH "ONLY FOR VIPs"

Make the complete index searchable only to VIPs, while all the others
can only search the boring servers with little content:

1. Put private_shares in /etc, and edit it. Each line stands for one smb
   share that should be searchable only by VIPs.
   The syntax is HOSTNAME_sharename.
   For example, to make the share "secretstuff" on the server "PARANOIDGUY"
   searchable only for VIPs, add a line:
   PARANOIDGUY_secretstuff

2. Create a dir for the listfiles searchable by everyone, e.g.
   /home/tst/listfiles/listen-public

3. Configure smbspider.php to use this list file dir

4. Create an additional dir under /var/www (or whereever), and put smbspider.php
   there, too. This time, configure it to use /home/tst/listfiles (where the
   complete listfiles are).
   
   Copy the sample_htaccess to this dir, and rename it to .htaccess
   Edit it and add the IPs of VIPs who can search the full index.
   
5. Put the script "copypublic" somewhere, and edit it to match
   your listfile directory configuration.
   
6. Edit your crontab again, so that copypublic is executed a while
   after smbmounter.py, and then copies the listfiles of those shares
   who shouldn't be searchable by everyone to the listen_public (or how
   you called it) dir.

7. Give the URL of the smbspider.php with the .htaccess to the VIPs, let
   the others use the regular smbspider.php.
  
Concerning the "only for VIPs" feature, I agree that this isn't solved as
elegantly as it could be, it's just a fast hack, but it works...


SECURITY

SMBSpider takes user input and passes it as command line arguments
to shell scripts. This is insecure by concept. Reasonable care has been
taken to avoid the usual issues. Still, do not run smbspider in untrusted
environments.

You should really make sure people outside your LAN don't have access
to smbspider, unless you really know what you're doing. 
Remember that smbspider comes with NO WARRANTY.
Use common sense. And don't do anything illegal :)

BUGS?

Please send bug reports to mail@tillmann-steinbrecher.de.
SMBSpider has been tested for around two years in a private environment
prior to this release, and has proven to be stable. 

If you have problems with list files not getting parsed properly,
try setting LANG=C before running smbmounter.py.

As far as the "advanced" scripts are concerned, I'd rather consider
these as toys, they haven't been tested much, but they do work well so
far.

CREDITS & COPYRIGHT

smbmounter.py was written by Ian Hubbertz (http://www.hubbertz.de/ian.html)
smbspider.php was written by Tillmann Steinbrecher, and is heavily based on
FileArchiveSearch, my CD/DVD catalog search engine
(http://www.t-st.org/fas/).
Maybe some day I'll merge smbspider and FAS to one program. 

The little scripts in the tools dir were also hacked together by me.

Everything may be distributed according to the GNU GPL, Version 2.

All the best,
Tillmann