=pod

=head1 NAME

Net::BitTorrent::FAQ - Frequently Asked Questions

=head1 Net::BitTorrent::FAQ

=head2 What is C<Net::BitTorrent>?

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

=head2 What is a... BitTorrent client?

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

=head2 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
(L<http://bittorrent.org/beps/bep_0003.html>) then move on to
some of the extensions; See
L<http://bittorrent.org/beps/bep_0000.html>.

=head2 How do I install this thing?

This distribution uses C<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 C<CPAN::Reporter> from the CPAN shell and then
install C<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 L<CPAN::Reporter|CPAN::Reporter/"DESCRIPTION"> documentation,
L<http://cpantesters.perl.org/>, and the CPAN Testers Wiki
(L<http://cpantest.grango.org/>)

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

C<Net::BitTorrent> requires L<version|version> and
L<Digest::SHA|Digest::SHA>.  On Win32, we require
L<Win32API::File|Win32API::File> and L<Encode|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 C<utf8::is_utf8()> function which didn't
appear until perl 5.8.1.

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

See L<Net::BitTorrent::Session::File/"priority( [NEWVAL] )">.

=head2 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 C<skip_hashcheck>
parameter to a C<true> value and reload the torrent with your stored
data.

=head2 I used C<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 L<Net::BitTorrent|Net::BitTorrent> as a problematic client,
I'll contact whoever is in charge and find out why.

=head2 Can you recommend other open source BitTorrent clients?

Sure!

=over 4

=item *

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

=item *

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

=item *

btpeer (L<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.

=item *

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

=back

=head2 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):

=over 4

=item B<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: L<http://bittorrent.org/beps/bep_0009.html>

=item B<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: L<http://bittorrent.org/beps/bep_0005.html>,
L<http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf>

=item B<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: L<http://bittorrent.org/beps/bep_0006.html>

=item B<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 L<IO::Socket::INET6|IO::Socket::INET6> or
L<Socket6|Socket6> be CORE?

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

=item B<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: L<http://bittorrent.org/beps/bep_0008.html>

=item B<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: L<http://bittorrent.org/beps/bep_0010.html>

=item B<HTTP Seeding>

Very low priority.

See L<http://bittorrent.org/beps/bep_0017.html>

=back

=head2 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
L<http://subversion.tigris.org/links.html#clients>.

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

=head2 How can I stay up to date?

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

=over 4

=item The project's website

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

=item 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
L<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
L<http://groups.google.com/group/net-bittorrent-announce>.

=item 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
C<Net::BitTorrent> mailing list.  To subscribe to the list or view the
archive, visit
L<http://groups.google.com/group/net-bittorrent-discuss>.

=item Bug and Issue Tracker

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

=item Stalk me while I tinker with the code

Follow C<Net::BitTorrent>'s development on Twitter:
L<http://twitter.com/Net_BitTorrent>.

=back

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

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

CPAN ID: SANKO

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

=for svn $Id: FAQ.pod 12 2008-04-10 01:53:19Z sanko@cpan.org $

=cut
