NAME

Net::BitTorrent::FAQ - Frequently Asked Questions

Net::BitTorrent::FAQ

What is Net::BitTorrent?

Net::BitTorrent is a class-based module written in pure perl that allows the exchange of data with other BitTorrent clients.

What is a... BitTorrent client?

See Wikipedia (http://en.wikipedia.org/wiki/BitTorrent).

Tell me more!

Okay, that's not a question, but... Basically, BitTorrent is a Free Speech tool.

If you're interested in the behind the scenes stuff, start with the base specification of the BitTorrent Protocol (http://bittorrent.org/beps/bep_0003.html) then move on to some of the extensions; See http://bittorrent.org/beps/bep_0000.html.

How do I install this thing?

This distribution uses Module::Build for installation, so use the following procedure:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

If you would like to contribute automated test reports (and I hope you do), first install CPAN::Reporter from the CPAN shell and then install Net::BitTorrent:

 $ cpan
 cpan> install CPAN::Reporter
 cpan> reload cpan
 cpan> o conf init test_report
   [...follow the CPAN::Reporter setup prompts...]
 cpan> o conf commit
 cpan> install Net::BitTorrent

For more on becoming a CPAN tester and why this is useful, please see the CPAN::Reporter documentation, http://cpantesters.perl.org/, and the CPAN Testers Wiki (http://cpantest.grango.org/)

Before I even bother installing, what do I need to have first?

Net::BitTorrent requires version and Digest::SHA. On Win32, we require Win32API::File and Encode when handling .torrents holding files with extended charset filenames.* As of perl 5.10, all of these modules are are CORE; they come bundled with the distribution.

I have listed these modules as prerequisites in Build.PL so, unless you answer 'no' when prompted, the CPAN shell should automagically install them for you.

* We also use the internal utf8::is_utf8() function which didn't appear until perl 5.8.1.

I'm writing a client. How can I choose which files I don't want Net::BitTorrent to download and prioritize the files I would like?

See "priority( [NEWVAL] )" in Net::BitTorrent::Session::File.

Hash checking every time I load the torrent is too much! How 'bout quick resume?

Early versions of N::B had resume built in but it was removed for various reasons. Adding this yourself is trivial, fortunately. For each torrent, store the bitfield, nodes (compact list of peers), piece priorities, and the modified times for each file just to be safe. Oh, and a list of the current 'working' pieces and their progress. Add to that some sort of verification scheme to be sure you're loading information that hasn't been tampered with or corrupted. Then, when you load the torrent, set the skip_hashcheck parameter to a true value and reload the torrent with your stored data.

I used Net::BitTorrent on [some tracker] and was banned. Will you talk to the admin for me?

Thanks to the vast amount of usage data large trackers have access to, administrators will probably notice bugs well before end users or even I, as the sole developer, catch on. If it's a ban that directly targets Net::BitTorrent as a problematic client, I'll contact whoever is in charge and find out why.

Can you recommend other open source BitTorrent clients?

Sure!

Where do you plan to go from here?

After I shake a few of the bugs loose, the following BitTorrent extensions are on my todo list (in no particular order):

Metadata Extension

The purpose of this extension is to allow clients to join a swarm and complete a download without the need of downloading a .torrent file first. This extension instead allows clients to download the metadata from peers. It makes it possible to support magnet links, a link on a web page only containing enough information to join the swarm (the info hash).

See also: http://bittorrent.org/beps/bep_0009.html

DHT Protocol

BitTorrent uses a "distributed sloppy hash table" (DHT) for storing peer contact information for "trackerless" torrents. In effect, each peer becomes a tracker. The protocol is based on Kademila and is implemented over UDP.

See also: http://bittorrent.org/beps/bep_0005.html, http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf

Fast Extension

The Fast Extension packages several extensions to the base BitTorrent Protocol the least of which being the ability to request and receive certain pieces (known as a peer's "Allowed Fast Set") regardless of choke status.

This extension was present in early, pre-CPAN releases of this module and will return soon. This is a high priority.

See also: http://bittorrent.org/beps/bep_0006.html

IPv6 Tracker Extension

This extends the tracker response to better support IPv6 peers as well as defines a way for multihomed machines to announce multiple addresses at the same time. This proposal addresses the use case where peers are either on an IPv4 network running Teredo or peers are on an IPv6 network with an IPv4 tunnel interface.

When will IO::Socket::INET6 or Socket6 be CORE?

See also: http://bittorrent.org/beps/bep_0007.html, https://www.microsoft.com/technet/network/ipv6/teredo.mspx

Tracker Peer Obfuscation

This extends the tracker protocol to support simple obfuscation of the peers it returns, using the infohash as a shared secret between the peer and the tracker. The obfuscation does not provide any security against eavesdroppers that know the infohash of the torrent. The goal is to prevent internet service providers and other network administrators from blocking or disrupting bittorrent traffic connections that span between the receiver of a tracker response and any peer IP-port appearing in that tracker response.

See also: http://bittorrent.org/beps/bep_0008.html

Extension Protocol

The intention of this protocol is to provide a simple and thin transport for extensions to the bittorrent protocol. Supporting this protocol makes it easy to add new extensions without interfering with the standard bittorrent protocol or clients that don't support this extension or the one you want to add.

See also: http://bittorrent.org/beps/bep_0010.html

HTTP Seeding

Very low priority.

See http://bittorrent.org/beps/bep_0017.html

I'd like to help! What can I do?

Right now, the best way to contribute would be through bug reports and patch submissions. All patches should be made against the most recent revision and well tested. For a list of svn clients, some of which make patch creation a little easier, see http://subversion.tigris.org/links.html#clients.

Please submit patches for review to the address listed in the "Who are you? How can I get in touch with you?" section or to the net-bittorrent-discuss mailing list linked to in the "How can I stay up to date?" section.

How can I stay up to date?

Visit the following for support and information related to Net::BitTorrent:

The project's website

For wiki and subversion repository access, please visit the project's home: http://net-bittorrent.googlecode.com/.

Receive svn commit updates

The preferred way is to subscribe to one of the feeds of the announce group. Both ATOM 1.0 and RSS 2.0 feeds are provided; see http://groups.google.com/group/net-bittorrent-announce/feeds for a list.

To have each message delivered to your mailbox, subscribe to the read only announce group by visiting http://groups.google.com/group/net-bittorrent-announce.

Public mailing list

Rather than contacting me directly (which you're welcome to do, it's just nice having a searchable, public archive to have for future reference), general questions and comments should be posted to the Net::BitTorrent mailing list. To subscribe to the list or view the archive, visit http://groups.google.com/group/net-bittorrent-discuss.

Bug and Issue Tracker

Use http://code.google.com/p/net-bittorrent/issues/list for bug tracking. Please include as much information as possible.

Stalk me while I tinker with the code

Follow Net::BitTorrent's development on Twitter: http://twitter.com/Net_BitTorrent.

Who are you? How can I get in touch with you?

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

Please use http://code.google.com/p/net-bittorrent/issues/list for bug reports rather than CPAN RT.