Gnutella2 - User contributions [en]

KHLA

2009-01-29T09:49:34Z

CyberBob: Fixed typo

{{Packets}}

= /KHLA =

The known hub list acknowledgement packet is part of UKHL implementation, used to
answer back to request of packet list of known Gnutella2 hubs with /KHLR packet.

== Sending ==

This packet should be sent through UDP when received /KHLR packet.

== Receiving ==

Upon receiving a known hub list, the detailed hubs should be stored in appropriate data structures.

== Payload ==

This packet has no payload at the current time.

== Children ==

This packet has several child packet types defined at the current time:

* /KHLA/UKHLID - Unique ID
* /KHLA/YOURIP - IP address of requester.
* /KHLA/URL - URL to UKHL services for bootstrap propagation.
* /KHLA/TS - Timestamp
* /KHLA/NH - Neighbouring Hub
* /KHLA/CH - Cached Hub

== /KHLA/UKHLID - Unique ID ==

Unique ID which must be same as sent on corresponding /KHLR packet. Client requesting
Known Hub List should compare if ID is same as corresponding /KHLR packet for security
reason.

=== Sending ===

This child is optional but recommended.

=== Payload ===

16Byte unique ID such as GUID.

== /KHLA/TS - Timestamp ==

The /KHLA/TS child provides a timestamp representing the current universal time at
the sending node. This can be used as a reference when considering other
timestamps in the packet, allowing them to be adjusted to eliminate differences
between the time setting on the local and remote node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

A 32-bit integer representing the current UNIX time, or time (NULL).

=== Children ===

This packet has no known children at the current time.

== /KHLA/NH - Neighbouring Hub ==

This child packet represents a neighbouring hub.

=== Sending ===

One should be included for each Gnutella2 neighbour hub, with the possible
exception of the one to which this packet is being sent.

=== Payload ===

The node address of the hub. See [[datatypes]] for more information.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/NH/GU - GUID
* /KHLA/NH/V - Vendor Code
* /KHLA/NH/LS - Library Statistics
* /KHLA/NH/HS - Hub Status

=== /KHLA/NH/GU - GUID ===

The /KHLA/NH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/V - Vendor Code ===

The /KHLA/NH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/HS - Hub Status ===

The /KHLA/NH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

== /KHLA/CH - Cached Hub ==

This child packet represents a hub from the hub cache.

=== Sending ===

An arbitrary number of these children should be included, constrained by space and
the number of available cached hubs. A selection of freshly time stamped but
previously unknown hubs should be included, and the list should not include hubs in
the local cluster.

=== Payload ===

The node address of the hub, followed by the time this hub was last seen as a 32-bit
timestamp. The last seen time can be adjusted based on the difference between the
/KHLA/TS timestamp and the local time. Note that the node address is of variable
length, so it is important to consider the last 4 bytes as the timestamp rather than
assuming a fixed length node address.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/CH/GU - GUID
* /KHLA/CH/V - Vendor Code
* /KHLA/CH/LS - Library Statistics
* /KHLA/CH/HS - Hub Status

This extra information is considered less relevant for a cached hub because it is
unlikely to be up to date enough to be useful.

=== /KHLA/CH/GU - GUID ===

The /KHLA/CH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/V - Vendor Code ===

The /KHLA/CH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/HS - Hub Status ===

The /KHLA/CH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

KHLA

2009-01-29T03:05:14Z

CyberBob: tiny update

{{Packets}}

= /KHLA =

The known hub list acknowledgement packet is part of UKHL implementation, used to
answer back to request of packet list of known Gnutella2 hubs with /KHLR packet.

== Sending ==

This packet should be sent through UDP when received /KHLR packet.

== Receiving ==

Upon receiving a known hub list, the detailed hubs should be stored in appropriate data structures.

== Payload ==

This packet has no payload at the current time.

== Children ==

This packet has several child packet types defined at the current time:

* /KHLA/UKHLID - Unique ID
* /KHLA/YOURIP - IP address of requester.
* /KHLA/URL - URL to UKHL services for bootstrap propagation.
* /KHLA/TS - Timestamp
* /KHLA/NH - Neighbouring Hub
* /KHLA/CH - Cached Hub

== /KHLA/UKHLID - Unique ID ==

Unique ID which must be same as sent on corresponding /KHLR packet. Client requesting
Known Hub List should compare if ID is same as corresponding /KHLR packet for sequrity
reason.

