<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN">

<!--

$Id$

Document style
==============

  Lines should be wrapped at no more than 80 characters and should end
  in a space to ease reformatting.

  Sentences should end in two spaces, even at the end of a line or
  paragraph.  This makes it easier to automatically recognize
  sentences.  Use double quotes (""), not single quotes (''), so
  contractions don't confuse syntax highlighting editors.

  Certain terms should always be written the same way to facilitate
  future search and replace operations:

  gtk-gnutella - should not be abbreviated or capitalized, even at the
  beginning of a sentence.

  Avoid acronyms, for the most part.  Use "Internet service provider"
  rather than "ISP" and "local area network" rather than "LAN".  It
  doesn't really matter which we use, as long as it's consistent.  The
  more rigidly consistent we are, the more flexibly we have for future
  search and replace if we change our minds.  So look at the
  previously written docs for precedence.

  When describing UI elements, use the exact spelling and
  capitalization as they appear.

  Avoid just restating the tool tips.  The tool tips in gtk-gnutella
  are excellent but if the user doesn't understand them, it does no
  good to repeat them in the documentation.

-->
    
<book>
<bookinfo>
  <title>gtk-gnutella manual</title>

<authorgroup>  
  <author><firstname>Hans</firstname><surname>de Graaff</surname></author>
  <author><firstname>Bill</firstname><surname>Pringlemeir</surname></author>
</authorgroup>

  <copyright><year>2002</year><year>2004</year>
    <holder>Hans de Graaff</holder>
    <holder>Vidar Madsen and Markus Goetz</holder>
  </copyright>
  <copyright><year>2007</year>
    <holder>Bill Pringlemeir</holder>
  </copyright>

</bookinfo>

<preface id="FORWARD">
  <title>Foreword</title>

  <para>gtk-gnutella is under active development.  This manual will
  always lag behind.  You may find discrepancies between this document
  and gtk-gnutella.  Hopefully, concepts are explained in a way that
  applies to future versions.  As time permits we will add additional
  text to update and expand the manual, but please feel free to
  contribute new sections and updates if you like.  Information on
  contributing can be found at <ulink
  url="https://gtk-gnutella.sourceforge.io/"/></para>

</preface>

<part id="GETTING_STARTED">
<title>Getting started</title>

<chapter id="NETWORK_INTRO">
<title>Network Introduction</title>

<para>gtk-gnutella is a servant on the Gnutella peer-to-peer
network. In order to make the most out of gtk-gnutella it helps to
understand a bit about peer to peer networking in general, and the
Gnutella network in particular.</para>

<sect1>
<title>Peer to peer</title>

<para>The concept of a peer to peer network is that each participant
in the network has the same level of rights in the network. Everyone
is equal, no one is unique, and everyone can be missed without
jeopardizing the network.</para>

<para>To make this possible each participant has the full
functionality needed to create the network. Any two participants
together can create a fully functional network. To realize why this is
special consider how information is normally distributed on the
Internet.

</para>

</sect1>


</chapter>

<chapter id="GETTING"><title>Installation</title>

<section><title>Getting gtk-gnutella</title>

<para>The easiest way to get gtk-gnutella is to install it as part of
your distribution. Most distributions carry gtk-gnutella pre-packaged
these days. This is not always the best option, though. Since the
Gnutella sometimes undergoes significant change, and since buggy
clients may cause many problems to the Gnutella network, gtk-gnutella
clients are coded with a maximum lifetime. After a pre-determined
period gtk-gnutella will start to complain and eventually will stop
working. Distributions are not always quick to pick up new versions
because stability is important to them, so you may be installing a
version of gtk-gnutella that is close to or already past its limited
lifetime. This is true in particular if you install from offline media
such as DVD.</para>

<para> Some web sights offer gtk-gnutella packages.  <ulink
url="http://rpmfind.net/linux/rpm2html/search.php?query=gtk-gnutella">
RPM find </ulink> and <ulink
url="http://linuxappfinder.com/package/gtk-gnutella"> Linux App finder
</ulink> have packages for some popular Linux distributions.  Also,
the <ulink url="https://gtk-gnutella.sourceforge.io/"> gtk-gnutella
</ulink> web site may contains some packages. </para>

<para>A better way to get gtk-gnutella is to install it yourself. The
<ulink url="https://gtk-gnutella.sourceforge.io/"> gtk-gnutella
</ulink> web site contains the source archive which allows you to
compile gtk-gnutella yourself. You can also use the web site to check
if your currently installed version is still the most recent version;
gtk-gnutella will also notify you if it sees a newer version on the
gnutella network. </para>

</section>
</chapter>

<chapter id="FIRSTTIME">
<title>First start</title>

<para> gtk-gnutella is abbreviated as GTKG for short. </para>

<section> <title>GUI overview</title>

<para> A document called "Gnutella for users" is available on the
Internet. <ulink url="http://en.wikisource.org/wiki/GnuFU"> GnuFU
</ulink> and also <ulink
url="http://basis.gnufu.net/gnufu/index.php/GnuFU_en"> GnuFU
</ulink>. </para>

<para> The <link linkend="gtkg-diagram"> figure </link> below labels
the areas of the gtk-gnutella screen.  In most cases, menu items, context help
and other documents will also use the same names to refer to these
areas.  This is for the GTK2 version of the program.  The GTK1 program
may locate the status icons in the status bar.</para>

<figure id="gtkg-diagram"><title>gtk-gnutella Screen Areas</title>
<screenshot>
<graphic width="784" depth="600" fileref="images/gtkg-diagram"></graphic>
</screenshot>
</figure>

<para> The mid-section of the screen is divided in two.  To the left
is the side bar.  The side bar contains a navigation tree, a search
list, and gnutella status information.  To the right is the "working
area".  This changes depending on the current activity. The following
table gives a short summary of each area.  These are covered in more
detail in the following sections. </para>

<para>
<informaltable>
<tgroup cols='3' align="left">
<colspec colname="c1" colwidth="1*" />
<colspec colname="c2" colwidth="3*" />
<colspec colname="c3" colwidth="11*" />
<spanspec spanname="hspan" namest="c1" nameend="c2" align="left" />

<thead><row><entry>Area</entry>
<entry>Sub-Area</entry>
<entry>Short Description</entry></row>
</thead>
<tbody>

<row><entry spanname="hspan">Menu</entry> <entry>The menus are File,
Transfer, Search, View and Help. Each menu has several entries that
change the working area, bring up the preferences dialog, or alter the
screen configuration. </entry> </row>

<row><entry spanname="hspan">Status Icons</entry> 
<entry>Icons include CPU overload, file copying, library SHA, download
SHA, library building, firewall and GnutellaNet status. Icons may change
according to current conditions</entry> </row>

<row><entry spanname="hspan">Search Bar</entry> 
<entry>Contains a text field for entering new search criteria.  Also
contains a drop-down filter selection button, and search and passive
search buttons. </entry> </row>

<row><entry spanname="hspan"> Working Area</entry>
<entry>This area changes depending on your current activity.  It is
one of the following nine items. </entry></row>

<row><entry morerows="8" /><entry colname="c2">GnutellaNet
Connections</entry> <entry>This shows detailed information about all
nodes directly connected to gtk-gnutella.  Various flags are shown as well as
the type of client, location, etc. </entry></row>

<row><entry colname="c2">GnutellaNet Statistics</entry> 
<entry>This working area has tabs along the top.  Statistics
relevant to the currently selected tab are shown.</entry></row>

<row><entry colname="c2">GnutellaNet Hostcache</entry> <entry>This
area manages previously seen hosts seen on gnutella.  Having a full
host cache allows quicker connection to the GnutellaNet when starting.
These entries are also relayed to other nodes to help them connect to
gnutella.</entry></row>

<row><entry colname="c2">Downloads</entry>
<entry>When downloads are the active working area, a list of all
downloads is shown.  Details on the currently selected download are
shown at the bottom of the working area. </entry></row>

