From Gnutella Developers

<< Extending the Protocol | Handshaking >> | Main Page

In the early stages of the Gnutella protocol, there were several known permanent hosts whose purpose was to provide a list of Gnutella hosts to any Gnutella servent connecting to them. These were often called "hostcaches". However hostcaches are not used anymore.

To connect to the Gnutella network, a servent needs to find and store hosts' addresses. There are four ways by which a servent may get hosts' addresses:

  1. Calling a GWebCache
  2. Storing hosts' addresses read from X-Try and X-Try-Ultrapeers headers during handshakes (whether the handshake was successful or not).
  3. Storing hosts' addresses in pong messages (after at least one connection is established with the GNet).
  4. Storing hosts' addresses read from QueryHit messages (after a minimum of two connections are established with the GNet). This assumes that the remote servent uses the same port for upload slots than for GNet slots (which is the case with most servents).


The GWebCache (GWC) protocol allows to get hosts' addresses by sending an HTTP request to a GWebCache server (see (3.2) The WebCache System). However, great care should be taken to not over-query the web caches with too many requests. In most cases, it is not needed to query a GWebCache more than once per session. This means, notably, that if the user gets disconnected and opts to reconnect, the servent SHOULD NOT query a GWebCache.

Instead, a servent SHOULD implement a host cache (see (3.1) The Local Hostcache) to store the hosts found by any of the four ways described above, and use it in conjunction with the GWebCache System.

Below is a suggested bootstrapping algorithm which should ensure that the mean count of GWebCache calls per session is near (slightly above) one :

  • Launch the client and load the Local Hostcache.
  • Try to connect to the GNet, using the host cache.
  • If after a while, there's no connection to the GNet, query a random GWebCache.
  • Wait for a moment before sending a request to another GWC (it may happen that the first choosen GWC is down, or very slow to answer).
  • After a certain delay, if no results have been received from the first GWC call, call a new GWC periodically, until a response is received from one of them.
  • Once results have been received from (at least) one GWC, the servent SHOULD NOT send a new request during the next session, unless the host cache is empty (which should not happen if there is an initial host cache provided with the software and no option to clear the host cache is available).

The bootstrapping routine SHOULD also ensure that the servent does not try to connect too often to a remote host. Less than once per minute is a reasonable threshold. To make this possible, one solution is to ensure that the host cache always has enough host so no host is retried in less than a minute from its previous connection attempt.

Gnutella Handshake

Every servent SHOULD send an X-Try header during the handshake. This header gives a list of hosts to which the servent can attempt to connect, allowing it to get new host addresses without using the GWebCache. Example:


A servent SHOULD send a reasonable number of hosts, common values are between 10 and 20. However, the hosts sent with X-Try headers should have a good quality. Therefore, a servent SHOULD only include in these headers the remote hosts that were known to be still active recently (no more than a few minutes from the sending of the X-Try header). If there are less than 10 hosts recently seen as active, then send less. Hosts found in Pongs are supposed to have free slots if the servent implements a pong-caching scheme (see section 3.4). This is not the case for hosts obtained by monitoring the QueryHits. Thus, hosts found in Pongs are good candidates for placement in X-Try headers, while hosts found in QueryHits are not.

See Also

  • UDP Host Cache UDP-based Host Caching Protocol: the now preferred host-discovery method, based on Gnutella ping/pongs over UDP.

<< Extending the Protocol | Handshaking >> | Main Page