gistfile1.txt

JohnLocke, an open source bit torrent tracker daemon.

 * Written in c
 * Uses libevent 2.0+
 * Supports different modes to help tracker operators shape the swarm

# Global Configuration Options

 * '--daemon' Run the tracker as a daemon. Note that by default it will write
   the pid to `/var/run/johnlocke.pid`.
 * '-v' Output runtime information to stdout. This can be a lot of information.
 * '--mode=name' The behavior or mode to run.
 * '--dir=path' The directory to load torrents from to track.
 * '--scan=bool' Periodically load newly found torrents from the aforementioned
   scan directory. Enabled by default if a directory was set and found.
 * '--locked=bool' Prevent new torrents from being tracked organically by
   peers. Enabled by default.
 * '--maxpeers=number' Returned peer lists will never be larger than this
   number. The default value is 50.

# Behaviors

This application is built around three distinct modes of operation as
described below.

## Small: Small / Private Distribution Groups

The first involves providing quick service for small, likely private, peer
groups.

Behavior Qualities:

 * The number of unique peers for a given torrent is small, under 100.
 * The lifespan of the torrents tracked is usually short, usually less than a
   week. Once all of the peers have what they need, they may stick around until
   the last peer is done and then all of them disconnect.
 * The peer operators probably know about the peers ahead of time and the
   the number of unexpected peers is probably small.
 * There isn't any need to keep any logs or statistics because the peer count
   is small or privacy may be important to the peers or tracker.
 * Peers are considered generous and usually have larger up:down ratios.

Use case #1: A family wants to distribute home videos and images with each
other. The torrent is created and the creator of the videos/images emails the
torrent to other family members who, in a relatively short period of time,
download the content and then the tracker is taken down.

Use case #2: A community college teacher wants to make course material available
at the begining of a school year. The torrent is created and seeded by the
teacher and the students download the course material the first several weeks
of class.

### Peer Lists

The following rules are applied to this mode of operation:

 * If a peer connects and there are less than 20 peers, the entire peer list
   is returned.
 * If a peer connects and there are more than 20 peers, a 'last_start' peer is
   tracked and half or 50 peers are returned starting at the 'last_start' peer
   and the 'last_start' peer is moved to the next known peer for the next peer
   list request.

This mode does not attempt to incorporate any intelligence in crafting peer
lists because of the estimated size of the swarm.

## Large: Large content distributions

The second behavior is geared toward providing tracker services for torrents
that involve larger content that has a signifantly longer lifespan than the
first behavior.

Behavior Qualities:

 * The number of unique peers for given torrent is very large, considering the
   lifespan of the torrent.
 * The lifespan of the torrents tracked is usually very long, greater than
   several months.
 * There are usually several fixed seeders over the lifespan of the torrent and
   occasionally peers that complete their download stick around and acts as
   seeders for a period of time, but the lifespan of new peers is short when
   compared to the lifespan of the torrent.
 * Peers don't know each other outside of the swarm and the swarm is considered
   a swarm of strangers.
 * Logs may or may not be kept given the lifespan of the torrent and the sheer
   number of unique peers and behaviors.
 * Peers are considered moderately greedy, some sharing very little while
   others share larger amounts.

Use case #1: A linux distribution is released and many unique peers across the
world join the swarm to download disk images.

## Surge: Burst downloads for one-time time-sensitive content distributions

The third behavior is intended to support time-sensitive content distribution
scenarios where there may be very large bursts of peers that only share content
while downloading and immediately disconnect.

Behavior Qualities:

 * The number of unique peers for a given torrent is very large over a short
   period of time.
 * The lifespan of the torrent tracked may be medium to long.
 * There are usually several fixed seeders supporting the entirety of the swarm.
 * Peers don't know each other outside of the swarm.
 * Peers are considered very greedy, some sharing may occur during the download
   phase but once downloading is complete the vast majority of peers disconnect
   immediately.

Use case #1: A company uses bittorrent to distribute game patches. On patch
days the torrent tracker is active with millions of peers. Once a peer is
done, they disconnect and there are never any perm seeders grown from peers.
aka you have a fixed number of seeders

# License

Copyright (c) 2010 XXXXXXXX

Open Source under the MIT license.