<row><entry colname="c2">Uploads</entry>
<entry>This working area shows files being sent to other gnutella
nodes.</entry></row>

<row><entry colname="c2">Upload History</entry>
<entry>This working area show previously sent files (or partially sent
files).</entry></row>

<row><entry colname="c2">Search Results</entry>
<entry>Gives all results found for the selected search.  The search is
selected via the "search list" or by using the "Current search"
selection button.  Any of the search results can be scheduled for
downloading.</entry></row>

<row><entry colname="c2">Search Monitor</entry>
<entry>Shows searches passing through our node.</entry></row>

<row><entry colname="c2">Search Stats</entry>
<entry>Statistics about where searches are coming from etc.</entry></row>

<row><entry spanname="hspan">Side bar</entry>
<entry> The entire side bar can be hidden with the "F8" key or using
the "View|show Sidebar" menu.  The side bar contains the following
three items.  </entry></row>

<row><entry morerows="2" /><entry colname="c2">Navigation Tree</entry>
<entry>An alternate to using the menu to change gtk-gnutellas working area.
This (and most items) can be disable by using the "View"
menu. ("View|show Navigation Tree").</entry></row>

<row><entry colname="c2">Search List</entry>
<entry>Lists gtk-gnutella searches. Greyed values are inactive.  Clicking on
an item changes the working area to show that search.</entry></row>

<row><entry colname="c2">GnutellaNet Status</entry>
<entry>Graphical summary of the GnutellaNet status.</entry></row>

<row><entry spanname="hspan">Status bar</entry> 
<entry>Contains messages from time to time.  Also contains estimates
of connected nodes, available files, size of all files and up time. A
button at the bottom left can disconnect from gnutella while leaving gtk-gnutella
running.  Current downloads and uploads will complete. </entry></row>

</tbody></tgroup></informaltable>
</para>


<para> When first run, gtk-gnutella will be very busy trying to
connect to the GnutellaNet for the first little while.  When three
nodes are found, gtk-gnutella is fully connected to the network.  The
GnutellaNet Status will show "3/3 connections". If this does not
happen after several minutes, gtk-gnutella might be having problems seeing the
Internet.  You will have to consult the <link linkend="NETWORKING">
Network troubleshooting </link> chapter.</para>

<para>There are also two dialog screens.  Once is under the File menu
and is named <link linkend="SETTINGS"> Preferences </link>.  This is a
tabbed dialog that allows gtk-gnutella to be configured.  There are many
options in the preference dialogs. The other dialog allows you to
build <link linkend="FILTERING"> filters </link> to improve search
results.</para>

<section> <title>gtk-gnutella activities</title>

<para> There are several distinct activities that you can perform with
gtk-gnutella.  A required activity is getting connected to gnutella.  Once
this is configured properly for your little section of the Internet,
gtk-gnutella will take care of this for you with little or no attention.
However, when you first use gtk-gnutella, it can be rather daunting to get
proper network connectivity.  The good news is the gtk-gnutella can work
partially even with limited network connectivity.  If the status icon,
second from the left, has a smiley face with sun-glasses, then you are
in good shape! <graphic width="32" depth="32" fileref="images/no_firewall"/></para>

<para> There are several variation of the "firewalled" icon.
Firewalled is a mis-leading term.  It actually means that gtk-gnutella is not
detecting good connections to the rest of the GnutellaNet.  It is ok
to continue with this icon, if you have connections showing in the
GnutellaNet Status area (ie. "3/3 Connections").  <graphic
width="32" depth="32" fileref="images/firewall"/> </para>

<para> Another task that gtk-gnutella helps you with is finding files.  This
is called "Searching".  There are all kinds of people connected to
gnutella with different purposes.  Some people are spreading spam, spy
ware and viruses.  Some people are mis-labelling files.  Some people
mistakenly or purposely share corrupted files.  gtk-gnutella has a very
powerful filter mechanism that can help to reduce the number of the
bad files found in a search.  gtk-gnutella also has some built-in features to
reduce the amount of spam and other bogus files.</para>

<para> From the search screen, you can highlight a result and use the
"Download selected" button to start downloading.  The download screen
will show you all files that you are downloading and the progress each
has made. </para>

<para> Ok, so maybe you wonder where all the files come from?  This is
the last major activity that gtk-gnutella facilitates.  It allows you to share
your files for others to download.  This takes some care as you might
have some information that you wish to keep private.  By default, gtk-gnutella
will share anything downloaded.  These files are generally in
"~/gtk-gnutella-downloads/complete".  Some people will disconnect you
if you don't share anything (or very little).  Of course, if you live
somewhere where you afraid of getting sued, you might not share so
much.  There is nothing wrong with sharing files that do not have
restrictions; manuals like this one for instance.</para>

</section>

</section>
</chapter>

<chapter id="SEARCHING">
<title>Searching for files</title>

<para> There are three different items in the Search menu.
"Search|Results" displays searches that you initiate in the working
area.  "Search|Monitor" and "Search|Stats" are for examining all
searches passing through our section of the GnutellaNet.</para>

<section> <title>Search results</title>

<para> Identifying what to download is a major task in any peer to
peer network.  This is especially true with all sorts of people
filling the network with garbage.</para>

<para>Searches are initiated in the search bar.  You type in text that
you wish to search for.  An active search is then started by pressing
the button to the left called" search".  This button will scour
gnutella and try to find file matching your text. </para>

<para> The "passive" search is an alternate method of finding files.
Passive searching monitors other active searches that flow through
your computer.  You can use it in leaf mode, but you will have to have
other active searches running at the same time to get results. This
can actually be very useful.  </para>

<para> What is "leaf mode"?  In the menu bar, at the top right of the
screen are the status icons.  The icon to the far right is either a
"leaf" or a "ultrapeer" icon.

<informaltable>
<tgroup cols='2'>
<tbody>
<row>
<entry><graphic width="32" depth="32" fileref="images/leaf"/> Leaf icon</entry>
<entry><graphic width="32" depth="32" fileref="images/smallserver"/> Ultrapeer icon </entry>
</row>
</tbody></tgroup></informaltable>
</para>

<para> A leaf node only connects to a few ultrapeers.  The ultrapeers
connect to many leaves and other ultrapeers.  For the most
part, searches will flow through node connections.  For this reason,
you will get many more passive results if you are an ultrapeer.
</para>

<para> The other item that determines search results is the filter
used.  This is a drop-down button to the left of the search edit box.
You can use filters with either active or passive searches.  It can be
useful to run an active search with a filter and a passive search with
no filter.  Comparing the two helps figuring out what is
filtered. </para>

<para> The search results display several columns of information.  The
results can be sorted by column.  Delete results results by selecting
them and using the delete key.  Groups of results can be deleted by
using the mouse and the control or shift key.  This can make it easier
to decide which of several results to download as you don't have to
scroll through many different items. </para>

<figure><title>gtk-gnutella Searches</title>
<screenshot>
<graphic width="623" depth="542" fileref="images/search"/>
</screenshot>
</figure>

<para>
There are many <glossterm
linkend="search_prefixes">prefixes</glossterm> that can be added to
specialize a search.  <glossterm
linkend="search_literals">Literals</glossterm> and <glossterm
linkend="search_required">required phrases</glossterm> also have
special notations.

</para>

<para>

Results are categorized by color in the search result list.  The
following table gives a description of what the different colors mean.

<informaltable>
<tgroup cols='2'>

<thead> <row>
  <entry>Text Color  </entry>
  <entry>Description </entry>
 </row>
