=pod

=head1 NAME

Net::BitTorrent::Protocol::BEP07 - IPv6 Tracker Extension

=begin header

BEP: 7
Title: IPv6 Tracker Extension
Version: $Revision: 4446139d80647591d17c5d0e39fd6ded3ac12973 $
Last-Modified: $Date: 2010-05-30 03:48:56Z (Sun, 30 May 2010) $
Author:  Greg Hazel <greg@bittorrent.com>, Arvid Norberg <arvid@bittorrent.com>
Status:  Draft
Type:    Standards Track
Created: 31-Jan-2008
Post-History:

=end header

=head1 Description

This extension extends the tracker response to better support IPv6 peers as
well as defines a way for multi homed machines to announce multiple addresses
at the same time. This proposal addresses the use case where peers are either
on an IPv4 network running
L<Teredo|https://www.microsoft.com/technet/network/ipv6/teredo.mspx> or peers
are on an IPv6 network with an IPv4 tunnel interface.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in IETF
L<RFC 2119|http://tools.ietf.org/html/rfc2119>.

=head1 Announce Parameter

The client MAY add an ``&ipv6=`` parameter to the HTTP GET request it sends to
the tracker. The value is either an IPv6 endpoint (address and port) or just
an IPv6 address. In the case where only an address is supplied, the IPv6 port
is assumed to be the same as specified by the ``&port=`` parameter.

The tracker SHOULD perform a NAT check on the IPv6 endpoint.

In case the client contacts the tracker on an IPv6 interface, it may add an
C<&ipv4=> parameter with its IPv4 address or endpoint. The value MUST be
either an IPv4 endpoint (address and port) or just an IPv4 address. If only an
address is supplied, the port is assumed to be the same as the C<&port=>
parameter.

The endpoints are encoded as strings as defined by
L<RFC 2732|http://tools.ietf.org/html/rfc2732>.

If both an C<&ipv4=> and an C<&ipv6=> parameter are specified, the tracker
MAY ignore the address family that is the same as the source address of the
request. i.e. If the client connects to the tracker with an IPv4 source
address, the tracker MAY ignore any C<&ipv4=> address and if the client
connects to the tracker with an IPv6 source address, the tracker MAY ignore
any C<&ipv6=> parameter.

=head1 Announce Response

In case the tracker does not support the C<compact> response as described in
L<BEP-23|Net::BitTorrent::Protocol::BEP23>, no change is necessary. Since the
original C<peers> response returns peer endpoints in their expanded string
form, IPv6 addresses can be passed back this way.

In case a compact response is requested, the tracker MAY add another key to
the response; C<peers6>. This key has the same layout as C<peers> in compact
mode, but instead of using 6 bytes per endpoint, 18 bytes are used. peers6
contains address-port pairs where the addresses are all IPv6.

=head1 Examples

Example announce string with C<2001::53aa:64c:0:7f83:bc43:dec9> as IPv6
address:

	GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&info_hash=aaaaaaaaaaaaaaaaaaaa
	&port=6881&left=0&downloaded=100&uploaded=0&compact=1
	&ipv6=2001%3A%3A53Aa%3A64c%3A0%3A7f83%3Abc43%3Adec9

Example announce string with C<[2001::53aa:64c:0:7f83:bc43:dec9]:6882> as IPv6 endpoint:

	GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&info_hash=aaaaaaaaaaaaaaaaaaaa
	&port=6881&left=0&downloaded=100&uploaded=0&compact=1
	&ipv6=%5B2001%3A%3A53Aa%3A64c%3A0%3A7f83%3Abc43%3Adec9%5D%3A6882

Example announce string with C<2001::53aa:64c:0:7f83:bc43:dec9> as IPv6
address and C<261.52.89.12> as IPv4 address:

	GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&info_hash=aaaaaaaaaaaaaaaaaaaa
	&port=6881&left=0&downloaded=100&uploaded=0&compact=1
	&ipv6=2001%3A%3A53Aa%3A64c%3A0%3A7f83%3Abc43%3Adec9&ipv4=261.52.89.12

Example response:

	d8:intervali1800e5:peers6:iiiipp6:peers618:iiiiiiiiiiiiiiiippe

=head1 Rationale

The naming of C<peers6> is chosen not to collide with the current C<peers>
response and to be backwards compatible. It is also a simple addition to the
current response, using the same encoding.

=head1 Copyright

This document has been placed in the public domain.

=cut
