Gtk-Gnutella is currently sponsored by www.locatemyname.com. Try it!
- What is gnutella anyway?
- What is GTKG?
- This eats up too much bandwidth!
- What are Ultrapeers and Leaf nodes?
- Why does gtk-gnutella claim it's firewalled when it's not?
Building from source
- How do I find peers?
- What is a good number of connections?
- Do I need to forward a port on my firewall?
- How do I configure port forwarding?
- Does gtk-gnutella use UDP?
- What does "[FC]" mean?
- Why do I lose Gnutella peer connections when i have an upload?
- What does this stuff in the Flags column mean?
- What's the meaning of a leading "!" in the User-Agent name?
- What does "Harmful version banned, upgrade required" mean?
- What does "Outdated version, please upgrade" mean?
- Why doesn't my HTTP proxy work?
- How can I increase the timeouts?
- How does auto mode decide between ultrapeer and leaf?
- How can I get more results?
- How can I ignore files with no SHA1?
- Where did the search entry box go?
- What are "Passive" searches?
- Why are there unreadable results?
- What does the status "Ignoring requested [SHA1|name & size]" mean?
- What does the status "No URN on server" mean?
- Why is the same file downloaded X times?
- What is "swarming"?
- What is a "chunk"?
- What is the "download mesh"?
- What is a "push request"?
- Why does gtk-gnutella append a .OK to my filenames?
- I got a file that just won't download!
- In the downloads pane, what does it mean if the color of the text is grey instead of black?
- What is the filename encoding?
Gnutella is a decentralized Peer to Peer information exchanging network. At the moment you can publish and download files of any kind using the Gnutella network. The modern Gnutella protocol is officially documented at the GDF wiki. For more information, visit the definition of gnutella on the infoAnarchy wiki.
We often refer to gtk-gnutella as GTKG or gtkg (because it's shorter). GTK comes from GTK+ which is the graphical toolkit used by gtk-gnutella.
At the moment you can try one or more of the following things if you are a user on a slow line (modem):
- Run as a leaf node. You change the peermode setting in the configuration panel under GnutellaNet. An icon in the statusbar indicates in which mode you are running.
- Limit the number of Gnutella peer connections you have.
- If you are able to receive incoming connections, enable Prefer compressed connections in the Bandwidth control options.
- Even if you are on a slow connection, it's still important to share files. With swarming, people can upload small chunks of files from you, so even a slow connection, multiplied by many sources on the Gnutella network, makes a tremendous contribution. If you have a 56K modem, you can set Bandwidth limits for HTTP traffic - Cumulative upload rate to 1K/s so you still have the majority of your bandwidth for downloading.
- Depress the lower-left button in the GUI after your downloads have started. This will disconnect from the Gnutella network. We strongly advise you to NOT do that. You won't be able to get more alternate locations from the net and people won't be able to search your files.
Since version 0.92, gtk-gnutella has implemented ultrapeers and leaf nodes. This divides peers on the Gnutella network into leaf nodes, which connect only to ultrapeers, and ultrapeers, which connect to many leaf nodes and a small number of other ultrapeers (see What is a good number of connections?).
Ultrapeers must not be not firewalled, are expected to have long uptimes (more than two hours), and have sufficient surplus bandwidth to donate to the Gnutella network. Ultrapeers forward queries from their leaf nodes and leaf nodes upload to their ultrapeers QRP tables which contain hashes of keywords that will match files shared by the leaf. When an ultrapeer gets a hit on a query routing table, it relays the query to the corresponding leaf node. The result is very low Gnutella network traffic for each leaf node, freeing bandwidth for sharing and downloading (which still occur directly p2p.) Ultrapeers can also act as push-proxies for firewalled leaf nodes.
gtk-gnutella needs to receive an incoming connection to determine if you
can be reached from the outside. Until then, it's assumed that there's
a firewall which blocks the configured listening TCP port.
If you want to speed up the detection, use a web browser, telnet or similar
and connect to the listening port from the outside. If the connection is
refused or dropped, then you are very probably really unreachable due to a
firewall which blocks the port, a misconfigured NAT or similar. You might
want to try a different listening TCP port because some ISPs block the
default Gnutella port (6346).
Do I need to forward a port on my firewall?.
Building from source
Use the build.sh script instead of Configure!
You can set compile options on the command line too. Here is an example that will configure gtk-gnutella to
compile gtk-gnutella with the old Gtk+ 1.2 user-interface:
compile in debugging information while turning off all compiler
Thus, the resulting command-line looks like this:
$ ./build.sh --gtk1 --cflags="-g O0"
For available options and help regarding build.sh run this:
$ ./build.sh --help
Normally, gtk-gnutella finds peers all by itself within one or two minutes after starting it. However, if this doesn't work for you read how you can bootstrap gtk-gnutella manually and find peers to connect to.
In leaf mode 3 ultrapeers, in ultrapeer mode 32/40 (minimum/maximum) ultrapeers and around 100 leaf nodes. The actual number should depend on the available bandwidth. If you have set "Prefer compressed connections," bandwidth used will be much lower. You should never use up all your bandwidth with Gnutella peer connections. Especially on an asymmetric cable/DSL connection you can easily starve your incoming traffic by producing too much outgoing traffic (TCP/IP issue). Use at most half of your outgoing bandwidth for Gnutella peer connections.
Since the adoption of "high outdegree" in version 0.95 you should have 32/40 connections to other ultrapeers. The number of leaf connections to use depends on your bandwidth and the speed of your cpu. As an absolute minimum an ultrapeer should connect to 20 leaf nodes and it's much better to connect to 100 or more. Watch the bandwidth odometers on the lower left of the gui and use the top command to keep track of cpu usage. Increase the number of leaf connections until you reach the maximum amount of bandwidth and system resources you wish to devote to this purpose.
The bandwidth control settings will help you further fine-tune gtk-gnutella's bandwidth usage.
You don't need to forward any ports for gtk-gnutella to work, but it
will perform much better if you do. If gtk-gnutella thinks you are
firewalled, it will not show any "push" results since
you wouldn't be able to download those anyway.
Even when people cannot connect directly to you, they can still download files from your node using a push request.
You can configure the port gtk-gnutella listens on. The setting Listen port is located in the Settings->Preferences->Network.
The FC means "flow control".
In general, you should make sure that peers to which you are connected do not flow control. Watch for the trailing [FC] indication at the end of the Info string (you may need to drag the right edge past the window to trigger the underlying scroll bar), or look at the FC state in the Flags column. As a rule of thumb, if you have more than one node flow-controlling at a given time, you don't have enough outgoing bandwidth dedicated to the Gnutella network, and therefore you are harming the network: either decrease the amount of connections, enable the Prefer compressed connections option or raise the outgoing bandwidth limit.
Try to do bandwidth limiting. If that doesn't help, maybe your provider throttles gnutella traffic. Try changing your gnutella port in the network settings of gtk-gnutella.
You can see the type and some of the settings of a connection here. Note push-proxies are implemented in 0.92.1c and later.
012345678AB (offset) NIrwqxZPFhE ||||||||||+ indicates a TLS-encrypted connection |||||||||+- hops flow triggered (h), or total query flow control (f) ||||||||+-- flow control (F), or pending data in queue (d) |||||||+--- we are push-proxy for node (P) or node is our push-proxy (p) ||||||+---- indicates whether Rx, Tx or both (Z) are compressed |||||+----- we sent our last-hop QRT to remote UP (X), or are sending one (x) ||||+------ we sent/received a QRT, or are sending/receiving one (q) |||+------- indicates whether node is writable ||+-------- indicates whether node is readable |+--------- connection type: (Incoming, Outgoing, Ponging) +---------- peer mode: Ultra, Leaf, or Legacy (a.k.a. Normal)
This indicates that the User-Agent name is possibly faked but it could be a false-positive caused by a bad clock on either side.
Sometimes, peers are discovered to have a bug or behaviour that is harmful to the Gnutella network. For example, gtk-gnutella-0.92b had a bug that generated excessive queries which hammered on the GWebCache system. Such banning is exceptional, usually restricted to specific versions, and the author of the software is informed about the banning.
Versions of gtk-gnutella more than one year old are banned, since they lack features that are important to the rapidly evolving health and scalability of the Gnutella network. In addition, unstable versions are banned after 90 days.
Your HTTP proxy must support the method
CONNECT because a normal
doesn't work with Gnutella connections. This is an extension to the HTTP
protocol and mainly supported by SQUID proxies. It's also often deactivated
because it might be considered a security problem by your provider. At the
moment, the proxy support - also for SOCKS - isn't very good. The developers
don't use proxies but if you think you can fix it, we would appreciate
If your internet connection suffers from high latency it might help to increase the timeouts. Go to Settings->Preferences->User Interface and tick Expert mode. Now, you'll find a lot more settings to change when you go to Settings->Preferences->GnutellaNet.
In order to be promoted to ultrapeer mode the following conditions must be met:
- There must be more than 8192 bytes/s outgoing bandwidth available.
- If bandwidth schedulers are enabled, leaf nodes must not be configured to steal all the HTTP outgoing bandwidth.
- If Gnutella network output scheduler is enabled, there must be at least 256 bytes/s per Gnutella network connection (ultrapeer or normal aka legacy).
- Overall, there must be 32 bytes/s per configured leaf plus 256 bytes/s per Gnutella peer connection available.
Click with right mouse button on a search result without a SHA1 and select "Drop results...->with the same urn:sha1" from the popup menu. That will drop all results with this SHA1 - in this case none - from your results. You'll miss a lot of spam.
Searches are now entered in the
Search: box in the sidebar.
passive search will return all the search results that
pass through gtk-gnutella. By
filtering these results,
passive searches can be useful.
If you are in ultrapeer mode, many search
results are already passing through your node besides the ones for your own
searches. You can take advantage of this to make searches without generating
any extra Gnutella network traffic. For example, on my ultrapeer with 200
leaf nodes, I opened a passive search and
filtered the results to display only hits with the name
eminem. Within an hour or so I had about 1500 results.
Obviously, the more popular the search, and the more patient you are, the
more useful this technique is.
If you are in leaf mode, then the only search results that will pass through gtk-gnutella will be those from your own searches, so the above technique won't be useful. But there is another way to use passive searches that is only useful in leaf mode. For example, if you start a passive search and filter it to display only mp3 files, then all mp3 files from all your open searches will be conveniently aggregated in one search window. By opening more passive searches with different filters, you can display different file types in each.
The standard encoding in the modern Gnutella network is UTF-8. All queries and results should be encoded this way. Unfortunately, there is still many legacy software that does not convert textual data (like filenames and queries) to UTF-8 but uses arbitrary character sets instead. gtk-gnutella tries to detect the used character set but this cannot be perfect. It may also replace characters with underscores if they cannot be converted to UTF-8.
This means that gtk-gnutella has that file recorded as complete in its
database. This database is usually located in
At the moment, there is no way to remove or modify
an entry of that database from the gui, but you can edit the file with any
text editor while gtk-gnutella is not running. If you add or remove something
from one of the files, do the same to the other.
This means that gtk-gnutella wants to download a new file from a host, but
that host does not provide a SHA1 hash for the file. Since the file is new
(not yet partially downloaded), gtk-gnutella cannot do an overlap check to
verify that the file on the host is really the file you want. In such a case
it relies on the SHA1 provided by the remote host, but if no SHA1 is
supplied, then gtk-gnutella has no way of assuring that the file it wants to
download and the file on the remote server are really the same.
If you get annoyed by those messages you can activate the Optimistic first chunk option in the Settings->Preferences->Download.
Swarming describes the ability to download a single file from multiple hosts in parallel. gtk-gnutella will automatically try to find additional sources for any queued file using the download mesh and by monitoring routed results.
A chunk is another word for part of a file. When gtk-gnutella runs in swarming mode it will retrieve multiple chunks of a downloading file until it has downloaded the complete file. The Range column shows you which chunk you are currently downloading.
When you download a file from a host that supports the download mesh, it will tell you about additional sources for the requested file (provided it knows of any). Those will then be used for swarming
The push request is a facility to download files from hosts you cannot
connect to directly (because they are firewalled). Well, you cannot
connect to those hosts, but they probably can connect to you. To
tell a remote host to connect to your host so that you can download
a file from the remote host you send a push request to it.
If you download a file using a push request and you loose contact to the host which originally returned the result for that file to you, then the push route is lost and you can no longer download this file. Therefore push routes are quite fragile. You can't make use of push requests when you are behind a firewall (see port forwarding).
You probably haven't set up different directories for downloaded files, temporary files and bad files.
If you don't see a smiling yellow icon with sunglasses in the statusbar, you should try to change that. See the section about firewalls.
Otherwise if gtk-gnutella says it has only a few sources for the file (best seen in the fileinfo subtab in the downloads pane) then this can have two reasons:
- the file is a rare one
- You selected a version of the file that is unique. Chances are that there may be a more common version. A file can become unique e.g. when somebody changes the mp3info on an mp3 file or otherwise does some custom modification to the file.
You can try to search for the file again and see if you find another version which is more common. It's usually a good indication if the "#" shows a number for a file. The larger the number, the better are the chances that you can get it quickly.
It means that the file is received over a push route.
gtk-gnutella uses UTF-8 as default encoding for filenames. If your locale setting does not use UTF-8, other applications may not display these filenames correctly or may have problems accessing them in the worst case. You can change the encoding using the environment variable G_FILENAME_ENCODING. This affects most applications that use Gtk+ or GLib.
If your system does not use UTF-8, it is recommend to use either G_FILENAME_ENCODING="UTF-8,@locale,ISO-8859-1" or G_FILENAME_ENCODING="@locale,UTF-8,ISO-8859-1" .
The first item in the list is the encoding used to store files. Following items are character sets used to convert existing filenames as found on the disk to UTF-8 for display purposes and information exchange. For people from Western Europe it is recommendable to add ISO-8859-1 as shown above to the list if you share any files that contain non-ASCII characters and which are encoded as ISO-8859-1 characters. For people from other regions of the world, other character sets might be more appropriate.
In most cases, the special item "@locale" takes care of this. This stands for the encoding used by the current locale and it's very likely that filenames are encoded with it. You can list multiple secondary filename character sets. When converting filenames to UTF-8, the first successful conversion will be used. The character sets are tried in the listed order. Non-convertible characters are replaced with underscores. This means if you download a file with mostly Arabic or Japanese characters in it, converting the filename to ASCII or ISO-8859-1 strips most or all information from the filename. Therefore it's best to stick with UTF-8.
gtk-gnutella supports G_FILENAME_ENCODING since version 0.96 regardless whether you use Gtk+ 1.2 or Gtk+ 2.x as front-end.
This shows the total amount of bytes uploaded for the file divided by the file size.
Gtk+ 2.x has complex and powerful font-rendering. There's hope that future versions will be much more optimized. If the performance is unacceptable, you should consider using Gtk+ 1.2 instead. However, if you switch to a pane with little action and minimize the window, the performance difference is negligible.