</thead>
<tbody>
<row>
  <entry>Black         </entry>
  <entry>The default color representing a normal search result.   </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#7f0000"?><?dbfo 
   bgcolor="#7f0000"?>Dark red       </entry>
  <entry>This result is most definitely spam.  These results may never be displayed depending on your configuration.   </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#FC000D"?><?dbfo 
   bgcolor="#FC000D"?>Bright red  </entry>
  <entry>The result is probably spam.  </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#001F7F"?><?dbfo 
   bgcolor="#001F7F"?>Blue  </entry>
  <entry>A user filter has marked this result.  </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#326732"?><?dbfo 
   bgcolor="#326732"?>Green  </entry>
  <entry>The file is currently being downloaded.  </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#7F7F7F"?><?dbfo 
   bgcolor="#7F7F7F"?>Gray  </entry>
  <entry>This result was ignored.  </entry>
</row>
<row>
  <entry><?dbhtml bgcolor="#5F007F"?><?dbfo 
   bgcolor="#5F007F"?>Indigo  </entry>
  <entry>The result came from a hostile host.  </entry>
</row>
<row>
  <entry>Marroon <?dbhtml bgcolor="#7E5029"?><?dbfo 
   bgcolor="#7E5029"?> </entry>
  <entry>These result were unrequested and delivered via OOB.  They are possibly spam. </entry>
</row>
</tbody></tgroup></informaltable>
</para>
</section>

<section id="BITZI"> <title>Bitzi and Magnet links</title>

<para> An alternative to searching with gtk-gnutella is to use a web site like
<ulink url="http://bitzi.com">Bitzi</ulink>, <ulink
url="http://www.magnetmix.com"> magnetmix </ulink> , or <ulink
url="http://www.freebase.be/"> Freebase </ulink>.  These sites have
web search capabilities and descriptions of files with magnet links.
A magnet link is just text that gtk-gnutella can understand (a URI in computer
parlance).  Magnet links can be copied to IRC and other chat programs,
sent in emails, posted to Usenet groups or put on your own web
site. Paste the magnet link to the gtk-gnutella search box and gtk-gnutella 
will start to download the file as soon as a source is found.</para>

<para>If you use a Mozilla based browser (Mozilla, Firefox, SeaMonkey,
etc), you can configure the browser to have gtk-gnutella handle magnet
links.  You need to have a script like the one below, </para>

<para><informalexample><programlisting>
#! /bin/sh

# Id: magnet-handler.sh 14334 2007-08-06 13:11:29Z cbiere 

# The following two options should be set in FireFox/Mozilla.
# Enter &quot;about:config&quot; in the address bar.
# Right click and create a new string under the name
# &quot;network.protocol-handler.app.magnet&quot;.  Set the value to the
# full path to this script.  Also create a new boolean called
# &quot;network.protocol-handler.external.magnet&quot; and set it to true.
# This script should have execute permissions.  Ie, chmod +x.

# Make sure that there is only one argument and that it starts
# either with &quot;magnet:?&quot; or &quot;http://&quot;.

scheme=
case &quot;$1&quot; in
'http://'*)	scheme='http';;
'magnet:?'*)	scheme='magnet';;
*)
esac

