Net::BitTorrent::LibBTT - Manipulate a tracker running under libbtt from perl
use Net::BitTorrent::LibBTT;
my $tracker = Net::BitTorrent::LibBTT->new("/path/to/tracker");
print "Tracker has ", $tracker->num_peers, " peers.\n";
The Net::BitTorrent::LibBTT module provides an interface to the LibBTT Hash and Peer databases and the statistics stored in shared memory.
Connects to, or creates, a LibBTT tracker database. If "$master" is specified, a new database and shared memory region are created.
If you are writing a script to be used in the mod_perl environment, use the Apache::ModBT module to initialize your tracker object instead; that module will connect you to an existing tracker object instead of creating a new one, which is far more efficient.
Returns an array of key/value pairs for every flag that this tracker supports. The keys returned are the flags' binary values, and the values returned are the flags' configuration names.
Returns a Net::BitTorrent::LibBTT::Tracker::Config object which allows the tracker's configuration data to be retrieved and set. Consult the libbtt documentation for the meanings of each of these configuration values.
Methods:
stylesheet([$new_val])db_dir()flags([$new_val])
NOTE: It is NOT safe to clear the flags and re-set them the way you want.
You must always first obtain the current flags, and then only set/clear
the ones you intend to change. Not all bits in $new_val will have been
defined by the Flags() function; some are used internally. You can
really screw your tracker up if you are not careful when re-setting flags!
random_retry([$new_val])return_peers([$new_val])return_interval([$new_val])return_max([$new_val])return_peer_factor([$new_val])hash_watermark([$new_val])hash_min_age([$new_val])hash_max_age([$new_val])parent_server()If the LibBTT tracker is embedded inside another server, that server will set this value on startup. (eg; "Apache/2.0.49")
Returns a Net::BitTorrent::LibBTT::Stats object which may be used to fetch (and set) statistics on the tracker's internal operation.
num_children()This value is incremented/decremented automatically whenever a tracker instance connects/disconnects from a tracker directory and should not be modified externally.
num_requests([$new_val])num_hashes([$new_val])num_peers([$new_val])announces([$new_val])scrapes([$new_val])full_scrapes([$new_val])bad_announces([$new_val])bad_scrapes([$new_val])start_t([$new_val])master_pid([$new_val])server_time([$new_val])This value is updated whenever the tracker processes an announce, register, or scrape request.
Returns a Net::BitTorrent::LibBTT::Infohash object for the given 20-byte $hash_id. If $create is set to "1", the hash will be created if it does not already exist.
Infohashes()Returns an array of Net::BitTorrent::LibBTT::Infohash objects, one for each hash in the tracker's database.
save()Copy changes to the Net::BitTorrent::LibBTT::Infohash object back into the tracker database. With busy torrents, it is possible that you will overwrite the tracker's updates to the infohash with this method. Most of the updates are only statistical and vital information is re-populated with each announce request, but if you want to keep your statistics accurate, be careful not to take too long between loading a hash and saving. If you are doing a long operation on a hash, load it first, do your calculations, load it again, update the second object quickly, then save.
TODO: Hash initializer method that maintains a database cursor on the hash so that updates can be made more safely. This brings up issues/complications with the berkeley transactional db but should be ready in the next version.
infohash()Return the 20-byte infohash value for this torrent. This value may not be modified; create a new Infohash object instead.
filename([$new_val])filesize([$new_val])max_uploaded()max_downloaded()max_left()min_left()hits([$new_val])peers()Returns the number of peers in this hash. If you want to get the peers themselves, use the $hash->Peers() method (documented below) instead.
seeds()shields()starts([$new_val])stops([$new_val])completes([$new_val])first_t()last_t([$new_val])register_t([$new_val])UNIX Timestamp this hash was "Registered". Hashes with a "register_t" value other than 0 will not be deleted by the tracker's garbage collection.
first_peer_t()last_peer_t()first_seed_t()last_seed_t()
Peers are always returned from Infohashes.
Returns a list of key/value pairs, the keys being valid binary flag values for a peer, the values being the configuration names of those flags.
Peer($peer_id)Given the 20-byte peer_id, return a Net::BitTorrent::LibBTT::Peer object from the database associated with that peer. If the peer does not exist, it will be created.
Peers()Return all peers associated with a given hash. NOTE: When dealing with peers, it is ABSOLUTELY VITAL at this point that you do not attempt to access Net::BitTorrent::LibBTT::Peer objects after the Infohash object that spawned them has been destroyed!!!
save()Store the object's information in the database. As with infohashes, care should be taken that a save() request happens as quickly as possible after the peer object is loaded.
peerid()Returns the 20-byte peer id associated with this peer.
infohash()Returns the 20-byte infohash associated with this peer.
flags([$new_val])ua([$new_val])Set/return the User-Agent of the peer.
event([$new_val])Set/return the peers's reported IP address and port. IP addresses are returned/specified as a 4-byte string in network byte order, suitable for passing to inet_ntoa. Ports are returned as an integer value in host byte order.
first_t([$new_val])last_t([$new_val])first_serve_t([$new_val])last_serve_t([$new_val])complete_t([$new_val])return_interval([$new_val])hits([$new_val])serves([$new_val])num_want([$new_val])num_got([$new_val])announce_byes([$new_val])uploaded([$new_val])downloaded([$new_val])left([$new_val])
This is pre-alpha software. Expect (and please, report!) bugs.
libbtt uses the Apache Portability Runtime (APR) library for it's memory management. Perl has it's own memory management system, and the code to keep them in sync has not been completely foolproofed. This does not cause any major problem so long as you pay attention to the scope of your variables; first, never use an Infohash object after the Tracker object that created it is gone, and second, never use a Peer object after the Infohash object that created it is gone.
When a multi-process tracker is running, the less Infohash or Peer objects you keep defined at a time the better. If you are modifying them, the quicker you save them after loading them, the better.
Apache::ModBT
Tyler 'Crackerjack' MacDonald, <tyler@yi.org>
Copyright (C) 2004 by Tyler 'Crackerjack' MacDonald
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.