# gtk-gnutella manual

## Foreword

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

## Getting started

### Network Introduction

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.

#### Peer to peer

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.

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.

### Installation

#### Getting gtk-gnutella

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.

Some web sights offer gtk-gnutella packages. RPM find and Linux App finder have packages for some popular Linux distributions. Also, the gtk-gnutella web site may contains some packages.

A better way to get gtk-gnutella is to install it yourself. The gtk-gnutella 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.

### First start

gtk-gnutella is abbreviated as GTKG for short.

#### GUI overview

A document called "Gnutella for users" is available on the Internet. GnuFU and also GnuFU .

The figure 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.

##### gtk-gnutella Screen Areas

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.

Area | Sub-Area | Short Description
Menu | 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.
Status Icons | Icons include CPU overload, file copying, library SHA, download SHA, library building, firewall and GnutellaNet status. Icons may change according to current conditions
Search Bar | Contains a text field for entering new search criteria. Also contains a drop-down filter selection button, and search and passive search buttons.
Working Area | This area changes depending on your current activity. It is one of the following nine items.
| GnutellaNet Connections | 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.
GnutellaNet Statistics | This working area has tabs along the top. Statistics relevant to the currently selected tab are shown.
GnutellaNet Hostcache | 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.
Downloads | 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.
Uploads | This working area shows files being sent to other gnutella nodes.
Upload History | This working area show previously sent files (or partially sent files).
Search Results | 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.
Search Monitor | Shows searches passing through our node.
Search Stats | Statistics about where searches are coming from etc.
Side bar | 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.
| Navigation Tree | 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").
Search List | Lists gtk-gnutella searches. Greyed values are inactive. Clicking on an item changes the working area to show that search.
GnutellaNet Status | Graphical summary of the GnutellaNet status.
Status bar | 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.

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 Network troubleshooting chapter.

There are also two dialog screens. Once is under the File menu and is named Preferences . 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 filters to improve search results.

##### gtk-gnutella activities

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!

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

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.

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.

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.

### Searching for files

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.

#### Search results

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.

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.

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.

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.

Leaf icon | Ultrapeer icon

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.

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.

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.

##### gtk-gnutella Searches

There are many prefixes that can be added to specialize a search. Literals and required phrases also have special notations.

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

Text Color | Description
Black | The default color representing a normal search result.
Dark red | This result is most definitely spam. These results may never be displayed depending on your configuration.
Bright red | The result is probably spam.
Blue | A user filter has marked this result.
Green | The file is currently being downloaded.
Gray | This result was ignored.
Indigo | The result came from a hostile host.
Marroon | These result were unrequested and delivered via OOB. They are possibly spam.

#### Bitzi and Magnet links

An alternative to searching with gtk-gnutella is to use a web site like Bitzi, magnetmix , or Freebase . 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.

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,

    #! /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 "about:config" in the address bar.
    # Right click and create a new string under the name
    # "network.protocol-handler.app.magnet".  Set the value to the
    # full path to this 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.

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

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

    if [ $# != 1 ] || [ "X$scheme" = X ]; then
       echo "Usage: ${0##*/} magnet:?[...]" >&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.' >&2
       exit 1
    }

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

    # Send a shell command to download the magnet URL.
    cat <<EOF | exec gtk-gnutella --shell
    intr
    download add "$url"
    EOF

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.

#### Search "Monitor"

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.

##### gtk-gnutella Search monitor

In either leaf or ultrapeer 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 GnutellaNet is targeting searches. Many of the search terms should be related to files you share.

#### Search "Stats"

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

### Downloading files

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.

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 completed download; it is just removed from the display. If the download is not completed, including the SHA check, the file will be deleted!

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.

#### gtk-gnutella downloads

### Sharing your own files

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.

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!

#### gtk-gnutella Uploads

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.

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

#### gtk-gnutella Upload Preferences

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).

#### gtk-gnutella upload history

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.

### Adjusting settings

#### gtk-gnutella Preferences dialog

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 networking section will also be of help. The remaining tabs are related to file sharing.

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).

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. OS Traffic shaping can limit this, or you can set limits here.

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.

Uploads configuration was covered in the Uploading chapter

## Advanced features

### Filtering

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.

#### Introduction

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.

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.

#### State flags

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.

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.

#### Filters

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

- 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.

- 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.

- 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.

#### Rules

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

- "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.

- The "Active" flag can be checked and unchecked to temporarily enable or disable a rule.

- 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.

##### Size rules

Size rules have three similar uses;

- 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.

- If both "minimum" and "maximum" is defined, the rule will cause a jump if the size is between the two values.

- If only "maximum" is given, the filter will jump if the result's size is larger than the given value.

##### Name rules

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

##### Flag rules

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.

##### Jump rules

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.

##### IP rules

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.

##### urn:sha1 rules

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).

##### State rules

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.

#### Tips

- 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.

- 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.

- 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".

#### Sample filters

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.

! | Condition | Target
| If filesize is smaller than 400000000 (381.5 MB) | DON'T DISPLAY
| If filename ends with ".avi" | RETURN
| If filename ends with ".mpg" | RETURN
| Always | DON'T DISPLAY

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.

! | Condition | Target
X | If filename contains the words "rammstein" | DON'T DISPLAY
X | If filename ends with "mpg" | DON'T DISPLAY
| If filesize is smaller than 20000000 (19.1 MB) | DON'T DISPLAY
X | If flag DON'T DISPLAY | DOWNLOAD