if [ $# != 1 ] || [ &quot;X$scheme&quot; = X ]; then
   echo &quot;Usage: ${0##*/} magnet:?[...]&quot; &gt;&amp;2
   exit 1
fi

# Select a default configuration directory.  FireFox/Mozilla can be
# run with alternate exports to over-ride behaviour in this script.
GTK_GNUTELLA_DIR=${GTK_GNUTELLA_DIR-$HOME/.gtk-gnutella}
export GTK_GNUTELLA_DIR

# Don't do anything if GTKG is not running.
gtk-gnutella --ping || {
   echo 'gtk-gnutella is not running.' &gt;&amp;2
   exit 1
}

# Special characters in the URL must not be parsed as quotes or escapes.
url=&quot;`printf '%s' &quot;$1&quot; |sed 's,&quot;,%22,g' |sed &quot;s,',%27,g&quot; |sed 's,\\\\,%5c,g'`&quot;

# Send a shell command to download the magnet URL.
cat &lt;&lt;EOF | exec gtk-gnutella --shell
intr
download add &quot;$url&quot;
EOF

</programlisting></informalexample></para>

<para>
To use the script, type "about:config" in the address bar of the
browser.  Right click and create a new string under the name
"network.protocol-handler.app.magnet".  Set the value to the full path
and name of the script.  Also create a new boolean called
"network.protocol-handler.external.magnet" and set it to true.  This
script should have execute permissions.  Ie, chmod +x.  An up to date
version of this script is in gtk-gnutella source in the scripts
directory.  When the script is active, clicking on a magnet link in
the browser will automatically start a download in gtk-gnutella.
</para>

</section>

<section id="SEARCH_MONITOR"> <title>Search "Monitor"</title>

<para> The search monitor allows you to see what other people on the
GnutellaNet are searching for.  It is certainly instructive to do this
once or twice just to see what can be seen.  It can be entertaining if
you are bored.  Don't do it for too long though, it might get you down
on people.  I am sure all the people searching for "back street boys"
and "lesbian granny" are using MLDonkey. </para>

<figure><title>gtk-gnutella Search monitor</title>
<screenshot>
<graphic width="430" depth="580" fileref="images/search-monitor"></graphic>
</screenshot>
</figure>

<para>In either <glossterm linkend="leaf">leaf</glossterm> or
<glossterm linkend="ultrapeer">ultrapeer</glossterm> you can observe
searches that are routed to your computer.  When you are a leaf node,
this gives you an idea of how well the <glossterm
linkend="GnutellaNet">GnutellaNet</glossterm> is targeting searches.
Many of the search terms should be related to files you share. </para>

</section>

<section id="SEARCH_STATS"> <title>Search "Stats"</title>

<para> The Search Stats are currently disabled, as they use too much
CPU time in their current form.  </para>

</section>
</chapter>

<chapter id="DOWNLOADING">
<title>Downloading files</title>

<para>Downloads are started automatically with magnet links.  If you
wish to download a search result, you can right click and select from
the menu or you can use the "Download selected" button at the bottom
of the search work area.</para>

<para>The download work area is divided into two sections.  The top
portion lists all downloads.  Completed downloads (showing "Finished;
SHA1 OK") can be removed by using the "Purge Selected" button at the
bottom of the work area.  This will not delete a
<emphasis>completed</emphasis> download; it is just removed from the
display.  If the download is not completed, including the SHA check,
the file will be deleted!</para>

<para>The lower section of the download area is dedicated to
information on the currently selected entry in the download list.  It
displays information on the file, a colour progress bar and a list of
file names.  The list of file names can be useful in identifying
mis-labeled files and spam.  The various colours in the progress bar
are explained in the tooltip. </para>

<figure><title>gtk-gnutella downloads</title>
<screenshot>
<graphic  width="617" depth="542" fileref="images/downloads"></graphic>
</screenshot>
</figure>

</chapter>
<chapter id="SHARING">
<title>Sharing your own files</title>

<para> Sharing too many files is just as bad as sharing too few.  If
everyone shares too few files, gnutella would be empty.  Sharing your
entire hard drive is also very bad.  Most people wouldn't want to do
this for privacy reasons.  However, even if you don't care about the
confidentiality of your files, it is still bad to share
everything.  </para>

<para> Consider someone searching for "Gimp", maybe looking for advice
on how to use this program.  If people share their entire hardrive,
all of the individual files in the "Gimp" package could be returned
from this search.  This makes it difficult to find relevant files.
Not only that, but this will be flooding the GnutellaNet with useless
search results.  Share what you would want to download, but no more!
</para>

<figure><title>gtk-gnutella Uploads</title>
<screenshot>
<graphic width="591" depth="535" fileref="images/uploads"></graphic>
</screenshot>
</figure>

<para>The uploads work area allows you to see what other client are
currently downloading from gtk-gnutella.  You can right click on an
upload and use the "Browse host" feature to see what files they share;
At least they are people with similar interests.  Unfortunately not
every client implements (or allows) the "Browse host" feature, or has
it enabled.</para>

<para>The files you share are configured using the "File|Preferences"
menu (or control-P).  The settings are under the "Uploads" tab.  You
can configure the directories and extensions that you wish to share.
Every directory underneath directories you list will be shared.  The
expose relative paths checkbox will include the sub-directory names in
your "search terms".  For instance if you store your music as
"music/Artist/Alblum/song.mp3", the "Expose relative paths" will add
both "Artist" and "Album" to the search terms.  Without this, your
gtk-gnutella will only return result if someone searches for "song" (or
"song.mp3").</para>

<figure><title>gtk-gnutella Upload Preferences</title>
<screenshot>
<graphic width="600" depth="433" fileref="images/preferences-upload"></graphic>
</screenshot>
</figure>

<para>Other interesting items are the "Browse Host" feature.  This
allows other gnutella nodes to request a list of all shared files.  The
partial files sharing allows others to download a file as you are
downloading it.  You might wish to disable this if you get corrupted
downloads (mainly larger video files).  A future feature called "Tiger
Tree Hashing" will allow better use of this feature with large files
(Ie, video files).</para>

<figure><title>gtk-gnutella upload history</title>
<screenshot>
<graphic  width="611" depth="542" fileref="images/upload-history"></graphic>
</screenshot>
</figure>

<para>The "Upload history" work area allows you to see what files are
taking the most bandwidth and which are the most popular.  If many
people have downloaded your file, it should be easy to find on the
GnutellaNet.  The popular share is available from many other sources
if the people who downloaded the file are sharing it.  You might
consider removing a popular file from your shares so you can provide
rarer content.</para>

</chapter>

<chapter id="SETTINGS">
<title>Adjusting settings</title>

<figure><title>gtk-gnutella Preferences dialog</title>
<screenshot>
<graphic width="865" depth="570" fileref="images/preferences"></graphic>
</screenshot>
</figure>

<para>As mentioned before, the preferences dialog can be accessed by
File | Preferences menu or by pressing control-P.  There are seven
tabs in this dialog.  The "User Interface" tab can be used to
customize gtk-gnutella.  The "Debugging" tab is mainly of use for developers.
The network tab is used to handle oddities of your section of the
Internet.  If you have problems connecting to any other gnutella nodes,
you will need to use this tab.  Information in the <link
linkend="NETWORKING"> networking section </link> will also be of help.  The
remaining tabs are related to file sharing. </para>


<para> The GnutellaNet tab configure how you connect to other
nodes. To begin with, you only need to change items in the top group.
If your machine is slow, you might want to set the peer mode to "leaf".
You can also configure the number of leave that are allowed to connect
when in "ultrapeer" mode.  The number of leaves should be above thirty.
Leaves don't consume much bandwidth or CPU usage.  The number of
ultrapeer to connect to is found at the bottom of the GnutellaNet
work area (strangely enough).</para>

<para> The Bandwidth tab allows you to configure how gtk-gnutella uses your
bandwidth.  See the traffic shaping section for more on how to address
this problem.  Appropriate values for Incoming and Outgoing traffic
are 30 and 40 KiB/s.  Leaves require 2 and 3 KiB/s for incoming and
outgoing traffic.  HTTP traffic is mainly for uploading and
downloading files. <link linkend="TRAFFIC_SHAPING">OS Traffic
shaping</link> can limit this, or you can set limits here. </para>

<para>The "Downloads" tab allows configuration of where downloaded
files are stored.  There are also many parameters on how to retrieve
files.  The particular options will depend on the size of the file,
the number of sources, and the number of hostile hosts.  The tool tips
explain the parameters, but the defaults are good for most
users.</para>

<para>Uploads configuration was covered in the <link
linkend="SHARING">Uploading chapter</link></para>

</chapter>

</part>

<part id="ADVANCED_FEATURES">
<title>Advanced features</title>

<chapter id="FILTERING">
<title>Filtering</title>

<para>The text in this chapter is copied verbatim from the Filtering
mini-Howto by Vidar Madsen and Markus Goetz. It is copyright 2002 by
them.</para>

<section id="FILTER_INTRO">
<title>Introduction</title>

<para>The filtering code in gtk-gnutella 0.90 was dramatically
improved. This small howto will tell you how to deal with the power
given by those filters.</para>

<para>Note that filters will only be applied to new search results as
they come in. There is currently no way to apply them to the results
that are already in the list.</para>
</section>

<section id="FILTER_STATE_FLAGS">
<title>State flags</title>

<para>When a search result arrives at the filtering engine it has two
state flags; DOWNLOAD and DISPLAY. Initially the state flags are in an
"undefined" state, and by applying various tests to each result, these
flags can be set to DO and DON'T.</para>

<para>Note: As soon as both state flags are defined, i.e. set to
either DO or DON'T, the filtering is aborted, and the application will
proceed to DISPLAY and/or DOWNLOAD if the respective flags are
set. Furthermore, each of the flags can be set only once (subsequent
attempts to set them will be silently ignored), so the order in which
you set up the rules is quite important.</para>
</section>

<section id="FILTER_FILTER">
<title>Filters</title>

<para>A filter is basically a set of rules. There are three types of
user-definable filters; Global filters, Search filters, and Free
filters;</para>

<itemizedlist>
<listitem><para>There are two global filters; "pre" and "post". The "pre"
filter is applied to all results before they go to their respective
search filter. They can be used to filter away certain hosts, restrict
which types of files you see (i.e. ignore all ".html" files), etc. The
global "post" filter will be processed after the search results have
gone through their search filter.</para></listitem>

<listitem><para>Search filters are filters that are connected to a specific
ongoing search. When you search for something, every result will be
sent to its respective search filter.</para></listitem>

<listitem><para>Free filters are perhaps the most interesting ones. You can
practically write "sub-routines" that can be called from any of the
other filters. For example, you can define a "movie" filter that
filters away files that are less than a certain size, and don't match
any of the common video file extensions. Then you can use the "jump"
rule in your search filters to call your "movie" filter.</para></listitem>
</itemizedlist>
</section>

<section id="FILTER_RULES">
<title>Rules</title>

<para>There are several different rule types. Most of them have some
flags that might warrant an explanation;</para>

<itemizedlist>

<listitem><para>"Invert condition" can be checked to invert the test
in question. An example; If you're looking for an mp3 file, and your
search results are cluttered with non-relevant hits, you can set up a
rule that says; If filename DOES NOT end with ".mp3", flag it as
"DON'T DISPLAY". Inverted conditions are marked with an X in the rule
list.</para></listitem>

<listitem><para>The "Active" flag can be checked and unchecked to
temporarily enable or disable a rule.</para></listitem>

<listitem><para>The "Mark only" flag is special, and is likely to be
replaced by something more generic, but currently it can be used to
mark search results with a different colour to make the matching
results stand out from the rest. To achieve that effect, check "Mark
only", and select "DON'T DISPLAY" as the target.</para></listitem>
</itemizedlist>

<section>
<title>Size rules</title>

<para>Size rules have three similar uses;</para>

<itemizedlist>
<listitem><para>If only "minimum size" is given, the rule will trigger
a jump to the selected target if the size is less than the value
given. This can be used to filter away small files when looking for
something large, such as a video clip.</para></listitem>

<listitem><para>If both "minimum" and "maximum" is defined, the rule
will cause a jump if the size is between the two
values.</para></listitem>

<listitem><para>If only "maximum" is given, the filter will jump if
the result's size is larger than the given value.</para></listitem>
</itemizedlist>
</section>

<section>
<title>Name rules</title>

<para>Name rules perform tests on the results' filenames. The
"Condition" pulldown should be quite self-explanatory.</para>
</section>

<section>
<title>Flag rules</title>

<para>The flag rules can be used to filter results based on the
hosting servent's flags; "Stable", "Busy "and "Push". For example, if
you are behind a firewall and unable to received pushed files, you can
add a rule that directs all results with the Push flag set to DON'T
DISPLAY.</para>
</section>

<section>
<title>Jump rules</title>

<para>The jump rule is used to either set a DO or DON'T flag directly,
or it can be used to call one of the free filters for subsequent
testing.</para>
</section>

<section>
<title>IP rules</title>

<para>IP rules filter results based on the servent's IP address. A
typical use for this is to ignore certain spammer hosts which return
bogus hits. Or one can auto-download results that come from a certain
IP address or network which is known to be fast.</para>
</section>

<section>
<title>urn:sha1 rules</title>

<para>The urn:sha1 rules are special, and can't be edited
manually. They can only be added via the right-click-menu in the
search results window. They are used to match a given file, and flag
it for either DON'T DISPLAY (if picked via the "ignore" menu item) or
DOWNLOAD (if picked via the "auto-download" item).</para>
</section>

<section>
<title>State rules</title>

<para>State rules can be used to process results that have already
been through a number of other tests. A common application for this
rule is to automatically download results that haven't been marked as
DON'T DISPLAY. See under "Sample rulesets" for a full example.</para>
</section>
</section>

<section id="FILTER_TIPS">
<title>Tips</title>

<itemizedlist>

<listitem><para>If you want to filter away certain results permanently
(based on e.g. file size or name), create a free filter called
"Ignore", and put two jumps in it; one to "DON'T DISPLAY" and one to
"DON'T DOWNLOAD". Now you can jump to "Ignore" instead of "DON'T
DISPLAY". This way the filter execution will abort immediately,
instead of trying to run the rest of the calling
filter.</para></listitem>

<listitem><para>To see which files have been tagged for download, add
a rule to your Global (post) filter; If state flag "DOWNLOAD" is set,
jump to "DON'T DISPLAY" with "Mark only". Now your auto-downloaded
files will show up in a different colour in the search
results.</para></listitem>

<listitem><para>Apparently some pieces of software like to respond to
every search they come across, and feed back bogus results. You may
have come across files with names like "!!_YEEHAA_!!_(search
term).exe" or "secret paysite passwords for (search term).html" and
similar. Zygo has a nice trick to weed them out: Specify your search
with the words jumbled, like "clones of the attack", and use a filter
to remove results that has the same order of the words; "If file
matches the regexp "clones.*of.*the.*attack", DON'T
DISPLAY".</para></listitem>
</itemizedlist>
</section>

<section id="FILTER_SAMPLES">
<title>Sample filters</title>

<para>Here is a sample "movie" filter as mentioned earlier. If you set
this up as a free filter, you can jump to it from the search filters
to filter out a lot of bogus hits. Also, when doing a new search, you
can select it on the default filter pulldown directly.</para>

<informaltable>
<tgroup cols="3">
<thead>
<row><entry>!</entry><entry>Condition</entry><entry>Target</entry></row>
</thead>
<tbody>
<row><entry/><entry>If filesize is smaller than 400000000 (381.5 MB)</entry><entry>DON'T DISPLAY</entry></row>
<row><entry/><entry>If filename ends with ".avi"</entry><entry>RETURN</entry></row>
<row><entry/><entry>If filename ends with ".mpg"</entry><entry>RETURN</entry></row>
<row><entry/><entry>Always</entry><entry>DON'T DISPLAY</entry></row>
</tbody>
</tgroup>
</informaltable>

<para>Here is a filter that will download MPEG music videos of
Rammstein tracks. The trick is to use inverted conditions (note the
X'es in front), and the last rule that will mark all files that aren't
flagged as DON'T DISPLAY with DOWNLOAD.</para>

<informaltable>
<tgroup cols="3">
<thead>
<row><entry>!</entry><entry>Condition</entry><entry>Target</entry></row>
</thead>
<tbody>
<row><entry>X</entry><entry>If filename contains the words "rammstein"</entry><entry>DON'T DISPLAY</entry></row>
<row><entry>X</entry><entry>If filename ends with "mpg"</entry><entry>DON'T DISPLAY</entry></row>
<row><entry/><entry>If filesize is smaller than 20000000 (19.1 MB)</entry><entry>DON'T DISPLAY</entry></row>
<row><entry>X</entry><entry>If flag DON'T
DISPLAY</entry><entry>DOWNLOAD</entry></row>
</tbody></tgroup></informaltable>

</section>
</chapter>

<chapter id="GNUTELLANET">
<title>The GnutellaNet pane</title>

<figure><title>GnutellaNet</title>
<screenshot>
<graphic  width="593" depth="541" fileref="images/gnet"></graphic>
</screenshot>
</figure>

<para>The GnutellaNet pane gives details of all the other nodes
directly connected to your computer.  The bottom of the pane controls
the GnutellaNet connections.  Clicking on a node and pressing the
"Disconnect" button will disconnect that node.  The node might decide
to reconnect, so you might have to do this twice.  Using the "Add"
button and entry field beside it, you can add a node.  The entry field
should contain an dip address and a port.  For instance,
"127.0.0.1:6346".  The "connect to xx ultrapeers" spinner box is only
applicable when in leaf mode.  Similarly, "Try to keep at least xx and
allow at most xx total connections up." only applies in ultrapeer
mode.  In ultrapeer mode, the number of leaves to connect to is set
from "File|Preferences" dialog in the "GnutellaNet" tab.  The final
spinner at the bottom sets the number of connection to initiate at
once (in any mode).  If your machine is slow on startup, this number
can be lowered; it will just take longer to become fully
connected.</para>

<para> The flags in the top half of the pane have the following
meanings,

<informaltable>
<tgroup cols='2'>
<thead><row><entry>Postion, Function</entry>
<entry>Short Description</entry></row>
</thead>
<tbody>
<row><entry>0, Node type</entry><entry>
     <para>N - very ancient client, should never see this.</para>
     <para>U - an ultrapeer connection.</para>
     <para>L - a leaf connection.</para>
     <para>C - a crawler collecting statistics.</para>
     <para>P - udp pseudo-node (our own node).</para></entry></row>
<row><entry>1, Origin</entry><entry>
     <para>I - an incoming connection.</para>
     <para>O - an outgoing connection.</para></entry></row>
<row><entry>2, Read</entry>
     <entry><para>r - we can "read" the node.</para></entry></row>
<row><entry>3, Write</entry>
     <entry><para>w - we can "write" to the node.</para></entry></row>
<row><entry>4, QRT received</entry><entry>
     <para>Q - search table received.</para>
     <para>q - search table is being received.</para>
     <para>p - updating search table.</para></entry></row>
<row><entry>5, QRT sent</entry><entry>
     <para>X - search table sent.</para>
     <para>x - search table is being sent.</para>
     <para>p - updating search table.</para></entry></row>
<row><entry>6, Compression</entry><entry>
     <para>R - compressed received channel.</para>
     <para>W - compressed write channel.</para>
     <para>Z - connection fully compressed.</para></entry></row>
<row><entry>7, Push proxy</entry><entry>
     <para>P - We are a push proxy for the node.</para>
     <para>p - The node is a push proxy for us.</para></entry></row>
<row><entry>8, Outgoing flow control</entry><entry>
     <para>d - Some data queued.</para>
     <para>D - More data queued, getting concerned.</para>
     <para>F - This node is sending a lot of data.</para>
     <para>S - Swift control mode. 
               Too much data, dropping new searches.</para></entry></row>
<row><entry>9, Incoming flow control</entry><entry>
     <para>h - Responds to searches in a limited neighbourhood.</para>
     <para>f - Will not respond to any new searches. </para></entry></row>
<row><entry>10, Encryption</entry>
     <entry><para>E - for an encrypted connection.</para></entry></row>
</tbody></tgroup></informaltable></para>

<para>
In all cases a value of "-" indicates an absence of the flag.
Normally, leaf values of the flags will start with "LIrwQ-", if the
leaf has been connected for a few minutes.  The connection can be
compressed or proxied.  Encryption may become more common in the
future, but it is rare.  A leaf connection can be "Outgoing" if you
use the "Add" button to connect.</para>

<para>A typical ultrapeer connection is "UIrwQXZ----".  With the
exception of the encryption flag, any flags after compression indicate
some sort of problem with the ultrapeer, especially if they persist.
An ultrapeer should never be "push proxied".</para> </chapter>

<chapter id="HOST_CACHE">
<title>The Host Cache</title>
<figure><title>gtk-gnutella Host Cache</title>
<screenshot>
<graphic  width="593" depth="541" fileref="images/host-cache"></graphic>
</screenshot>
</figure>

<para>The host cache pane provides information about other nodes seen
on the GnutellaNet.  They are not necessary connected at the moment.
They have been seen at some time in the past.  The host cache is used
when new connections are needed.  This is not only for your version of
gtk-gnutealla, but any other node that might contact you will be given
random values from the host cache. </para> 

<para>The buttons at the bottom allow you to clear the caches.
However, you should never do this.  If none of the hosts work,
gtk-gnutella will still use other means to find good hosts.  It is
only sensible to clear these values if you haven't used the program in
several months.  It is useful to adjust the number of hosts stored in
the cache, but the defaults work very well.  For the most part, after
a single connection is made, new hosts will come directly from the
network. </para> </chapter>

<chapter id="GNET_STATS">
<title>GnutellaNet Statistics</title>

<figure><title>GnutellaNet Statistics</title>
<screenshot>
<graphic  width="592" depth="545" fileref="images/gnet-stats"></graphic>
</screenshot>
</figure>

<para>The GnutellaNet statistics require an indepth understanding of
the gnutella protocol.  You may be asked to visit these screens to
diagnose problems.</para> 

<para>The horizon tab gives an estimate of the number of files and
total amount of data available on the GnutellaNet.  Currently all
information must be less than five hops away.  So the four hops data
is what is displayed in the status line.  This data is derived from
the HSEP (horizon size estimate protocol).  Unfortunately only
gtk-gnutella supports this, so there are not very many nodes
participating.  This makes the estimates unreliable. </para>

</chapter>

</part>


<part id="TROUBLE_SHOOTING">
<title>Trouble shooting</title>

<chapter id="NETWORKING">
<title>Networking</title>

<section><title>NAT and firewalling.</title>
<para> This section only addresses IPv4.  Some background on the
Internet Protocol is needed.  Most likely if you are having networking
problems, you are on a private network.  These addresses are found in
"RFC 1918".

</para>

<informaltable>
<tgroup cols='3'>

<thead> <row>
  <entry>Start address </entry>
  <entry>End address   </entry>
  <entry>CIDR range    </entry>
 </row>
</thead>
<tbody>
<row>
  <entry>10.0.0.0         </entry>
  <entry>10.255.255.255   </entry>
  <entry>10.0.0.0/8       </entry>
</row>
<row>
  <entry>172.16.0.0       </entry>
  <entry>172.31.255.255   </entry>
  <entry>172.16.0.0/12    </entry>
</row>
<row>
  <entry>192.168.0.0      </entry>
  <entry>192.168.255.255  </entry>
  <entry>192.168.0.0/16   </entry>
</row>
</tbody></tgroup></informaltable>

<para>There are only a limited amount of real (routeable) IP addresses
and they cost money.  In order to get around this, many networks use
these private networks and a gateway connects them to the outside.
The gateway will have at least two IP addresses.  You can find the
external IP address by visiting a web sight like <ulink
url="http://www.portforward.com/english/routers/port_forwarding/routerindex.htm"/>.
This URL also contains instructions on how to configure most routers
to forward ports.</para>

<para> A critical item to know is the port used by gtk-gnutella.  It
can be found using the <guimenuitem>Preferences</guimenuitem> item
from the <guimenu>File</guimenu> menu or by pressing
<keysym>Control-p</keysym>.  The port is the "listen port" in the
"network" tab.  The ip address and port are also in the status bar
separated by a colon.  Finally, you can find the port with a shell
command. </para>

<para><informalexample><programlisting>
grep listen_port ~/.gtk-gnutella/config_gnet
</programlisting></informalexample></para>

<para>The gateway will use <emphasis>network address
translation</emphasis> or <emphasis role="bold">NAT</emphasis> for
short.  There are two types of NAT, source and destination NAT or
simply SNAT and DNAT.  DNAT is the appropriate technology to get
gtk-gnutella working inside a translated network.  Often NAT is
combined with port blocking, more commonly known as firewalling.
Changing the port that gtk-gnutella uses can avoid port blocking.</para>

<para> If your gateway uses iptables, it maybe as simple as adding a
few rules to forward gtk-gnutella traffic on the gateway. </para>

<para><informalexample><programlisting>
#
# DNAT rules to allow machines inside to act as servers on external ports.
#
EXTIF=ppp0
gtkg=192.168.0.111
port=6346

# Forward Gnutella traffic.
iptables -t nat -A PREROUTING -i $EXTIF -p udp --dport $port -j DNAT --to $gtkg
iptables -t nat -A PREROUTING -i $EXTIF -p tcp --dport $port -j DNAT --to $gtkg

</programlisting></informalexample></para>

<para><emphasis role="bold">NOTE:</emphasis> Many consumer firewall
products refer to DNAT as "DMZ".  This is the wrong nomenclature, but
it maybe what you want. </para>
</section>

<section id="ENCRYPT-SHAPING">
<title>ISP filtering and shaping Gnutella traffic</title>

<para>
Many ISPs have been known to filter or shape peer-to-peer traffic.
The <ulink url="http://www.azureuswiki.com/index.php/Bad_ISPs">
Azureus wiki </ulink> gives an extensive list of ISPs known to filter
or shape BitTorrent traffic.  As can be seen from <ulink
url="http://www.gnutellaforums.com/connection-problems/33712-isps-known-block-filter-p2p-specifically-limewire.html">
this discussion </ulink> many of the same ISPs are shaping Gnutella traffic.
</para>

<para>
gtk-gnutella was the first Gnutella client to provide encryption to
prevent traffic filtering and shaping of Gnutella traffic.  If you
have an ISP that you <emphasis role="bold">know</emphasis> is
detecting Gnutella traffic, you can set the
<emphasis>tls_enforce</emphasis> parameter.  The
<emphasis>tls_enforce</emphasis> parameter is set from the "Debugging"
tab of the Preferences dialog (control-P).  Type
<emphasis>tls_enforce</emphasis> in the "Property pattern" and click
on the value "FALSE" and change it to "TRUE".
</para>

<para>
If your ISP is not shaping traffic, there is no need to set the
<emphasis>tls_enforce</emphasis> parameter.  gtk-gnutella will detect
if other servents wish to use encrypted connections.  gtk-gnutella
must be compile to use the GnuTLS libraries for the encryption to
work.
</para>

</section>

</chapter>

<chapter id="TRAFFIC_SHAPING">
<title>OS Traffic shaping</title>

<para>The bandwidth preferences are an excellent tool for controlling
gtk-gnutella's bandwidth.  However, you must often be a pessimistic when using
application layer bandwidth control.  Consider a system running gtk-gnutella,
a BitTorrent client, a web server and a secure shell server (sshd).
The bandwidth can be divided into four (possibly unequal) parts at the
application level.  </para>

<para>Simple division of bandwidth is not ideal.  The ssh task doesn't
need a lot of bandwidth.  The important item is response or "latency".
This is also true for many real time gaming applications.  Ftp, and
peer-to-peer applications like gtk-gnutella need bandwidth.  Web pages also
need to be responsive.  It also becomes obvious that dividing the
bandwidth is not making full use of your network connection.  Web
traffic is very bursty as users click links.  gtk-gnutella and BitTorrent
traffic is also bursty as new clients come and go.</para>

<para>Fortunately there are better ways to do this.  Linux provides
the "tc" program.  BSD provides "ipfw" queue and pipe commands.  When
using traffic shaping, it is useful to have some diagnostic tools. The
<ulink url="http://www.ex-parrot.com/pdw/iftop/">iftop</ulink> program
is useful in observing bandwidth usage.</para>

<para>The following is an example ".iftoprc" that is useful for
sorting bandwidth based on destination port.
</para>

<para><informalexample><programlisting>
interface: ppp0
dns-resolution: yes
port-resolution: no
show-bars: yes
promiscuous: no
port-display: source-only
hide-source: yes
hide-destination: yes
use-bytes: yes
sort: 2s
line-display: one-line-both
show-totals: yes
log-scale: no
</programlisting></informalexample></para>

<para>

The "iftop" program requires libpcap and must be run as root.
However, root access is not an issue as all traffic shaping commands
need to be run a root level.</para>

<para>As mentioned previously, there are two factors that affect
network performance.  One is bandwidth, the other is latency.  As most
network traffic is bursty, all routers on the Internet buffer packets.
This allows momentary handling of traffic that is above a links
capacity.  However, this buffer forms a queue which increases latency.
If the traffic never subsides latency will increase for interactive
traffic, like ssh, web and gaming applications.  A key to configuring
traffic shaping is to limit the total outbound traffic below the link
capacity (bandwidth).  Running "iftop" without any traffic shaping and
use "ftp" or another application to use all your bandwidth.  It is
important to get real numbers.  If you over-estimate your bandwidth,
the latency will increase.  The "f" key allows a filter to be
installed.  The filter "src host <emphasis>ip</emphasis>" will show
only outbound traffic on most home networks (single IP).  Your
<emphasis>ip</emphasis> is your actual ip, found with "ifconfig" or
any other method.</para>

<para>It is not simple to control incoming traffic and you may never
be sucessful as it requires support on both ends.  It is probably best
to use the application layer controls for download bandwidth.  </para>

<section id="BSD_TRAFFIC_SHAPING"><title>BSD Traffic Shaping</title>
<para>Please add information here.</para>
</section>

<section id="LINUX_TRAFFIC_SHAPING"><title>Linux Traffic Shaping</title>

<para> If you are using OS traffic shaping, the "Use IP Type of
Service (TOS)" is useful.  Uploads use "maximum throughput", Downloads
use "low-delay" and other traffic is normal service.  This can be used
to classify the gnutella traffic, with the iptables MANGLE table and
mark. </para>

<para>The <emphasis>wondershaper</emphasis> and
<emphasis>myshaper</emphasis> scripts provide a good base to start
controlling your bandwidth.  The main idea is to use the heiarchical
token bucket (htb) queuing discipline.  This ensures that all traffic
classes get a minimum amount of bandwidth, but they can also borrow
bandwidth if another class isn't using it. </para>

<para><emphasis role="bold">NOTE:</emphasis> Most Linux distributions
do not provide a kernel with traffic shaping built-in.  You may be
required to re-compile your kernel in order to use system wide
bandwidth control. </para>

</section>

</chapter>

<chapter id="HEADLESS">
<title>Headless mode</title> 

<para>gtk-gnutella has a configuration called "headless".  This configuration
doesn't use either GTK1 or GTK2.  It will operate without the X Window
System. Due to abscence of a GUI it uses even less resources - CPU and
memory. This mode is mostly useful for ultrapeers.
</para>

<para>See the chapter <link linkend="GETTING">on getting
gtk-gnutella</link> on how to get the source code.  The following
"build.sh" invocation will produce a headless version of gtk-gnutella.
</para>

<para><informalexample><programlisting>
./build.sh --topless [...]
</programlisting></informalexample></para>

<para>
Run "build.sh" and "make" in the source directory.

After compiling, the gtk-gnutella binary is in the "src" subdirectory.
Rename the gtk-gnutella binary to gtk-gnutella-headless and copy it to
a directory in your PATH, for example, /usr/local/bin.  </para>

<para> Assuming you have run a graphical version of gtk-gnutella, copy all
files in $HOME/.gtk-gnutella to a backup directory.  Run the graphical
gtk-gnutella and configure the networking parameters for the "headless"
version.  You may wish to let it run for a while to verify that it is
operating well.  Make sure you change the listening port.  Exit the
graphical gtk-gnutella.</para>

<para>
Now, you move the configuration directory for use by the headless
gtk-gnutella:
</para>

<para><informalexample><programlisting>
 mv -i ~/.gtk-gnutella ~/.gtk-gnutella-headless
</programlisting></informalexample></para>

<para>
Note that you should not copy the file "config_gnet" directly. However,
if you do so, delete the lines containing "guid" and "servent_kuid".
These IDs have to be globally unique and must therefore not be shared by
two running peers at the same time. Thus, delete these lines so that
gtk-gnutella generates new IDs on startup.

Using grep to copy any but the mentioned lines is another possibility:
</para>

<para><informalexample><programlisting>
 grep -Ev '^(guid|servent_kuid)' ~/.gtk-gnutella/config_gnet
</programlisting></informalexample></para>

<para><informalexample><programlisting>
#! /bin/sh

GTK_GNUTELLA_DIR=~/.gtk-gnutella-headless
export GTK_GNUTELLA_DIR
gtk-gnutella-headless --daemonize --log-stderr ~/tmp/error.log
</programlisting></informalexample></para>

<para>
You can name this script "gtkg-headless" and invoke it like this
"gtkg-headless". You can then use the GnutellaNet working area in the
graphical gtk-gnutella to connect to this headless ultrapeer, using
"127.0.0.1:port".

</para>

</chapter>

<chapter id="KERNEL_MODE_PPPOE">
<title>Kernel mode PPPoE.</title>

<para> ADSL and cable modem user that require PPPoE should consider
using a kernel that supports PPPoE.  The user mode PPPoE consumed
about 20% of CPU on an AMD-K6/2 300MHz running a gtk-gnutella ultrapeer on Linux
2.6.  When using kernel mode PPPoE, this drops to near zero.  This is
especially important if you wish to support many connections as an
ultrapeer. </para>

<informaltable>
<tgroup cols='6'>

<thead> <row>
  <entry>Operating System   </entry>
  <entry>PPP additional info</entry>
  <entry>Transfer rate      </entry>
  <entry>Ping               </entry>
  <entry>CPU usage          </entry>
  <entry>CPU usage breakdown</entry>
 </row>
</thead>

<tbody>
<row>
  <entry> Linux 2.2 (64MB RAM)  </entry>
  <entry> usermode, async       </entry>
  <entry> ~4.1Mbits/s           </entry>
  <entry> 1.4/1.1               </entry>
  <entry> 100%                  </entry>
  <entry> pppoe 95%, nc 5%      </entry>
 </row>

<row>
  <entry> Linux 2.2 (64MB RAM)  </entry>
  <entry> usermode, sync        </entry>
  <entry> Network max           </entry>
  <entry> 1.0/0.8               </entry>
  <entry> 50%                   </entry>
  <entry> pppoe 40%, nc 10%     </entry>
</row>

<row>
  <entry> Linux 2.4 (64MB RAM)  </entry>
  <entry> kernelmode            </entry>
  <entry> Network max           </entry>
  <entry> 0.7/0.5               </entry>
  <entry> 26%                   </entry>
  <entry> system 24%, nc 11%    </entry>
</row>

<row>
  <entry> NetBSD 1.6 (64MB RAM)   </entry>
  <entry> kernelmode              </entry>
  <entry> Network max             </entry>     
  <entry> 0.9/0.5                 </entry>
  <entry> 23%                     </entry>
  <entry> sys 15%, nc 17%         </entry>
</row>

<row>
  <entry> NetBSD 1.6 (32MB RAM)  </entry>
  <entry> kernelmode             </entry>
  <entry> Network max            </entry>
  <entry> 1.1/0.6                </entry>
  <entry> 23%                    </entry>
  <entry> sys 15%, nc 17%        </entry>
 </row>

<row>
  <entry> FreeBSD 4.7 (64MB RAM)  </entry>
  <entry> usermode,sync           </entry>
  <entry> ~6.5Mbits/s             </entry>
  <entry> 2.0/1.9                 </entry>
  <entry> 100%                    </entry>
  <entry> ppp 80%, nc 15%, int 5%  </entry>
</row>

 <row>
  <entry> FreeBSD 4.7 (64MB RAM)  </entry>
  <entry> kernelmode              </entry>
  <entry> ~7.7Mbits/s             </entry>
  <entry> 0.7/0.5                 </entry>
  <entry> 35%                     </entry>
  <entry> nc 17%, sys 16%, int 18%  </entry>
</row>

<row>  
  <entry> OpenBSD 3.2 (64MB RAM) </entry>
  <entry> usermode,sync          </entry>
  <entry> ~2.0Mbits/s            </entry>
  <entry> 2.9/2.3                </entry>
  <entry> 99%                    </entry>
  <entry> sys 87%, pppoe 65%, ppp 23%, nc 7% </entry>
</row>

</tbody></tgroup></informaltable>


<para> This table is from an <ulink
url="http://www.jraitala.net/comp/articles/2002/pppoe/"> article
entitled "PPPoE performance under Linux and BSDs"</ulink> by Juuso
Raitala and others.  The important point is that kernel mode PPPoE
will significantly reduce CPU load when running gtk-gnutella as an
ultrapeer.  </para>

<para><emphasis role="bold">Disclaimer</emphasis></para>

<para>
Distribution and copying of this section is permitted in any medium
provided this notice is preserved. An e-mail notification to any one
of the following would be preferred if this article is redistributed.
</para>

<para>
&copy; 2002 
<ulink url="http://www.jraitala.net">Juuso Raitala</ulink> 
&lt;<ulink url="mailto:jraitala -at- jraitala dot net">jraitala -at-
jraitala dot net</ulink>&gt (the main author of the article),

Olli Vainio
&lt;<ulink url="mailto:odo -at- lyseo.edu.ouka.fi">odo -at-
lyseo.edu.ouka.fi</ulink>&gt;,
Juha K. Kallio 
&lt;<ulink url="mailto:bunnyh -at- psychedelic.baana.suomi.net">bunnyh -at- psychedelic.baana.suomi.net</ulink>&gt;,
</para>
</chapter>

</part>

<glossary id="GLOSSARY"><title>Glossary</title>

<para>

This glossary is meant to contain more advanced topics.  It is meant
as a reference as opposed to the earlier text which is more
explainatory.

</para>

<!-- ................................................................ -->
<!-- sample...
<glossdiv><title>A</title>

<glossentry><glossterm>A</glossterm>
<glossdef>  <para>Definition.</para></glossdef>
</glossentry>

</glossdiv>
-->
<!-- ................................................................ -->

<glossdiv><title>G</title>

<glossentry id="GnutellaNet"><glossterm>GnutellaNet</glossterm>

<glossdef> <para>The GnutellaNet is an <emphasis>overlay</emphasis>
network.  This means it is a network that sits on top of the normal
internet.  GnutellaNet is <emphasis>unstructured</emphasis>.  This
just means that no particular computer or group of computers controls
GnutellaNet; it is probably more democratic than most governments.
</para> 

<para>As the GnutellaNet is an overlay network, it doesn't have to pay
attention to geography.  It is likely that you will connect to
computers in other countries.  Things might be faster if this was not
the case.  However, they may also be more resilient in the current
form.</para>

</glossdef>

</glossentry>

</glossdiv>

<!-- ................................................................ -->

<glossdiv><title>L</title>

<glossentry id="leaf"><glossterm>Leaf node</glossterm>

<glossdef> <para>A leaf is the basic connection to the GnutellaNet.  A
leaf typically connects to three or four ultrapeers.  The ultrapeers
route searches and keep their leaves connected to the
GnutellaNet. </para>
<glossseealso otherterm="ultrapeer">ultrapeers</glossseealso>
</glossdef>

</glossentry>

</glossdiv>

<!-- ................................................................ -->

<glossdiv><title>S</title>

<glossentry id="search_literals"><glossterm>search literals</glossterm>

<glossdef>

<para>

Double and single quotes can be used so that an entire search term
will be matched instead of individual words.  Quoting maybe necessary
if you wish to search for a phrase with special characters such as the
<glossterm linkend="search_required"> plus and minus
signs</glossterm>.

</para>


</glossdef>
</glossentry>


<glossentry id="search_prefixes"><glossterm>search prefixes</glossterm>

<glossdef>

<itemizedlist mark='opencircle'>

<listitem><para><emphasis role="bold">browse:</emphasis>
   - List shared files on the specified host.  The format is
   "browse:<emphasis>ip_address</emphasis>:<emphasis>port</emphasis>".
   Many portions of the GUI have a menu option, available from a right
   click, that will browser the specified computer.</para></listitem>

<listitem><para><emphasis role="bold">http:</emphasis>
   - Download the specified web page.  This could be a zip file, a
     movie, large JPEG, etc.</para></listitem>

<listitem><para><emphasis role="bold">local:</emphasis>
   - Search results from the local host.  Ie, your computer.  A
     regular expression may follow to filter the results.  For
     example, "local:manual" will show all files you share with
     manual in the file name.</para></listitem>

<listitem><para><emphasis role="bold">magnet:</emphasis>
   - Search and download the magnet target. </para></listitem>

<listitem><para><emphasis role="bold">push:</emphasis> - The format of
   this search is
   "push:<emphasis>guid</emphasis>:<emphasis>ip_address</emphasis>:<emphasis>port</emphasis>/<emphasis>path_to_file</emphasis>".
   The <emphasis>guid</emphasis> is the Gnutella ID of the computer
   that has the file of interest.  The
   <emphasis>ip</emphasis>:<emphasis>port</emphasis> is the push proxy
   that the <emphasis>guid</emphasis> is connected to.  Typically this
   would be an ultrapeer that will allow a proxy download. The
   <emphasis>guid</emphasis> is a 32 hexadecimal characters.
   </para></listitem>

<listitem><para><emphasis role="bold">sha1:</emphasis>
   - A base64 SHA value to search for.  It is not automatically
     downloaded.</para></listitem>

<listitem><para><emphasis role="bold">urn:</emphasis>
   - Similar to a sha1 search, but the hash value is specified.
     Ie, urn:sha1:<emphasis>hash value</emphasis></para></listitem>
</itemizedlist>

</glossdef>
</glossentry>

<glossentry id="search_required"><glossterm>search requireds</glossterm>

<glossdef>

<para>
Mini filters are created with the '+' and '-' signs.  The plus sign
requires that a word is part of the results.  The minus sign doesn't
display any results with the given phrase.  The plus and minus signs
can be used to select ambigious terms.
</para>

<para>
Suppose you wish to find information about apples.  You might use a
search like <emphasis role="bold">apples -computers</emphasis>.  You
may get even more relevant results by using <emphasis
role="bold">apples +fruit</emphasis>.
</para>

</glossdef>
</glossentry>

</glossdiv>

<!-- ................................................................ -->

<glossdiv><title>U</title>

<glossentry id="ultrapeer"><glossterm>Ultrapeer</glossterm>

<glossdef> <para>An ultrapeer is well connected to the GnutellaNet.
As ultrapeers must have many connections and route search queries,
they require more resources than a leaf node.  Ultrapeers will
typically be connected to 30+ other ultrapeers and connected to 70+
leaf nodes. </para> 
<glossseealso otherterm="leaf">leaf node</glossseealso>
</glossdef>

</glossentry>

</glossdiv>

<!-- ................................................................ -->

</glossary>

<!-- <index> </index> -->

</book>


