CTCS Protocol

This page documents the CTCS client-server communication protocol. The current protocol version is 3. The information here could be used as a reference for debugging or to develop other applications to interface with CTorrent or CTCS.

Note the following when interpreting this specification:

Each message is valid in the indicated protocol version and higher.
A message or message format is not valid in a higher protocol version where a different message or format is specified. (If a message format is specified for protocol 2, then the protocol 1 format will not be used under protocols 2 or 3.)
If no protocol version is indicated, the message is valid in all versions.

Syntax Notes

Parameters are in text form. The number 100 would be sent as the text string "100" rather than as a binary representation or encoding.
Punctuation in message parameter sequences, where shown, is required.
While it is intended that variable whitespace (tabs and multiple spaces) be allowed, in general it is recommended to use a single space. The current implementation has not been thoroughly updated to allow for other types or amounts of whitespace in all messages.

List of Messages

Client-originated:


AUTH,
CTBW,
CTCONFIG,
CTCONFIGDONE,
CTCONFIGSTART,
CTDETAIL,
CTFILE,
CTFILESDONE,
CTFILESTART,
CTINFO,
CTORRENT,
CTSTATUS,
CTPEER,
CTPEERSDONE,
CTPEERSTART,
PROTOCOL

Deprecated:


CTFDONE,
CTFILES,
CTPDONE,
CTPEERS

Server-originated: CTCONFIG, CTQUIT, CTRESTART, CTUPDATE, ERROR, PROTOCOL, SENDCONF, SENDDETAIL, SENDPEERS, SENDSTATUS, SETDLIMIT, SETULIMIT

Example Exchanges

Client (CTorrent)	Server (CTCS)
`PROTOCOL`	`PROTOCOL`
`AUTH` (possibly)
	`ERROR` (possibly)
`CTORRENT`
`CTSTATUS`
	`SETDLIMIT`
	`SETULIMIT`
`CTBW`
...
	`SENDSTATUS`
`CTSTATUS`
...
	`SENDDETAIL`
`CTDETAIL`
`CTFILESTART`
`CTFILE` (multiple)
`CTFILESDONE`
...
	`SENDPEERS`
`CTPEERSTART`
`CTPEER` (multiple)
`CTPEERSDONE`
...
	`SENDCONF`
`CTCONFIGSTART`
`CTCONFIG` (multiple)
`CTCONFIGDONE`
	`CTCONFIG` (with changes)

Client-originated Messages

PROTOCOL

PROTOCOL version

Upon connection, this message is sent by both the client and the server to indicate the CTCS protocol version that each supports. The information should be used to format message parameters appropriately for the other side and to recognize that newer messages will not be recognized (and should be avoided if possible). This should be the first message sent when the connection is established. It may be sent again with a different version confirming a "negotiation down" of the protocol version that will be used, but this is not required.

version: The protocol version expressed as four ASCII numeric digits, e.g. 0001

AUTH

AUTH password

If authentication is used, the client sends this message upon connection (after protocol identification).

password: A password or passphrase string.

CTORRENT

CTORRENT peer_id start_timestamp current_timestamp filename

The client sends this message upon connection to identify itself to CTCS.

peer_id: The peer ID string of the client. CTCS can use this to uniquely identify the client.
start_timestamp: The time at which the client was started, in seconds. The convention for obtaining and reporting this value should be the same as that used for the current_timestamp below.
current_timestamp: The current time in seconds. This will be used as a reference for working with the start_timestamp (above), so any consistent convention will work. Using the time returned by the system is recommended. The client's elapsed time since starting could also be used if this value is available.
filename: The name of the torrent file that the client is exchanging.

CTCONFIGSTART

Protocol 3:

CTCONFIGSTART

The client sends this message to indicate that it is sending a list of configuration options. It may be sent in response to a SENDCONF message from the server or independently if something has changed. This message is followed by a CTCONFIG message for each option, and then by a CTCONFIGDONE message.

CTCONFIG

Protocol 3:

CTCONFIG name type range len:value len:short_desc len:long_desc

For previous protocols, see the old format of this message.

The client sends this message as part of a CTCONFIGSTART sequence to describe its entire configuration, or independently to notify of a configuration change.

name

The name that is used internally to identify and manipulate the option.

type

A single uppercase letter indicating the type of the option:

I = integer
F = floating-point number
B = binary (value may be 0 or 1)
S = string

range

A range (x-y) indicating the acceptable numeric values of the option, or a single number indicating the maximum acceptable string length.

len

The actual length of the parameter that follows.

value

The current value of the option.

short_desc

A brief description for the user; this is intended to provide a descriptive name.

long_desc

A longer description (think "short one-liner", not "help screen").

