NAME

Net::BitTorrent::FAQ - Frequently Asked Questions

Net::BitTorrent::FAQ

These are the Frequently Asked Questions I anticipate will arise with the release of the Net::BitTorrent module.

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...

Begin with the base specification of the BitTorrent Protocol (http://wiki.theory.org/BitTorrentSpecification) then move on to some of the extensions:

• Fast Extension aka 'Fast Peers' (http://www.bittorrent.org/fast_extensions.html)

• DHT/PEX (http://www.bittorrent.org/Draft_DHT_protocol.html)

• Wire protocol encryption (http://www.azureuswiki.com/index.php/Message_Stream_Encryption)

• Extension protocol (http://www.rasterbar.com/products/libtorrent/extension_protocol.html)

• Extension Negotiation Protocol (http://www.azureuswiki.com/index.php/Extension_negotiation_protocol)

• BitComet Extension Protocol (Currently un(der)documented)

How do I install this thing?

The current distribution uses the CORE ExtUtils::MakeMaker module, so the standard procedure will suffice:

perl Makefile.PL
make
make test
make 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 the Makefile.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.

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

See "priority" in Net::BitTorrent::Session::File.

Net::BitTorrent is slower than [some other client]. Did you know that?

Yes.

Right now, we become interested in any peer who happens to have a piece we need; I haven't written anything that rates the quality of peers we've connected to. Perhaps, in a future version, a peer will be judged on how fast they transfer blocks to us, how often they are involved with 'bad' pieces, how many times they have choked us while we were waiting for a block, etc. Making attempts to stay interested and unchoked by these high quality peers will greatly increase download speed. Add to this PEX/DHT and other extensions we have yet to support-- Yeah...

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), and piece priorities, the modified times for each file just to be safe. Oh, and the current 'working' pieces and their progress. And 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. See? Easy.

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 (private and public) 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!

• libtorrent (http://www.rasterbar.com/products/libtorrent/) is covered by the The BSD License.

• Bitflu (http://bitflu.workaround.ch/) is a full client written in (*nix oriented) Perl and available under the Perl/Artistic License.

• btpeer (http://www.alhem.net/project/btpeer/) is "a collection of classes implementing the core client functionality of the BitTorrent protocol" and has been released under the GPL.

• Arctic (http://dev.int64.org/arctic.html) is a minimal client based on libtorrent, written in C++ and released under the MIT License.

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

Short of becoming an official co-owner of the project, the best way to contribute would be through submission of patches. 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 next section.

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

Sanko Robinson
CPAN ID: SANKO
<sanko@cpan.org>
ProperNoun on Freenode

I'm usually idle on Freenode but you can /msg me anytime or have MemoServ deliver it for you.

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

cpanm Net::BitTorrent

perl -MCPAN -e shell
install Net::BitTorrent