Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Net::BitTorrent::NotesUser Contributed Perl DocumentaNet::BitTorrent::Notes(3)

       Net::BitTorrent::Notes -	Annotated Guide	to the Ins and Outs of

       This is a first draft attempt at	defining a road	map for	future
       "Net::BitTorrent" development and a behavioral reference	for third-
       party client developers.	 A few bits for	users might slip in too.

Net::BitTorrent's Way-too-Obvious Class	Hierarchy
						   .---- N::B::T::T::UDP
			     .-------- N::B::T::Tracker
			    /			  \
			   /   .-- N::B::T::File   `---	N::B::T::T::HTTP
			  /   /
		   .---- Net::BitTorrent::Torrent
		 /   .--- Net::BitTorrent::DHT
		/   /
		 `---- Net::BitTorrent::Peer

       The following utility modules also come with the	distribution and will
       be of great use if you decide to	whip together your own BitTorrent

	   Correctly builds and	parses all known BitTorrent packets.

	   Contains basic functions to parse and create	.torrent metadata
	   files, and compact peer lists from trackers.

       To pick and choose which	functions will be exported into	your namespace
       from these modules, see their POD documentation for more	information.

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

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

       See also: Automated Test	Reports

       "Net::BitTorrent" requires version and Digest::SHA.  On Win32, we try
       to use Win32API::File and Encode	to handle extended charset
       filenames[1].  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()" functions which didn't appear	until
       perl 5.8.1.

How Do I...
       Parts that aren't handled internally are	described here (eventually)
       with sample code	to get you started.

   Get basic info from a .torrent without adding it to a client
       Net::BitTorrent::Torrent	objects	can be created directly	without	a
       parent client.  While functionally limited (obvious things like an
       inability to serve data,	etc.) basic information	is available and some
       'advanced' functions still work (hashchecking, for example).  See
       Net::BitTorrent::Torrent	for more.

   Pause and Resume a .torrent Session
       See Net::BitTorrent::Torrent::pause( ) and
       Net::BitTorrent::Torrent::start(	)

   Stop	and Resume a .torrent Session
       See See Net::BitTorrent::Torrent::stop( ) and
       Net::BitTorrent::Torrent::start(	)

   Quick Resume	a .torrent Session Between Client Sessions
       Note: This section describes resume functionality as of "v0.045".

       "Net::BitTorrent" is capable of restoring the state of single torrents
       between sessions.  To store resume data,	use the	save_resume_data( )

       To resume a single torrent, use a variation of the following to save
       the data...

	my $torrent = $bt->add_torrent(	{ Path=> 'some.torrent', Resume	= '.resume' });

	# later...


       ...and unless "Net::BitTorrent::Torrent"	decides	the resume data	is
       bad, you'll start right were you	left off. I would suggest storing
       resume data on a	regular	basis while the	client runs and	again on exit.

       To view a fully functioning example, see	"/tatoeba/".

       For more	on what	exactly	you're saving and the structure	of the data,
       see Resume API in the <Net::BitTorrent Internals|/"Net::BitTorrent
       Internals"> section.

   Save	and Restore Client-wide	State and DHT Data
       Unless you've hard coded	everything, being able to restore client-wide
       state is	a necessary feature.  Besides, DHT can be very slow to boot
       without a good set of initial nodes and the spec	states that the	local
       nodeID should not change	very often, so resume is a useful thing.

       I would use a hash with the following keys:

	   This	would be a SHA-1 hash of the bencoded data in the ".t",	"dht",
	   "nodes", and	"torrents" keys. On restore, I would use this to
	   validate the	data in	case it	was tampered with.


	   To avoid problems (API changes, etc.), I would use an API version
	   number and ignore resume data created with a	newer/incompatible
	   version.  This value	would not be included in the SHA-1 digest used
	   to prevent tampering.

	   A hash with the following keys:

	       The local node ID used in the DHT swarm.	 To obtain this, see
	       node_id(	).

	       List of nodes in	the DHT	routing	table.

	       To make life easy, each node would be a hash with the following

		   IP or hostname of the remote	node.

		   UDP port number the remote port has been contacted on.

	       A list of nodes with this format	is obtained from nodes ( ).
	       To reload these later, use the add_node ( ) method.

	   These would be any client-wide settings I allow users to change.

	   This	would be a list	of filenames, their current status, and	some
	   sort	of verification	that the .torrent file hasn't been replaced;
	   the infohash	would do.

       I would save a bencoded version of this data in a file for later.  For
       now, putting all	of this	into practice is an exercise for the reader.

       Note: Reloading the data	may require using otherwise private methods
       (specifically the private "Net::BitTorrent::DHT->_set_node_id( )"
       method).	Changes	to private methods are not listed in the changelog
       found in	this distribution but they are noted in	the public git
       repository's log.

   Set File Download Priorities
       See Net::BitTorrent::Torrent::File.

   Implement My	Own Event Loop