CTCONFIGDONE

Protocol 3:

CTCONFIGDONE

The client sends this message at the end of a CTCONFIGSTART sequence to indicate that the complete list of configuration options has been sent.

CTCONFIG

Protocol 3:
See the new format of this message.

Protocol 2:

CTCONFIG verbose seedtime seed_ratio maxpeers minpeers fileno cache_size pause

Protocol 1:

CTCONFIG verbose seedtime seed_ratio maxpeers minpeers fileno exitzero pause soft_quit

The client sends this message in response to a SENDCONF message from the server, or to notify the server of configuration changes. The server can send this message to change the client's configuration. The server can use a dot (".") in any parameter position to leave that setting as it is.

verbose: Turn the CTorrent -v (verbose console reporting) command-line option on (1) or off (0).
seedtime: Set the value of the CTorrent -e (seed time) command-line option. Note that this is the total hours to seed, including hours that have already passed.
seed_ratio: Set the value of the CTorrent -E (seed ratio) command-line option. (A value of 0 turns the option off.)
maxpeers: Set the value of the CTorrent -M (maximum peers) command-line option.
minpeers: Set the value of the CTorrent -m (minimum peers) command-line option.
fileno: Set the value of the CTorrent -n (file number to download) command-line option. (A value of 0 turns the option off.)
exitzero: Tell the client to exit (quit) if or when it has no peer connections. This is an option which can be turned on(1) or off (0).
cache_size: Set the value of the CTorrent -C (maximum cache size) command-line option.
pause: Tell the client to pause. The client will de-register with the tracker and refuse new peer connections (but continue to serve existing peers as long as they stay connected). This is an option which can be turned on(1) or off (0).
soft_quit: Tell the client to pause, and then exit (quit) if or when it has no peer connections. This is an option which can be turned on(1) or off (0).

CTBW

CTBW dl_rate,ul_rate dl_limit,ul_limit

The client sends this message periodically (unsolicited) to report its current transfer rates and limits. The client should send this message whenever the download or upload rate changes.

dl_rate: The current measured download rate in bytes per second.
ul_rate: The current measured upload rate in bytes per second.
dl_limit: The current download rate limit in bytes per second.
ul_limit: The current upload rate limit in bytes per second.

CTINFO

CTINFO severity message

The client can send this message to report errors or general status information.

severity: A numeric digit indicating the importance of the message. The severity is optional and need not be present.
message: A freeform text string.

CTSTATUS

Protocol 2:

CTSTATUS seeders:total_seeders/leechers:total_leechers/connecting n_have/n_total/n_avail dl_rate,ul_rate dl_total,ul_total dl_limit,ul_limit cache_used

Protocol 1:

CTSTATUS seeders/leechers n_have/n_total/n_avail dl_rate,ul_rate dl_total,ul_total dl_limit,ul_limit

The client sends this message in response to a SENDSTATUS message from the server. The information is typical of what might be included in a client's status display. It can also be sent unsolicited in place of a CTBW message to provide an initial status or to communicate important changes (such as completion of the torrent).

seeders: The number of "seeders" (peers with the complete torrent) connected to the client.
total_seeders: The number of seeders available in the swarm.
leechers: The number of "leechers" (peers with less than the complete torrent) connected to the client.
total_leechers: The number of leechers available in the swarm.
connecting: The number of peer connections in progress (in process of being established).
n_have: The number of pieces that the client has completed.
n_total: The total number of pieces in the torrent.
n_avail: The overall number of pieces available among peers connected to the client.
dl_rate: The current measured download rate in bytes per second.
ul_rate: The current measured upload rate in bytes per second.
dl_total: The total bytes downloaded by the client.
ul_total: The total bytes uploaded by the client.
dl_limit: The current download rate limit in bytes per second.
ul_limit: The current upload rate limit in bytes per second.
cache_used: The amount of cache currently used in kilobytes.

CTPEERSTART

Protocol 3:

CTPEERSTART

Protocol 1:

CTPEERS

The client sends this message in response to a SENDPEERS message from the server. It tells the server that the client is beginning to send a list of its peers. This message is followed by a CTPEER message for each peer (if the client has any), and then by a CTPEERSDONE message.

CTPEER

CTPEER peer_id address choke_interest dl_rate ul_rate dl_total ul_total n_pieces

The client sends this message as part of a CTPEERSTART sequence. The message reports the details of one peer.

peer_id

The peer's peer ID string.

address

The peer's IP address in dotted quad form. Optionally, the port number may be included by appending it preceded by a colon (x.x.x.x:port).

choke_interest

A string of four characters indicating "choke" and "interested" status:

