Getting started with gnut:
by: Elijah <eli@panix.com>
with additions by Robert Munafo <mrob@mrob.com>

QUICK START

(It is assumed you have already built/installed gnut. If not, read the
file "DEPEND")

Before you can run gnut for the first time you need a .gnut_hosts
file. Try going to one of these sites:

  http://gnutella.wego.com/
  http://gnutella.co.uk/servers/
  http://gnutelliums.com/

and look in the "downloads" or "files" area for a GNUTELLA.txt file.
Save this file as ~/.gnut_hosts

If you can't find the file, you can start gnut without a .gnut_hosts
file, and connect to one of the "host cache" or "host servers" like
gnutellahosts.com:6346, router.limewire.com:6346 or gnet1.ath.cx:6346
by typing the command "open gnet1.ath.cx:6346", then after the
connection is open (use "info" to find out), type "update" to send a
request (called a "ping") for host addresses. After you do this, use
"info" again to make sure the "HOST STATS" have a number bigger than
0. As soon as you quit gnut, it will save the host list as
~/.gnut_hosts and you're all set.

To see if you're connected, use the 'info' command; repeat until you
see some connections that say "UP" or "OK" (not "CONN" which indicates
an attempt in progress). Then use the 'monitor' command and see what
other people are searching for. If you don't see any results within a
minute or two you have a problem: maybe the seed addresses are all
bad? This might happen if your .gnut_hosts file is really old or if it
only contained a small number of lines.

If you're behind a firewall, it has to be the kind that allows direct
connections. If you have Netscape set to "manual proxy" or "automatic
proxy", or if you have MSIE set to use proxy servers (both are in the
"proxies" section of the browser's preferences) you'll probably have
trouble running any Gnutella client.

FILE TRANSFER

Once you have established that you are connected, you can either share
some files or search for some.

To share everything in /my/cool/files/:

    gnut> share /my/cool/files
    gnut> scan
	
To search for cphack:
	
    gnut> find cphack

or:

    gnut> search cphack

Immediately you will see:

    Searching the gnutella network for: cphack
    press any key to continue
    0 results received.

You can watch the numbers go up and press a key when you want to type
another command. The numbers keep going up even after you press a key.
To see the search results, type "search" or "find" with no argument,
or type "response":

    gnut> find
    CURRENT RESPONSES
    -----------------
    1)cphack.exe
      10.23.45.18:6346    size: 188416  ref: 413    speed:1024
    2)cphack.zip
      172.24.1.217:6346   size: 185234  ref: 12     speed:56

To download the first of them:

    gnut> get 1
    
The download will happen in the background.  Use "into t" to monitor:

    gnut> info t
    TRANSFER_STATS
    --------------
    1)10.23.45.18:6346  6.1%        11495/188416 bytes 0.8 k/sec
      TID: 9224    IN   State: UP   Name: cphack.exe
      
When the state turns to "DONE" the download has stopped.  If the percentage
downloaded was "100.0%", you are done.

FILTERING SEARCH RESPONSES

The response section can get very large for some searches. As of
version gnut-0.3.20 responses can be narrowed with a regular
expression. To do this you need to use the 'response' command with
the regular expression as an argument. Starting with version 0.3.24
there are two forms of the command:

    response reg-exp
    response /reg-exp/options

If you just want a bare regular expression (case-insensitive, if possible)
the first form is for you. If you want to change an option, the second
form is needed. Current options:

    /i  ignored since case-insensitive is default
    /I  make search case-sensitive
    /v  invert matching (print only those that don't match)

An example of this is:

    gnut> search USA

    gnut> search           - you'll get a lot because the search
                             is not case-sensitive

    gnut> response /USA/I  - to see only those with uppercase 'USA'

The code tries to use the POSIX regcomp() function, and fails back to
re_comp() if that does not exist. re_comp() doesn't support a case-
insensitive flag, so a warning is printed if you try to use it.
regcomp() can do extended regular expressions. If you're on Win32, you
just get a simple keyword search.

MONITORING

Monitoring is a nice way to find out what other people are interested
in. There are three monitoring commands: "monitor", "mreply", and
"mpush". "monitor" is the familar search monitor: it shows other
people's search strings. "mreply" is more interesting because it shows
their search results: names of files that are out there on the
network. "mpush" shows which files are actually being requested, but
it doesn't show very much because it only sees push requests, and
those are fairly rare.

WEB (HTTP) INTERFACE

If you have a gnut running on your machine, you automatically have a web
server running too. To see it from your own machine, point your browser
at

    http://127.0.0.1:5634/

(or change '5634' to your local port number). You should see a simple
web page with the words "Gnutella client web search" near the top.
The files shared by your gnut appear in a list below; click on one
to download it to your machine.

Others can connect to your gnut, too. They'll have to put your
IP address in place of "127.0.0.1" in the URL.

You can also do a search through the gnut web interface. This will
actually search through the remote server -- that is, the remote
machine running gnut does a search, and returns a list of file results
on other remote machines. To start a search, go to:

    http://127.0.0.1:5634/search/

(once again, replace "127.0.0.1:5634" with the real IP address and
port number of the machine running gnut)