=== Sending ===

This child is optional but recommended.

=== Payload ===

16Byte unique ID such as GUID.

== /KHLA/TS - Timestamp ==

The /KHLA/TS child provides a timestamp representing the current universal time at
the sending node. This can be used as a reference when considering other
timestamps in the packet, allowing them to be adjusted to eliminate differences
between the time setting on the local and remote node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

A 32-bit integer representing the current UNIX time, or time (NULL).

=== Children ===

This packet has no known children at the current time.

== /KHLA/NH - Neighbouring Hub ==

This child packet represents a neighbouring hub.

=== Sending ===

One should be included for each Gnutella2 neighbour hub, with the possible
exception of the one to which this packet is being sent.

=== Payload ===

The node address of the hub. See [[datatypes]] for more information.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/NH/GU - GUID
* /KHLA/NH/V - Vendor Code
* /KHLA/NH/LS - Library Statistics
* /KHLA/NH/HS - Hub Status

=== /KHLA/NH/GU - GUID ===

The /KHLA/NH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/V - Vendor Code ===

The /KHLA/NH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/HS - Hub Status ===

The /KHLA/NH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

== /KHLA/CH - Cached Hub ==

This child packet represents a hub from the hub cache.

=== Sending ===

An arbitrary number of these children should be included, constrained by space and
the number of available cached hubs. A selection of freshly time stamped but
previously unknown hubs should be included, and the list should not include hubs in
the local cluster.

=== Payload ===

The node address of the hub, followed by the time this hub was last seen as a 32-bit
timestamp. The last seen time can be adjusted based on the difference between the
/KHLA/TS timestamp and the local time. Note that the node address is of variable
length, so it is important to consider the last 4 bytes as the timestamp rather than
assuming a fixed length node address.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/CH/GU - GUID
* /KHLA/CH/V - Vendor Code
* /KHLA/CH/LS - Library Statistics
* /KHLA/CH/HS - Hub Status

This extra information is considered less relevant for a cached hub because it is
unlikely to be up to date enough to be useful.

=== /KHLA/CH/GU - GUID ===

The /KHLA/CH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/V - Vendor Code ===

The /KHLA/CH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/HS - Hub Status ===

The /KHLA/CH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

KHLA

2009-01-29T03:03:21Z

CyberBob: Added detail of KHLA packet. (incomplete)

{{Packets}}

= /KHLA =

The known hub list acknowledgement packet is part of UKHL implementation, used to
answer back to request of packet list of known Gnutella2 hubs with /KHLR packet.

== Sending ==

This packet should be sent through UDP when received /KHLR packet.

== Receiving ==

Upon receiving a known hub list, the detailed hubs should be stored in appropriate
data structures. Neighbouring hubs must be retained in the hub cluster records,
while cached hubs should be merged with the local accessible hub cache.

== Payload ==

This packet has no payload at the current time.

== Children ==

This packet has several child packet types defined at the current time:

* /KHLA/UKHLID - Unique ID
* /KHLA/YOURIP - IP address of requester.
* /KHLA/URL - URL to UKHL services for bootstrap propagation.
* /KHLA/TS - Timestamp
* /KHLA/NH - Neighbouring Hub
* /KHLA/CH - Cached Hub

== /KHLA/UKHLID - Unique ID ==

Unique ID which must be same as sent on corresponding /KHLR packet. Client requesting
Known Hub List should compare if ID is same as corresponding /KHLR packet for sequrity
reason.

=== Sending ===

This child is optional but recommended.

=== Payload ===

16Byte unique ID such as GUID.

== /KHLA/TS - Timestamp ==

The /KHLA/TS child provides a timestamp representing the current universal time at
the sending node. This can be used as a reference when considering other
timestamps in the packet, allowing them to be adjusted to eliminate differences
between the time setting on the local and remote node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

A 32-bit integer representing the current UNIX time, or time (NULL).

=== Children ===

This packet has no known children at the current time.

== /KHLA/NH - Neighbouring Hub ==

This child packet represents a neighbouring hub.

=== Sending ===

One should be included for each Gnutella2 neighbour hub, with the possible
exception of the one to which this packet is being sent.

=== Payload ===

The node address of the hub. See [[datatypes]] for more information.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/NH/GU - GUID
* /KHLA/NH/V - Vendor Code
* /KHLA/NH/LS - Library Statistics
* /KHLA/NH/HS - Hub Status