C or U indicating that the peer has Choked or Unchoked the client.
i or n indicating that the client is interested (or not) in the peer's pieces.
C or U indicating that the client has Choked or Unchoked the peer.
i or n indicating that the peer is interested (or not) in the client's pieces.

dl_rate

The client's current measured download rate from the peer.

ul_rate

The client's current measured upload rate to the peer.

dl_total

The total bytes downloaded from the peer.

ul_total

The total bytes uploaded from the peer.

n_pieces

The number of pieces that the peer has completed.

CTPEERSDONE

Protocol 3:

CTPEERSDONE

Protocol 1:

CTPDONE

The client sends this message at the end of a CTPEERSTART sequence to indicate that the complete list of peers has been sent.

CTDETAIL

CTDETAIL torrent_size piece_size current_timestamp seed_timestamp

The client sends this message in response to a SENDDETAIL message from the server to report information related to ratios and seed time. This may also be followed by a CTFILESTART sequence.

torrent_size: The total size of the torrent in bytes.
piece_size: The size of a piece, in bytes.
current_timestamp: The current time in seconds. This will be used as a reference for working with the seed_timestamp (below), so any consistent convention will work. Using the time returned by the system is recommended. The client's elapsed time since starting could also be used if this value is available.
seed_timestamp: The time at which the client began seeding, in seconds. The convention for obtaining and reporting this value should be the same as that used for the current_timestamp above.

CTFILESTART

Protocol 3:

CTFILESTART

Protocol 1:

CTFILES

The client may send this message following a CTDETAIL response. It tells the server that the client is beginning to send a list of the torrent files. This message is followed by a CTFILE message for each file, and then by a CTFILESDONE message.

CTFILE

Protocol 3:

CTFILE fileno priority current_priority n_pieces n_have n_available filesize filename

Protocol 2:

CTFILE fileno n_pieces n_have n_available filesize filename

Protocol 1:

CTFILE fileno n_pieces n_have filesize filename

The client sends this message as part of a CTFILESTART sequence. The message reports the details of one file.

fileno: The sequence number of the file in the torrent.
priority: The download priority of the file, a number indicating the sequence in which files (or groups of files) will be downloaded.
current_priority: The sequence number of the group of files currently being downloaded. (Files with a matching priority are currently being downloaded.)
n_pieces: The number of pieces comprising the file.
n_have: The number of file pieces that the client has completed.
n_available: The number of file pieces that are available in the swarm.
filesize: The size of the file in bytes.
filename: The name of the file.

CTFILESDONE

Protocol 3:

CTFILESDONE

Protocol 1:

CTFDONE

The client sends this message at the end of a CTFILESTART sequence to indicate that the complete list of files has been sent.

Server-originated Messages

PROTOCOL

PROTOCOL version

This message is identical to the client-originated PROTOCOL message.

CTCONFIG

Protocol 3:

CTCONFIG name value

For previous protocols, see the old format of this message.

The server sends this message to the client to change a configuration option.

name: The name that is used internally to identify and manipulate the option.
value: The new value of the option.

CTCONFIG

Protocol 3:
See the new format of this message.

Protocol 2:

CTCONFIG verbose seedtime seed_ratio maxpeers minpeers fileno cache_size pause

Protocol 1:

CTCONFIG verbose seedtime seed_ratio maxpeers minpeers fileno exitzero pause soft_quit

This message is identical to the client-originated CTCONFIG message.

ERROR

ERROR message

The server can send this message to report an error to the client. This would normally be used for CTCS issues such as authentication; the client would display the message in its console window.

message: A freeform text string.

CTQUIT

CTQUIT

The server can send this message to tell the client to exit gracefully (it will attempt to update the tracker).

CTRESTART

CTRESTART

The server can send this message to tell the client to restart its tracker session. The client will de-register with the tracker, then re-register with the tracker as a new peer.

CTUPDATE

CTUPDATE

The server can send this message to tell the client to update statistics with the tracker and try to obtain more peers.

SETDLIMIT

SETDLIMIT dl_limit

The server can send this message to change the client's download limit.

dl_limit: The new download limit in bytes per second.

SETULIMIT

SETULIMIT ul_limit

The server can send this message to change the client's upload limit.

ul_limit: The new upload limit in bytes per second.

SENDSTATUS

SENDSTATUS

The server can send this message to request the client to report detailed status information. The client responds with a CTSTATUS message.

SENDPEERS

SENDPEERS

The server can send this message to request the client to report detailed information about its connected peers. The client responds with a CTPEERS message sequence.

SENDDETAIL

SENDDETAIL

The server can send this message to request the client to report detailed torrent information. The client responds with a CTDETAIL message.

SENDCONF

SENDCONF

The server can send this message to request the client to report its current configuration. The client responds with a CTCONFIG message.