Linux Certif

Toute la documentation sur la certification Linux LPI

Net::BitTorrent::LibBT::Tracker.3pm

NAME

Net::BitTorrent::LibBT::Tracker - Access a tracker running under libbttracker

SYNOPSIS

   use Net::BitTorrent::LibBT::Tracker;
 
   my $tracker = Net::BitTorrent::LibBT::Tracker->new("/path/to/tracker");
   print "Tracker has ", $tracker->num_peers, " peers.\n";
 
 

DESCRIPTION

The Net::BitTorrent::LibBT::Tracker module provides an interface to the "libbttracker" Hash and Peer databases and the statistics stored in shared memory.

USAGE

TRACKER

"$tracker = Net::BitTorrent::LibBT::Tracker->new($dir, [$master])"

Connects to, or creates, a LibBTTracker 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.

CONNECTION ACTIONS

"$tracker->cxn_announce($args, $user_agent, $addr, $port)"

Process an ``/announce'' connection. $args are the URL arguments (info_hash=blah&peer_id=blah&etc), $user_agent is the ``User-Agent'' header sent by the client, $addr is the remote address, as an integer, in network byte order (If you're using an IO::Socket::INET object, you can get this with ""$address = unpack('L', $socket->peeraddr);""), and $port is the remote port, in host byte order ("$socket->peerport" returns this).

The return value is an array. The first element is the HTTP status code to return, the second element is the length of the content, and the third element is the content itself.

"$tracker->cxn_details($args, $addr, $port)"

"$tracker->cxn_register($args, $addr, $port)"

"$tracker->cxn_scrape($args, $addr, $port)"

Process ``details'', ``announce'', and ``scrape'' requests, respectively. The arguments have the same meanings as they do in "$tracker->cxn_announce()", and the return value is also the same.

If you wish to get a root HTML info page, specify ``html=1'' in $args for "$tracker->cxn_scrape()".

"Net::BitTorrent::LibBT::Tracker::Flags()"

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.

"$tracker->c"

Returns a "Net::BitTorrent::LibBT::Tracker::Config" object which allows the tracker's configuration data to be retrieved and set. Consult the "libbttracker" documentation for the meanings of each of these configuration values.

"Net::BitTorrent::LibBT::Tracker::Config" Methods

"$c->stylesheet([$new_val])"

Gets/sets the URI for the stylesheet to be used on HTML pages generated by the tracker.

"$c->db_dir()"

Returns the directory on the filesystem where the database is kept.

"$c->flags([$new_val])"

Gets/sets the tracker configuration's flags.

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 ``Net::BitTorrent::LibBT::Tracker::Flags()'' function; some are used internally. You can really screw your tracker up if you are not careful when re-setting flags!

"$c->random_retry([$new_val])"

Gets/sets the number of times ``random'' operations should be allowed to iterate if unsuccessful. Currently, the main ``random'' operation is picking peers off of a peerlist to return to a client; the higher this value, the more times the tracker will retry building peerlists for "/announce" requests if random selection does not return any peers.

"$c->return_peers([$new_val])"

Gets/sets the default number of peers to return on "/announce" requests.

"$c->return_interval([$new_val])"

Gets/sets the base return interval to return to peers on "/anounce" requests.

"$c->return_max([$new_val])"

Gets/sets the maximum number of peers to return on /announce requests.

"$c->return_peer_factor([$new_val])"

Gets/sets the ``return peer factor''. This value is used to increase peers' return intervals as more peers are added to an infohash.

The following formula is used to calculate what interval to return to a peer:

         peer.return_interval = ((tracker.return_peer_factor / infohash.peers) + 1) * tracker.return_interval
 
 

So, with a tracker "return_interval" of 500 seconds, and a "return_peer_factor" of 20,

•

An infohash with 10 peers would tell it's peers to return every 500 seconds,

•

an infohash with 22 peers would tell it's peers to return every 1000 seconds,

•

an infohash with 1000 peers would tell it's peers to return every 500000 seconds,

•

etc.

The default "return_interval" setting is 1000. Setting it below 100 would probably cause problems on very popular torrents.

"$c->hash_watermark([$new_val])"

Gets/sets the hash watermark, which is how many hashes need to be in existance before hashes between ``hash_min_age'' and ``hash_max_age'' are deleted.

"$c->hash_min_age([$new_val])"

Gets/sets the minimum inactivity of an infohash before it is eligible for deletion.

"$c->hash_max_age([$new_val])"

Gets/sets the maximum inactivity of an infohash before it must be deleted.

"$c->parent_server()"

If the LibBTTtracker is embedded inside another server, that server will set this value on startup. (eg; ``Apache/2.0.49'')

"$tracker->s"

Returns a "Net::BitTorrent::LibBT::Tracker::Stats" object which may be used to fetch (and set) statistics on the tracker's internal operation.

"Net::BitTorrent::LibBT::Tracker::Stats" Methods

"$s->num_children()"

This value is incremented/decremented automatically whenever a tracker instance connects/disconnects from a tracker directory and should not be modified externally.

"$s->num_requests([$new_val])"

Gets/sets the total number of requests this tracker has processed.

"$s->num_hashes([$new_val])"

Gets/sets the number of hashes on this tracker. Setting this value is pretty useless, since it is re-set by the tracker frequently to reflect the actual database value.

"$s->num_peers([$new_val])"

Gets/sets the number of peers on this tracker. Setting this value is pretty useless, since it is re-set by the tracker frequently to reflect the actual database value.

"$s->announces([$new_val])"

Gets/sets the number of announce requests this tracker has served.

"$s->scrapes([$new_val])"

Gets/sets the number of scrape requests this tracker has served.

"$s->full_scrapes([$new_val])"

Gets/sets the number of non-specific scrape requests this tracker has served.

"$s->bad_announces([$new_val])"

Gets/sets the number of erronious announce requests this tracker has processed.

"$s->bad_scrapes([$new_val])"

Gets/sets the number of erronious scrape requests this tracker has processed.

"$s->start_t([$new_val])"

Gets/sets the UNIX timestamp when this tracker started up.

"$s->master_pid([$new_val])"

Gets/sets process id of the tracker instance that is responsible for final clean-up on shutdown. Changing this value can be hazardous!

"$s->server_time([$new_val])"

This value is updated whenever the tracker processes an announce, register, or scrape request.

INFOHASHES

Initialization

"$hash = $tracker->Infohash($hash_id, [$create])"

Returns a Net::BitTorrent::LibBT::Tracker::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.

"@hashes = $tracker->Infohashes()"

Returns an array of "Net::BitTorrent::LibBT::Tracker::Infohash" objects, one for each hash in the tracker's database.

Methods

"$hash->save()"

Copy changes to the "Net::BitTorrent::LibBT::Tracker::Infohash" object back into the tracker database.

"$hash->infohash()"

Return the 20-byte infohash value for this torrent. This value may not be modified; create a new Infohash object instead.

"$hash->filename([$new_val])"

Gets/sets the filename to report for this hash on the information page.

"$hash->filesize([$new_val])"

Gets/sets the size of the actual file(s) represented by this infohash, in bytes.

"$hash->max_uploaded()"

Returns the highest "uploaded" value reported by any peers currently active on this infohash.

"$hash->max_downloaded()"

Returns the highest "downloaded" value reported by any peers currently active on this infohash.

"$hash->max_left()"

Returns the highest "left" value reported by any peers currently active on this infohash.

"$hash->min_left()"

Returns the lowest "left" value reported by any peers currently active on this infohash, except for seeds. The only time "$hash-"min_left()> will return zero is if all of the peers on the infohash are seeds.

"$hash->hits([$new_val])"

Gets/sets the number of times this infohash has been part of an announce request.

"$hash->peers()"

Returns the number of peers in this hash. If you want to get a list of every actual peer, use the "$hash->Peers()" method (documented below) instead.

"$hash->seeds()"

Returns the number of seeds in this hash.

"$hash->shields()"

Returns the number of shielded seeds in this hash. Shielded seeds are only returned to other peers if there are absolutely no other seeds available.

"$hash->starts([$new_val])"

Gets/sets the number of "/announce" requests this tracker has processed with the peer's "started" attribute set.

"$hash->stops([$new_val])"

Gets/sets the number of "/announce" requests this tracker has processed with the peer's "stopped" attribute set.

"$hash->completes([$new_val])"

Gets/sets the number of /announce requests this tracker has processed with the peer's "completed" attribute set.

"$hash->first_t()"

Returns the UNIX timestamp for when this hash was first placed in the database.

"$hash->last_t([$new_val])"

Returns the timestamp for when this hash was last processed.

"$hash->register_t([$new_val])"

Returns the timestamp for when this hash was registered. Hashes with a "register_t" value other than 0 will not ever be deleted by the tracker's garbage collection.

"$hash->first_peer_t()"

Returns the timestamp for when this hash first had a peer.

"$hash->last_peer_t()"

Returns the timestamp for when this hash last had a peer.

"$hash->first_seed_t()"

Returns the timestamp for when this hash first had a seed.

"$hash->last_seed_t()"

Returns the timestamp for when this hash last had a seed.

PEERS

Peers are always returned from Infohashes.

Functions

"Net::BitTorrent::LibBT::Tracker::Peer::Flags()"

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.

Initialization

"$peer = $hash->Peer($peer_id)"

Given the 20-byte peer_id, return a "Net::BitTorrent::LibBT::Tracker::Peer" object from the database associated with that peer. If the peer does not exist, it will be created.

"@peers = $hash->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::LibBT::Tracker::Peer" objects after the "Net::BitTorrent::LibBT::Tracker::Infohash" object that created them has been destroyed!!!

Methods

"$peer->save()"

Store the object's information in the database. As with infohashes, care should be taken that a "$peer->save()" call happens as quickly as possible after the peer object is loaded.

"$peer->peerid()"

Returns the 20-byte peer id associated with this peer.

"$peer->infohash()"

Returns the 20-byte infohash associated with this peer.

"$peer->flags([$new_val])"

Get/set this peer's flags as a bitmask. The meanings of each bit are returned by the ``Net::BitTorrent::LibBT::Tracker::Peer::Flags()'' function.

"$peer->ua([$new_val])"

Get/set the User-Agent of the peer.

"$peer->event([$new_val])"

Get/set the last "event" string this peer returned.

"($addr, $port) = $peer->address([$new_addr[, $new_port]])"

Get/set 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.

"($addr, $port) = $peer->real_address([$new_addr[, $new_port]])"

Get/set the peers's detected IP address and port.

"$peer->first_t([$new_val])"

Get/set the timestamp for when this peer first connected to the tracker.

"$peer->last_t([$new_val])"

Get/set the timestamp for when this peer last connected to the tracker.

"$peer->first_serve_t([$new_val])"

Get/set the timestamp for the first time this peer was served to another peer.

"$peer->last_serve_t([$new_val])"

Get/set the timestamp for the last time this peer was served to another peer.

"$peer->complete_t([$new_val])"

Get/set the timestamp for when this peer reported that it was done downloading, if ever.

"$peer->return_interval([$new_val])"

Get/set the return interval last returned to this peer.

"$peer->hits([$new_val])"

Get/set the number of times this peer has connected to the tracker.

"$peer->serves([$new_val])"

Get/set the number of times this peer has been served to other peers.

"$peer->num_want([$new_val])"

Get/set the number of peers this peer asked for on it's last "/announce" request.

"$peer->num_got([$new_val])"

Get/set the number of peers this peer was sent on it's last "/announce" request.

"$peer->announce_byes([$new_val])"

Get/set the total number of bytes that have been sent to this peer in "/announce" responses.

"$peer->uploaded([$new_val])"

Get/set the number of bytes this peer claims to have uploaded.

"$peer->downloaded([$new_val])"

Get/set the number of bytes this peer claims to have downloaded.

"$peer->left([$new_val])"

Get/set the number of bytes this peer claims to have left to download.

NOTES

This is a pole for perl.

While "libbttracker" itself is, "Net::BitTorrent::LibBT::Tracker" is not transactional. This is to prevent perl scripts from affecting the operations of the tracker. If you are saving data to the tracker's database, it is always best to do so as quickly as possible after loading the data, otherwise your save may overwrite a tracker update.

SEE ALSO

Apache2::ModBT, <http://www.crackerjack.net/mod_bt/>, Socket(3), perlfunc, IO::Socket::INET

AUTHOR

Tyler 'Crackerjack' MacDonald, <tyler@yi.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Tyler 'Crackerjack' MacDonald

This library is free software; you can redistribute it and/or modify it under the terms of the Apache License 2.x (<http://www.apache.org/licenses/LICENSE-2.0>).