=== /KHLA/NH/GU - GUID ===

The /KHLA/NH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/V - Vendor Code ===

The /KHLA/NH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/NH/HS - Hub Status ===

The /KHLA/NH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

== /KHLA/CH - Cached Hub ==

This child packet represents a hub from the hub cache.

=== Sending ===

An arbitrary number of these children should be included, constrained by space and
the number of available cached hubs. A selection of freshly time stamped but
previously unknown hubs should be included, and the list should not include hubs in
the local cluster.

=== Payload ===

The node address of the hub, followed by the time this hub was last seen as a 32-bit
timestamp. The last seen time can be adjusted based on the difference between the
/KHLA/TS timestamp and the local time. Note that the node address is of variable
length, so it is important to consider the last 4 bytes as the timestamp rather than
assuming a fixed length node address.

=== Children ===

This packet has several child packet types defined at the current time:

* /KHLA/CH/GU - GUID
* /KHLA/CH/V - Vendor Code
* /KHLA/CH/LS - Library Statistics
* /KHLA/CH/HS - Hub Status

This extra information is considered less relevant for a cached hub because it is
unlikely to be up to date enough to be useful.

=== /KHLA/CH/GU - GUID ===

The /KHLA/CH/GU child packet specifies the globally unique identifier of the hub.

==== Sending ====

This child is optional.

==== Payload ====

The 16 byte globally unique node identifier of the hub.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/V - Vendor Code ===

The /KHLA/CH/V child packet specifies the vendor code of the software operating the
hub.

==== Sending ====

This child is optional.

==== Payload ====

A four byte vendor code.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/LS - Library Statistics ===

The /KHLA/NH/LS packet provides information about the content library of the hub
and its connected leaves.

==== Sending ====

This child is optional.

==== Payload ====

Two 32-bit integers representing the number of files, and the total KB of available
content in the hub's own library and the libraries of its connected leaves. The
payload may grow beyond 8 bytes in the future.

==== Children ====

This packet has no known children at the current time.

=== /KHLA/CH/HS - Hub Status ===

The /KHLA/CH/HS packet contains the status of the hub.

==== Sending ====

This child is optional.

==== Payload ====

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

==== Children ====

This packet has no known children at the current time.

Template:Root packet list

2009-01-29T02:40:51Z

CyberBob: Added UKHL packet types to root packet list

* /[[CRAWLA]] - Crawler Answer
* /[[CRAWLR]] - Crawler Request
* /[[HAW]] - Hub Advertisement Walker
* /[[KHL]] - Known Hub List
* /[[KHLR]] - Known Hub List Request
* /[[KHLA]] - Known Hub List Acknowledgement
* /[[LNI]] - Local Node Information
* /[[PI]] - Ping
* /[[PO]] - Pong
* /[[PUSH]] - Push
* /[[QKA]] - Query Key Acknowledgement
* /[[QKR]] - Query Key Request
* /[[Q2]] - Gnutella2 Query
* /[[QA]] - Query Acknowledgement
* /[[QH2]] - Gnutella2 Query Hit
* /[[QHT]] - Query Hash Table
* /[[UPROC]] - User Profile Challenge
* /[[UPROD]] - User Profile Delivery

HAW

2008-03-13T06:06:21Z

CyberBob: added some detail of HAW packet. (still incomplete)

[[CRAWLR|<< CRAWLR]] | [[KHL|KHL >>]] | [[Root_packets_index|Packet Index]]

= /HAW - Hub Advertising Walker =

The HAW packet ...

== Sending ==

The /HAW packet ... TODO

== Receiving ==

Upon receiving HAW packet, re-send packet to another neighbour. reduce TTL and increase Hops should be done before re-send.

== Payload ==

* 1byte TTL
* 1byte Hops
* 16byte GUID

TTL should probably be 100 and Hops should be set to 0 when packet first created. GUID is not node ID, it is packet ID for determine where the packet should be routed. rule of routing is if TTL has enough amount, and the packet has ever been to routed to the neighbour. as GUID on HAW packet is not node ID, it can be used to determine if the packet has been routed to the neighbour or not.

== Children ==

The /HAW packet has the following child packets defined:

* /HAW/NA - Network Address
* /HAW/HS - Hub Status
* /HAW/V - Vendor Code

Source Exchange (x-G2alt)

2007-07-01T13:53:44Z

