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 "INSTALL")

When you run gnut for the first time it tries to connect to the host
cache sites. However, if this doesn't work, gnut won't be able to
connect to anything until you get 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) then you do not have
direct connection ability and you will not be able to use *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  speed: 1024 rating: ***.
    2)cphack.zip
      172. 24.  1.217:6346 size: 185234  speed:   56 rating: **

Notice the rating. Each file will have up to 4 stars indicating how
good that server is estimated to be. Ratings incorporate the server's
speed, availability, and performance on previous downloads by other
users.

To download the first file:

    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.

LIMITING SEARCH RESULTS

You can tell gnut to only search for files of a certain type:

    gnut> set search_extensions jpg

You can tell gnut to only find files larger than a certain size (1
Mbyte in this example):

    gnut> set search_min_size 1000000

Perhaps most useful of all, you can filter by host rating:

    gnut> set search_min_rating 64

('64' specifies two stars or more. See the manual chapter 4 for more
details about ratings and scoring)

FILTERING SEARCH RESPONSES

The response section can get very large for some searches. 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:

    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.

THE forget COMMAND

You can also filter out search results with the 'forget' command.
This is used to eliminate things you don't want. For example, if you
searched for 'apple pie', you might get some matches that are called
'apple-rhubarb pie'. You can then eliminate those responses with the
command:

    gnut> forget rhubarb

THE .gnutrc FILE

You can put gnut commands in a file ".gnutrc" in your home directory.
These commands will get executed every time you start gnut. Some
useful commands to put in hare are the 'share' and 'scan' commands
described above, and the 'set' commands to set your gnut options.
Learn more about all the options you can set in chapter 4 of the
manual.

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 files that 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://12.34.56.78:1011/search/

(here, you should replace "12.34.56.78:1011" with the real IP address
and port number of the machine running gnut)

Please note that almost all servers (including BearShare and LimeWire)
refuse to serve files to users who are using a web browser.