Net::BitTorrent	Internals
       This section describes all the behind the scenes	stuff that makes
       "Net::BitTorrent" work.	Or not work.  It depends.

   Peer	ID Specification
       Please see Net::BitTorrent::Version.

   IPv6-Related	Information
       Socket6 does not	seem to	work with Win32	so... no plans for IPv6	right

   Implemented Extensions
       The BitTorrent Community	Forum coordinates the development of the
       BitTorrent protocol suite, its reference	implementation,	and BitTorrent
       Enhancement Proposals (BEPs).  For more information, see	BEP 0: Index
       of BitTorrent Enhancement Proposals

       This is the list	of extensions used by this release of Net::BitTorrent
       sorted by their progress	toward standardization.

       o   BEP 5: DHT Protocol -

       o   BEP 6: Fast Extension -

	   Note: the Fast Extension is only partially implemented in

       o   BEP 10: Extension Protocol -

       o   BEP 12: Multitracker	Metadata Extension -

       o   BEP 15: UDP Tracker Protocol	-

       o   BEP 27: Private Torrents -

       o   BEP 32: Tracker Returns Compact Peer	Lists -

   Resume API
       "Net::BitTorrent::Torrent"'s resume data	is bencoded and	stored in a
       file.  To restore this data, use	the "Resume" parameter when calling
       Net::BitTorrent::Torrent->new( )	or Net::BitTorrent->add_torrent( ).

       Note: The structure and data held in the	resume data is subject to
       change in future	versions.

       Data Structure

       Parsed resume data is a simple hash containing the following keys:

	   A string describing what sort of file this is.  For now, it's value
	   is "Net::BitTorrent resume".

	   Timestamp when data was gathered.

	   API version used to gather data.  To	avoid problems (API changes,
	   etc.), Net::BitTorrent::Torrent will	not load resume	data created
	   with	a higher version.

	   A bitvector representing the	pieces we already have.

	   A list of hashes (one for each file in the .torrent)	with the
	   following keys:

	       The modified times for the files	(or 0 if the file does not

	       The file's download priority.

	   Compact list	of peers we've found either through DHT	or from	a

	   List	of hashes representing pieces we are currently downloading
	   with	the following keys: (Subject to	change)

	       Number of blocks	contained in the piece.

	       Size of blocks in piece.

	       Size of final block in piece.

	       Bitfield	representing which blocks have been received and
	       written to disk.

	       Boolean value dependent on endgame state	when we	began working
	       on this piece.

	       Zero-based index	of the piece.

	       Total size of the piece in bytes.

	       Priority	based (partially) on the piece's containing file.

	       Boolean value dependent on how long ago we received a block
	       contained within	this piece.

   Development Policy
       o   All APIs are	subject	to change.

	   Changes to documented or well established parts will	be clearly
	   listed and archived in the CHANGES file.

       o   All undocumented functionality is subject to	change without notice.

	   Net::BitTorrent is just asploding with incomplete bits of stuff so
	   I reserve the right to change or eliminate code at any time without
	   warning unless functionality	is defined in POD documentation.  If
	   you sift through the	source and find	something nifty	that isn't
	   described in	full in	POD, don't expect your client to work with
	   future releases.

   Compatibility Notes
       This section lists recent major changes in API or behavior between
       stable releases.	 For older news	see the	Changes	file included with
       this distribution.  For detail see the commit logs.

	   Protocol Encryption (MSE) is	now supported and enabled by default.
	   It is still rather unstable,	so outgoing connections	use header-
	   only	encryption but incoming	connections allow for full RC4
	   encrypted sessions.

	   Entire distribution was rewritten. Both the internals and the API
	   have	broken compatibility.

Giving back
       If you're interested in assisting with Net::BitTorent's development but
       don't know where	to begin, here are a few ideas.

   Joining the Project
       "Net::BitTorrent" is too	large for just one person to hack on.  If
       you're Perl adept and would like	to help, you can start by forking the
       project on github:  When
       ready, send me a	pull request, I'll look	over your changes and get back
       to you.	Minor patches get your name in the changelog.  Major patches
       get your	name in	the Acknowledgments section and	an invitation to be a
       trusted collaborator.  Oooo.  Ahhh.


       If you're interested in helping clear things out	of the TODO list or if
       you have	a suggestion and are willing to	see it through to completion,
       contact me or, better yet, go ahead and fork the	project	on github:

       In general, N::B	could use a second or third pair of eyes.  So, if
       you're interested in BitTorrent,	p2p, or	just Perl in general, let me

   Bug Reporting
       Found bugs should be reported through "Net::BitTorrent"'s Issue
       Tracker.	 Before	creating a new report through "Net::BitTorrent"'s
       Issue Tracker, please review the	following list:

       1.  Make	sure you are using the most recent stable release.

       2.  Make	sure the bug is	reproducible.

       3.  Please write	in clear English.

       4.  Provide "baby steps"	to describe exactly how	to replicate the bug.
	   Sample code is welcome.  The	issue tracker also allows attachments
	   so, if relevant, include the	.torrent file.

       5.  Search the list of open and resolved	issues to make sure the	flaw
	   hasn't already been reported.  If it	has, star the issue to stay up
	   to date.

       6.  One bug is one bug report.  Please do not include multiple,
	   separate issues in one report unless	they are explicitly related to
	   each	other.

       7.  Star	the issue so you'll be notified	of any changes.

       8.  Look	over your report before	submission to be sure you've included
	   as much detail as possible.	Seriously.  Get	up, have a drink of
	   water, come back, read over it again	to make	sure you've included
	   everything you intended, and	then submit it.

   Automated Test Reports
       Becoming	a CPAN Tester is an easy, automatic way	to contribute to the
       quality of your favorite	module and CPAN	in general.  If	you would like
       to contribute automated test reports for	"Net::BitTorrent", install
       "CPAN::Reporter"	from the CPAN shell first:

	$ 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, see the
       CPAN::Reporter documentation and

See Also
   Support and Information Links for "Net::BitTorrent"
       Website and Blog
	   The official	website	is
	   and related blog entries are	posted to

	   If you're looking for a feed	with only on-topic articles, subscribe

       Live support
	   The official	means of support for "Net::BitTorrent" is through
	   "#net-bittorrent" on	the p2p	IRC network:

       Receive Commit and Issue	Tracker	Updates
	   These are posted to the public mailing list for which both ATOM 1.0
	   and RSS 2.0 feeds are available; see

	   To subscribe	to the list or view the	archive, visit  Both	ATOM 1.0 and
	   RSS 2.0 feeds are provided; see for a list.

       Issue Tracker
	   Use for bug tracking.
	   Please include as much information as possible and review the list

	   I announce stable builds and	occasionally complain on Twitter:

   Other Recommend Open	Source BitTorrent Clients
       o   libtorrent (<>)	is
	   covered by the The BSD License.

       o   Bitflu (<>) is a	full client written in
	   *nix	oriented Perl.	It is available	under the Perl/Artistic

       o   btpeer (<>) is "a collection of
	   classes implementing	the core client	functionality of the
	   BitTorrent protocol"	and has	been released under the	GPL.

       o   Arctic (<>) is a minimal client
	   based on libtorrent,	written	in C++ and released under the MIT

   Related Information
       RFC 3986	(URI: Generic Syntax)
	   Section 2.3.	"Unreserved Characters"

       PAUSE FAQ sub-section entitled "Developer Releases"

       Sanko Robinson <> -


License	and Legal
       Copyright (C) 2008-2009 by Sanko	Robinson <>

       This program is free software; you can redistribute it and/or modify it
       under the terms of The Artistic License 2.0.  See the LICENSE file
       included	with this distribution or  For	clarification,

       When separated from the distribution, all POD documentation is covered
       by the Creative Commons Attribution-Share Alike 3.0 License.  See  For
       clarification, see

       Neither this module nor the Author is affiliated	with BitTorrent, Inc.

perl v5.32.1			  2021-03-02	     Net::BitTorrent::Notes(3)

NAME | Description | Net::BitTorrent's Way-too-Obvious Class Hierarchy | Installation | How Do I... | Net::BitTorrent Internals | Giving back | See Also | Author | License and Legal

Want to link to this manual page? Use this URL:

home | help