CyberBob: fixed format bug

'''Source Exchange (x-G2alt)'''

Source exchange on Gnutella2 is done by HTTP header "x-G2Alt:" in transfer connection. format of the header is basically similar to "x-alt" header of Gnutella source exchange, however there is slight difference for sources behind firewall.

'''Specification'''

X-G2ALT:( <DALT> | <PALT> )

DALT: ( <IP>[:<PORT>] )

PALT: ( <GUID>[!<DALT>]@<DALT>(|<DALT>)+ )
( first DALT above is optional which tells PALT's IP:PORT.
second one is PALT's conected Hub addresses deliminated
by pipe symbol("|") )

IP: ( standard string representation of an IP Address.
i.e. Typical dotted IP Address a.b.c.d )

PORT: ( text number representing the port.
If 6346, you MAY omit it )

GUID: ( Base32 encoded version of the proxied hosts'
16-byte Gnutella2 GUID )

'''Example'''

X-G2ALT: 111.222.33.44:5555
X-G2ALT: 111.222.33.44, 55.66.77.88:9999
X-G2ALT: ABCDEFGHIJKLMNOPQRSTUVWXYZ@111.222.33.44:5555|66.77.88.99
X-G2ALT: 55.66.77.88:9999, ABCDEFGHIJKLMNOPQRSTUVWXYZ@111.222.33.44:5555|66.77.88.99

Source Exchange (x-G2alt)

2007-07-01T13:51:34Z

CyberBob: added a proposal

Main Page

2007-07-01T13:38:56Z

CyberBob: /* Proposals */

<table width="100%" ><tr>
<td align="left">
== Gnutella2 Developer Network ==
Welcome to the Gnutella2 Developer Network.
The Gnutella2 Developer Network (or G2DN) is a convenient central location for discussing, developing and documenting all aspects of Gnutella2. Like the Gnutella2 platform itself, this website is designed to evolve through community support and participation. Everyone is free to contribute discussion, proposal documents, developer resources or any other relevant material.

<p>Although the G2DN is primarily geared toward developers and technical enthusiasts, users of Gnutella2-enabled software are also welcome to participate. Those who are new to Gnutella2 may wish to check out some of the [[Gnutella2-powered software]].</p></td>
<td width="20px"></td>
<td align="right" valign="bottom" width="200px">
__TOC__
</td></tr>
</table>

==News==
* ''29th, March, 2007'' - '''[[TCP Stream Connection and Handshaking]] specification updated.'''
* ''10th, April, 2005'' - '''Gnutella2 website re-opened'''
<p>After server problems we're proud to re-launch the Gnutella2 website. It is now based on MediaWiki (like Wikipedia). The forums are gone, but we now have a [[mailing list]] for Gnutella2 related discussion. Feel free to contribute to the wiki after reading [[Gnutella2:Community Portal]] to learn about editing policy.</p>