### The GnutellaNet pane

#### GnutellaNet

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.

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

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

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.

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".

### The Host Cache

#### gtk-gnutella Host Cache

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.

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.

### GnutellaNet Statistics

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

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.

## Trouble shooting

### Networking

#### NAT and firewalling.

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".

Start address | End address | CIDR range
10.0.0.0 | 10.255.255.255 | 10.0.0.0/8
172.16.0.0 | 172.31.255.255 | 172.16.0.0/12
192.168.0.0 | 192.168.255.255 | 192.168.0.0/16

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 . This URL also contains instructions on how to configure most routers to forward ports.

A critical item to know is the port used by gtk-gnutella. It can be found using the Preferences item from the File menu or by pressing Control-p. 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.

    grep listen_port ~/.gtk-gnutella/config_gnet

The gateway will use network address translation or NAT 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.

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

    #
    # 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

NOTE: Many consumer firewall products refer to DNAT as "DMZ". This is the wrong nomenclature, but it maybe what you want.

#### ISP filtering and shaping Gnutella traffic

Many ISPs have been known to filter or shape peer-to-peer traffic. The Azureus wiki gives an extensive list of ISPs known to filter or shape BitTorrent traffic. As can be seen from this discussion many of the same ISPs are shaping Gnutella traffic.

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 know is detecting Gnutella traffic, you can set the tls_enforce parameter. The tls_enforce parameter is set from the "Debugging" tab of the Preferences dialog (control-P). Type tls_enforce in the "Property pattern" and click on the value "FALSE" and change it to "TRUE".

If your ISP is not shaping traffic, there is no need to set the tls_enforce 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.

### OS Traffic shaping

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.

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.

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 iftop program is useful in observing bandwidth usage.

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

    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

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.

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 ip" will show only outbound traffic on most home networks (single IP). Your ip is your actual ip, found with "ifconfig" or any other method.

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.

#### BSD Traffic Shaping

Please add information here.

#### Linux Traffic Shaping

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.

The wondershaper and myshaper 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.

NOTE: 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.

### Headless mode

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.

See the chapter on getting gtk-gnutella on how to get the source code. The following "build.sh" invocation will produce a headless version of gtk-gnutella.

    ./build.sh --topless [...]

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.

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.

Now, you move the configuration directory for use by the headless gtk-gnutella:

     mv -i ~/.gtk-gnutella ~/.gtk-gnutella-headless

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:

     grep -Ev '^(guid|servent_kuid)' ~/.gtk-gnutella/config_gnet

    #! /bin/sh

    GTK_GNUTELLA_DIR=~/.gtk-gnutella-headless
    export GTK_GNUTELLA_DIR
    gtk-gnutella-headless --daemonize --log-stderr ~/tmp/error.log

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".

### Kernel mode PPPoE.

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.

Operating System | PPP additional info | Transfer rate | Ping | CPU usage | CPU usage breakdown
Linux 2.2 (64MB RAM) | usermode, async | ~4.1Mbits/s | 1.4/1.1 | 100% | pppoe 95%, nc 5%
Linux 2.2 (64MB RAM) | usermode, sync | Network max | 1.0/0.8 | 50% | pppoe 40%, nc 10%
Linux 2.4 (64MB RAM) | kernelmode | Network max | 0.7/0.5 | 26% | system 24%, nc 11%
NetBSD 1.6 (64MB RAM) | kernelmode | Network max | 0.9/0.5 | 23% | sys 15%, nc 17%
NetBSD 1.6 (32MB RAM) | kernelmode | Network max | 1.1/0.6 | 23% | sys 15%, nc 17%
FreeBSD 4.7 (64MB RAM) | usermode,sync | ~6.5Mbits/s | 2.0/1.9 | 100% | ppp 80%, nc 15%, int 5%
FreeBSD 4.7 (64MB RAM) | kernelmode | ~7.7Mbits/s | 0.7/0.5 | 35% | nc 17%, sys 16%, int 18%
OpenBSD 3.2 (64MB RAM) | usermode,sync | ~2.0Mbits/s | 2.9/2.3 | 99% | sys 87%, pppoe 65%, ppp 23%, nc 7%

This table is from an article entitled "PPPoE performance under Linux and BSDs" 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.

Disclaimer

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.

© 2002 Juuso Raitala <jraitala -at- jraitala dot net> (the main author of the article), Olli Vainio <odo -at- lyseo.edu.ouka.fi>, Juha K. Kallio <bunnyh -at- psychedelic.baana.suomi.net>,

## Glossary

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.

## G

GnutellaNet

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

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.

## L

Leaf node

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.

ultrapeers

## S

search literals

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 plus and minus signs.

search prefixes

- browse: - List shared files on the specified host. The format is "browse:ip_address:port". Many portions of the GUI have a menu option, available from a right click, that will browser the specified computer.

- http: - Download the specified web page. This could be a zip file, a movie, large JPEG, etc.

- local: - 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.

- magnet: - Search and download the magnet target.

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

- sha1: - A base64 SHA value to search for. It is not automatically downloaded.

- urn: - Similar to a sha1 search, but the hash value is specified. Ie, urn:sha1:hash value

search requireds

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.

Suppose you wish to find information about apples. You might use a search like apples -computers. You may get even more relevant results by using apples +fruit.

## U

Ultrapeer

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.

leaf node