Options

-d

Print debugging information to stderr. Use multiple times for more verbosity.

-n

Do not sanitize file names. By default the file names specified in the torrent file are sanitized: special characters and whitespace replaced by underscores. With this option the original file names are created or opened.

-s

Start up `stopped'. Data exchange is started immediately at start up without this option.

-m ratio

Set the maximum ratio of uploaded/downloaded bytes. When this ratio is reached and all pieces have been downloaded, all data transfer is stopped.

-r maxuprate

Set the maximum used bandwidth used for uploading, per second. The value is a size, see below. Torrent/peer does not upload more per second. The default value `0.0' disables the limit. Note that the value is for TCP-application data, i.e. the bittorrent protocol, not counting TCP/IP overhead.

-R maxdownrate

Like -r, but for the download bandwidth.

-t maxuptotal

Set the maximum total bytes uploaded. When this is reached, data exchange is stopped, regardless of whether downloading has finished. The value is a size. The default value `-1' allows unlimited data transferred.

-T maxdowntotal

Like -t, but for data downloaded.

Sizes

Sizes in torrent/peer are normally returned from styx files in bytes. Where sizes are written, e.g. to the ctl file, the suffix `k' for kilobyte, `m' for megabyte, `g' for gigabyte and so on are recognized.

Features

Torrent/peer attempts to stay connected to between 80 and 85 peers, receiving data from any peer that is willing to give data. The trackers from the torrent file are periodically queried for more peers. The first three requests are done in quick succession, to get a big pool of peers quickly. Torrent/peer itself sends data to at most three peers at a time, those that give back most bandwidth. An additional randomly selected peer receives data too, to give it an incentive to start sending data back. A pool of peer addresses is maintained. When in need of connections, addresses from that pool are dialed. At most fifteen connection attempts are in progress at one time and some time is kept between the start of two connection attempts. As part of the protocol, peers exchange information about which pieces they have completed. They also indicate whether they are interested and willing to send data. This is essentially protocol overhead, and counted as `meta' data by torrent/peer. Non-urgent messages are delayed for a short time. For example, completion of a piece has to be mentioned to all connected peers. Instead of sending up to 80 messages immediately, the messages are scheduled with a small delay between each message. This also increases the chance multiple such messages can be sent in a single TCP/IP packet, reducing overhead. Downloaded data is kept in memory until chunks of up to 128KB before they are written to disk. Hopefully they will end up on disk in consecutive blocks, reducing seek times and file system fragmentation (depending on the file system in use) and making later reading faster. Data to be uploaded is read from disk. Up to four reads can be scheduled, ensuring data for sending is available. Peers typically requests blocks of a piece sequentially, allowing the data to be read from disk sequentially. Data is read from disk in chunks of up to 128k when the upload rate is high enough for them to be consumed quickly. Blocks of a piece are normally requested and received in order. The SHA-1 hash of the piece is kept up to date as long as blocks do come in in order. Otherwise, when the last block is on disk, a separate thread reads the remaining data of the piece from disk and completes the SHA-1 calculation. Torrent/peer stores progress in a separate file, a bit array with the pieces that have been downloaded and verified. It is updated after a piece has been completed. This file is read at start up, eliminating the need to verify hashes of all pieces. The name of this file is `.state' appended to the name of the torrent file. Potentially abusive peers are refused connection for some time. E.g. when a peer sent misleading information about the pieces it had, or when a peer sent invalid data.

Styx files

ctl

Reads return values of configuration parameters, one per line. Each line has two tokens, the first is the name of the parameter, the second the value. The values can be changed by writing a line with parameter and value to the ctl file. The following parameters can be changed: maxratio, maxuprate, maxdownrate, maxuptotal, maxdowntotal, debugpeer, debuglib and debugpeerlib.

info

Can only be read, returning lines with two quoted string tokens each: torrentpath, path of the torrent file. infohash, the unique identifier of the data exchanged in the torrent. announce, the address of the tracker. announces, the addresses of the trackers in case the torrent file uses the ``multi tracker extension''. piecelen, the length of a piece. piececount, the number of pieces. length, the total length of the data described in the torrent file.

state