==Mailing List==
To allow communication among developers of Gnutella2 clients, there exists a [[mailing list]]. You can access it too via regular news reader at the news-to-mail gateway [http://www.gmane.org Gmane] (list page [http://dir.gmane.org/gmane.network.gnutella2.devel here]).

== The Gnutella 2 Network==
# [[Gnutella2|What is Gnutella2]]
# [[Gnutella2 Standard]]
# [[Network Architecture]]
# [[Node Types and Responsibilities]]
# [[Background|Background / Archive]]

== The Protocol==
# [[TCP Stream Connection and Handshaking]]
# [[UDP Transceiver]]
# [[Packet Structure]]
# [[Datatypes]]
# [[Basic Network Maintenance]]
# [[Known Hub Cache and Hub Cluster Cache]]
# [[Node Route Cache and Addressed Packet Forwarding]]
# [[Query Hash Tables]]
# [[Object Search Mechanism]]
# [[Search Security]]
# [[Search Description]]
# [[Search Acknowledgement]]
# [[Search Results]]
# [[Simple Query Language and Metadata]]
# [[Server for Uploading]]
# [[Client for Downloading]]
# [[User Profile Challenge and Delivery]]

== Root Packets ==
{{Root packets}}

== Proposals==
* [[Active Source Exchange]] (ASE) by Kevin O'Toole
* [[Source Exchange (x-G2alt)]]

== Additional Information==
Since Gnutella2 somehow evolved from the original Gnutella protocol you might find the following links useful:
* [http://www.the-gdf.org The GDF Wiki]
* [http://groups.yahoo.com/group/the_gdf/ Gnutella Developer forum]
* [http://rfc-gnutella.sourceforge.net/ RFC Gnutella]
* [http://draketo.de/inhalt/krude-ideen/gnufu_en.html Gnutella for Users (GnuFU)]
* [http://crawler.trillinux.org/ Gnutella2 Crawler]

Main Page

2007-03-29T06:24:47Z

CyberBob: added recent change to News secrion of top page.

<table width="100%" ><tr>
<td align="left">
== Gnutella2 Developer Network ==
Welcome to the Gnutella2 Developer Network.
The Gnutella2 Developer Network (or G2DN) is a convenient central location for discussing, developing and documenting all aspects of Gnutella2. Like the Gnutella2 platform itself, this website is designed to evolve through community support and participation. Everyone is free to contribute discussion, proposal documents, developer resources or any other relevant material.

<p>Although the G2DN is primarily geared toward developers and technical enthusiasts, users of Gnutella2-enabled software are also welcome to participate. Those who are new to Gnutella2 may wish to check out some of the [[Gnutella2-powered software]].</p></td>
<td width="20px"></td>
<td align="right" valign="bottom" width="200px">
__TOC__
</td></tr>
</table>

==News==
* ''29th, March, 2007'' - '''[[TCP Stream Connection and Handshaking]] specification updated.'''
* ''10th, April, 2005'' - '''Gnutella2 website re-opened'''
<p>After server problems we're proud to re-launch the Gnutella2 website. It is now based on MediaWiki (like Wikipedia). The forums are gone, but we now have a [[mailing list]] for Gnutella2 related discussion. Feel free to contribute to the wiki after reading [[Gnutella2:Community Portal]] to learn about editing policy.</p>

==Mailing List==
To allow communication among developers of Gnutella2 clients, there exists a [[mailing list]]. You can access it too via regular news reader at the news-to-mail gateway [http://www.gmane.org Gmane] (list page [http://dir.gmane.org/gmane.network.gnutella2.devel here]).

== The Gnutella 2 Network==
# [[Gnutella2|What is Gnutella2]]
# [[Gnutella2 Standard]]
# [[Network Architecture]]
# [[Node Types and Responsibilities]]
# [[Background|Background / Archive]]

== The Protocol==
# [[TCP Stream Connection and Handshaking]]
# [[UDP Transceiver]]
# [[Packet Structure]]
# [[Datatypes]]
# [[Basic Network Maintenance]]
# [[Known Hub Cache and Hub Cluster Cache]]
# [[Node Route Cache and Addressed Packet Forwarding]]
# [[Query Hash Tables]]
# [[Object Search Mechanism]]
# [[Search Security]]
# [[Search Description]]
# [[Search Acknowledgement]]
# [[Search Results]]
# [[Simple Query Language and Metadata]]
# [[Server for Uploading]]
# [[Client for Downloading]]
# [[User Profile Challenge and Delivery]]

== Root Packets ==
{{Root packets}}

== Proposals==
* [[Active Source Exchange]] (ASE) by Kevin O'Toole

== Additional Information==
Since Gnutella2 somehow evolved from the original Gnutella protocol you might find the following links useful:
* [http://www.the-gdf.org The GDF Wiki]
* [http://groups.yahoo.com/group/the_gdf/ Gnutella Developer forum]
* [http://rfc-gnutella.sourceforge.net/ RFC Gnutella]
* [http://draketo.de/inhalt/krude-ideen/gnufu_en.html Gnutella for Users (GnuFU)]
* [http://crawler.trillinux.org/ Gnutella2 Crawler]

TCP Stream Connection and Handshaking

2007-03-28T16:54:03Z

CyberBob: changed "X-Ultrapeer" to "X-Hub". this should be used for Gnutella2

[[UDP_Transceiver|UDP Transceiver >>]] | [[Main_Page|Main Page]]

== Introduction ==

TCP stream connections are established between Gnutella2 nodes when they elect to
form a permeant link, creating the fundamental network topology of a highly
interconnected hub network serving dense clusters of leaf nodes.

== Initiation ==

TCP connections are initiated by leaf or hub nodes in an attempt to gain a connection
to a hub node. Leaf nodes are never the target of an outbound connection. The TCP
port number is not standardised, and must be stored with the IP address.

== Handshaking ==

Upon the establishment of a TCP stream connection between two Gnutella2 nodes, a
handshaking phase must be completed to negotiate the nature of the link and
exchange other necessary information.

This handshaking phase is the only part of the communication which remains
compatible with the old Gnutella network, allowing new connections to be negotiated
without fore-knowledge the capabilities of the other node. The handshaking process
has been well documented elsewhere, however, a short summary is provided here.

=== Handshake Stages ===

The Gnutella handshake process consists of three header blocks. The node which
initiated the connection sends an initial header block, of the form:

<pre>
<nowiki>
GNUTELLA CONNECT/0.6
Listen-IP: 1.2.3.4:6346
Remote-IP: 6.7.8.9
User-Agent: Shareaza 1.8.2.0
Accept: application/x-gnutella2
X-Hub: False
</nowiki>
</pre>

The receiver then responds with its own header block:

<pre>
<nowiki>
GNUTELLA/0.6 200 OK
Listen-IP: 6.7.8.9:6346
Remote-IP: 1.2.3.4
User-Agent: Shareaza 1.8.2.0
Content-Type: application/x-gnutella2
Accept: application/x-gnutella2
X-Hub: True
X-Hub-Needed: False
</nowiki>
</pre>

Finally, the initiator accepts the receiver's header block, and provides any final
information:

<pre>
<nowiki>
GNUTELLA/0.6 200 OK
Content-Type: application/x-gnutella2
X-Hub: False
</nowiki>
</pre>

The latter two stages may be replaced with an error condition if the connection is
being rejected. Appropriate error status codes are returned in this case, for example:

<pre>
<nowiki>
GNUTELLA/0.6 503 Too many connections
(more headers)
</nowiki>
</pre>

Note that only the HTTP-style error code should be interpreted by the software: any
descriptive text provided is for display purposes only and is not standardised.

== Headers ==

Important headers which are required or strongly recommended are detailed in the
following sections.

=== Addressing Headers ===

Two important headers to send on all connections are "Remote-IP" and "Listen-IP".
Both of these headers should be sent on the first transmission, meaning in the first
and second header blocks in the three block exchange.

The Remote-IP header contains the IP address from which the remote host is
connecting. This allows a remote host operating through some kind of network
address translation system, to learn its effective external address.

The Listen-IP header contains the IP address and port number that the local host is
listening for inbound TCP connections on. It should be listening for UDP datagrams
on the same port. The format of this header is "IP:PORT", eg "1.2.3.4:6346".

=== Identification ===

The User-Agent header is used to identify the client software operating on the
sending node. It should be sent on the first transmission, meaning in the first and
second header blocks in the three block exchange. Note that this is a descriptive
string that often includes a version number, and is not a "vendor code" as described
elsewhere.

=== Content Type (Protocol) ===

The Accept and Content-Type header exchange is used to negotiate the data
protocol that will be used in the connection, in this case Gnutella2. The Gnutella2
content type is "application/x-gnutella2", and this exchange follows standard HTTP
rules for negotiating content type.

The first step is to advertise support for the content type (Gnutella2) in the first
header block with "Accept: application/x-gnutella2". The responding node will then
indicate that it will send Gnutella2 content with "Content-Type: application/xgnutella2",
and that it also supports Gnutella2 with "Accept: application/x-gnutella2".
The initiating host then confirms that it will be sending Gnutella2 with "Content-
Type: application/x-gnutella2" in the third header block. For more information on the
Accept/Content-Type exchange, consult a HTTP reference.

Note that the content type negotiation process is designed to be a "one-way"
process, i.e. a different content type can be negotiated for sending and receiving.
However, when the gnutella2 protocol is negotiated, both channels must use the
same content type. This means that a receiving node must not accept Gnutella2 if
the initiator did not advertise support for it, and if at the end of the handshake,
bidirectional Gnutella2 was not negotiated, the connection should be terminated.

=== Node State Negotiation ===

There are two node types in a Gnutella2 peer to peer network, a hub and a leaf, as
described in [[Node Types and Responsibilities]]. During the initial handshake,
the two parties must exchange their current node type and advise of their
capabilities, negotiating the node types they will adopt when the connection
completes, and indeed whether it should complete at all.

As the handshake sequence is compatible with Gnutella1, the headers involved in
negotiating node types should not be identical to those used to negotiate Gnutella1 to minimize network pollution.
states:

<pre>
<nowiki>
X-Hub: [True|False]
X-Hub-Needed: [True|False]
</nowiki>
</pre>

Both headers contain a Boolean value, "true" or "false", case insensitive.

The X-Hub header indicates whether the transmitting node is currently
operating as a hub. Hub nodes will send "X-Hub: True" while leaf nodes will
send "X-Hub: False".

The X-Hub-Needed header indicates whether the transmitting node would like
(and allow) the receiver to be a hub. A hub which sees no need for additional hubs in
its area of the network, will send "X-Hub-Needed: False", indicating to the
connecting node that it must operate in leaf mode if it wishes to connect. A hub
which sees a need for additional hubs, will send "X-Hub-Needed: True",
indicating that the receiving node should become a hub, if it is capable of doing so. A
leaf may send "X-Hub-Needed: True" to indicate that it is seeking a connection
to a hub.

The X-Hub header should be sent on all three of the header blocks to indicate
the current intended state of the node, while the X-Hub-Needed header should
be sent in the first two header blocks only, to indicate the desired status of the
receiver. If the nodes cannot agree on a satisfactory arrangement, the connection
will be terminated at or prior to the third header block with an appropriate message,
for example:

<pre>
<nowiki>
GNUTELLA/0.6 503 Too many hub connections
GNUTELLA/0.6 503 Too many leaves
GNUTELLA/0.6 503 I have leaves, can't downgrade to leaf mode
GNUTELLA/0.6 503 Leaf mode disabled
</nowiki>
</pre>

- NOTE: because X-Ultrapeer and X-Ultrapeer-Needed has been used on Gnutella2 for longtime, there should be some backword compatibility code to comunicate with older nodes until they disapper.

=== Hub Address Exchange ===

It is desirable for connecting nodes to exchange the node addresses of other hubs on
the network to facilitate rapid connection. The Gnutella2 protocol includes highly
efficient methods to share hub addresses with peers once connected, but for a node
trying to connect and encountering only "full" hubs, learning new hubs to try is
helpful.

The X-Try-Hubs header was developed for this purpose. It contains a comma
separated list of hub node addresses and ports, along with a timestamp recording
the time the hub was last seen. For example:

<pre>
<nowiki>
X-Try-Hubs: 1.2.3.4:6346 2007-01-10T23:59Z, [..more..]
</nowiki>
</pre>

Hub addresses should not be sent unless the transmitter has reasonable knowledge
of the hub's existence and the timestamp is not too old.

=== Compression Negotiation and Encoding ===

The Gnutella2 architecture makes widespread use of "deflate" compression, due to
its high availability and ease of integration. Support of compressed TCP links is not a
requirement in the Gnutella2 standard, however, it is strongly recommended.

Deflate compression of a TCP link is negotiated with the pair standard HTTP headers
"Accept-Encoding" and "Content-Encoding". For example:

Header block one (initiator):

<pre>
<nowiki>
Accept-Encoding: deflate
</nowiki>
</pre>

Header block two (receiver):

<pre>
<nowiki>
Accept-Encoding: deflate
Content-Encoding: deflate
</nowiki>
</pre>

Header block three (initiator):

<pre>
<nowiki>
Content-Encoding: deflate
</nowiki>
</pre>

In this example, the initiator advertises support for receiving a deflated connection.
The receiver then indicates that it too supports receiving a deflated connection, and
that it intends to transmit deflated data. Finally, the initiator upon noting that the
receiver supports deflate, indicates that it too will transmit deflated data.

Note that unlike the content-type / protocol negotiation, deflated encoding can be
applied on either incoming, outgoing, or both channels of a connection.

For performance reasons, nodes should consider whether they can afford to support
additional deflated connections before advertising support for them, or agreeing to
provide a deflated data stream. In the Gnutella2 network topology, all links benefit
from compression, except the leaf to hub channel of the leaf/hub link. Exempting this
channel from compression, saves the leaf and more importantly, the hub, a
considerable CPU and RAM investment.

== Post Handshake Communication ==

After the third and final header block has been received by the initiator, subsequent
communication over the TCP stream occurs in the negotiated protocol, with the
negotiated encoding. This means that while the handshake sequence was backwards
compatible with Gnutella1, after Gnutella2 support has been negotiated, all
subsequent communication occurs in the Gnutella2 common protocol - an entirely
new system not backwards compatible with any other protocol.