Can only be read, returning information about the current state of data exchange, one key/value pair on a line. Current transfer rates, total bytes transferred and remaining, an estimated time of arrival, number of peers and `seeds' (peers that have all data), number of peers torrent/peer initiated connection to, number of peers that have data we still want, are sending data to us, peers we know of, etc.

files

For reading only. Returns the files described in the torrent file, one per line. Each line has five quoted strings: a sanitized file name, the original file name as specified in the torrent file, the length of the file, and the first and last piece that has bytes for the file.

peers

For reading only, returning information about peers, one line with quoted strings per peer. The format of the lines is:
id address peeridhex in/outlocalstate remotestate lastunchoke npeerpieces createtime up total rate down total rate metaup total rate metadown total rate reqs localreqs remotereqs
Id is the unique connection id, peeridhex a client-chosen software identifier. The local and remote state is an empty string with optionally the characters `c' (choking) and `i' (interested) in them. Lastunchoke is the unix epoch time of the last time the peer was unchoked. Npeerpieces the number of pieces the peer has. Createtime the time the connection was made. Local and remote reqs is the number of requests currently queued.

peerstracker

For reading only, returns lines with known peers from the address pool. The format of a lines is: ip!port peeridhex nextusetime backofftime state Peeridhex may be an empty string Nextusetime is the unix epoch time the peer may be dialed again. Incoming connections from the address are accepted even before nextusetime. Backofftime is the last back off time for the peer. Each consecutive failed connection attempt exponentially increases the back off time.

peersbad

For reading only, returns lines with peers that have shown bad behaviour. The format of the lines is: ip!port nextusetime peeridhex reason Reason is the error string that caused this address to be banned. Nextusetime is the unix epoch time a connection from this address is accepted or initiated.

Two more styx files are exported: progress and peerevents. These read-only files block until an event occurs. They return one or more lines per read, each line a list of quoted strings. The first token indicates the type of event.

progress

The following lines can be returned:

endofstate

When progress is opened, lines indicating the current state is queued to be returned. The last line queued is `endofstate'. Reads up to this line will not blocks, reads after this line will.

done

All pieces have been downloaded and verified.

started

Data exchange started.

stopped

Data exchange stopped.

newctl

A configuration parameter changed, typically returned after a write to the ctl file.

piece index have total

Piece index has been downloaded and verified. Have of total pieces are not stored locally.

block peer index blockindex blockhave blocktotal

Block blockindex from piece index has been received from peer, bringing the block totals to blockhave of blocktotal of the piece.

pieces index ...

Multiple pieces are downloaded and verified. These lines are normally returned as part of the state, before `endofstate'.

blocks index blockindex ...

Multiple blocks blockindex ... of piece index have been received. Returned as part of the state.

filedone fileindex sanepath origpath

Fileindex is indexes the file from files. sanepath and origpath are the sanitized and original path of the file

tracker interval waittime npeers trackerurl error

A tracker request has been completed. Interval is the interval between tracker requests, as requested by the tracker. Waittime the time until the next tracker request. Npeers the number of peers received in the request, only valid if error is empty. Trackerurl is the url of the tracker used, only valid if error is empty. Error is an error message in case of a failed tracker request.

error msg

For various errors, e.g. when connections to peers break. These are usually non-fatal.

hashfail index

Verification of downloaded piece index failed. A peer sent invalid blocks, the piece is downloaded again.

peerevents

The following lines can be returned:

endofstate

Like progress' `endofstate', the line after initial state, before starting to block on reads.

dialing address

Address is now being dialed.

tracker address

Address has been added to the pool of addresses of peers.

new address id peeridhex dialed

A new peer is now connected. Dialed is a number, only `0' means the connection was not dialed.

gone id

Peer id is no longer connected.

bad ip nextusetime peeridhex reason

A peer from ip has misbehaved and is banned until nextusetime for non-empty string reason.

state id localstate remotestate

The connection state changed. Local and remote state give the new state, an string that is `c' (choked) and/or `i' (interested) in it, or is empty.

piece id index

Peer id completed piece index.

pieces id index ...

id completed pieces index .... This is normally sent as part of the state or when a new peer connects.

done id

Peer id has completed all pieces.

	mkdir /mnt/torrent
	mount {torrent/peer $home/some.torrent} /mnt/torrent
	wm/torrent /mnt/torrent