Zanka Software Axel Andersson Request for Comments: 3 February 2005 Wired Tracker Protocol 1.0 Status of this Memo This memo provides information for the Internet community. It describes an Internet protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) Axel Andersson 2004-2005. All Rights Reserved. Abstract The Wired Tracker protocol is an application-level protocol for exchanging information of presently online Wired servers. Servers connect to the tracker and register themselves using the Wired Tracker protocol. Clients can then fetch information about servers by connecting to the tracker and requesting a server listing. Table of Contents 1 Introduction ...................................................2 1.1 Purpose ......................................................2 1.2 Terminology ..................................................2 1.3 Overall Operation ............................................3 2 Sequences ......................................................3 2.1 Login Sequence ...............................................3 3 Registration ...................................................3 4 Commands .......................................................4 4.1 Command Format ...,............................................4 4.2 Command Listing ...............................................4 4.2.1 CATEGORIES ................................................4 4.2.2 CLIENT ....................................................4 4.2.3 HELLO .....................................................5 4.2.4 REGISTER ..................................................5 4.2.5 SERVERS ...................................................5 4.2.6 UPDATE ....................................................6 5.1 Message Format ................................................6 5.2 200 Class Messages ............................................6 5.2.1 200 Tracker Information ...................................6 5.3 500 Class Messages ............................................7 5.3.1 500 Command Failed ........................................7 5.3.2 501 Command Not Recognized ................................7 5.3.3 502 Command Not Implemented ...............................7 5.3.4 503 Syntax Error ..........................................7 5.3.5 511 Banned ................................................7 5.3.6 516 Permission Denied .....................................7 5.3.7 530 Address Registered ....................................8 5.3.8 531 Address Mismatch ......................................8 5.4 700 Class Messages ............................................8 5.4.1 700 Registered ............................................8 5.4.2 710 Category Listing ......................................8 5.4.3 711 Category Listing Done .................................8 5.4.4 720 Server Listing ........................................8 5.4.5 721 Server Listing Done ...................................9 6 References .....................................................9 7 Author's Address ...............................................9 8 Full Copyright Statement .......................................10 1 Introduction 1.1 Purpose The Wired Tracker protocol is an application-level protocol for exchanging information of presently online Wired servers. Servers connect to the tracker and register themselves using the Wired Tracker protocol. Clients can then fetch information about servers by connecting to the tracker and requesting a server listing. This protocols draws heavily upon the Wired client/server protocol. It relies on the same structure, and only adds new commands and messages. Refer to the Wired Protocol specification [1] for definitions of the protocol parameters that are not duplicated in this specification. 1.2 Terminology client A program that establishes connections for the purpose of sending commands and interpreting messages. In this context, a client is either a program that connects to the tracker for the purpose of retrieving information about servers, or a program that connects to the tracker for the purpose of making itself available to clients. command A command sent from a client to a tracker, as defined in section 4. identifier A unique 3-digit number that describes the type of message. field A part of a command or a message that conveys a particular pre-defined type of information. message A message sent from a tracker to a client, as defined in section 4. tracker A program that accepts connections in order to service commands by sending back messages. In this context, a server that has both servers and clients as clients. 1.3 Overall Operation The Wired Tracker protocol is a textual command/message protocol. A client sends a command in a specific format to the tracker, and the tracker interprets this command, and if needed, sends back a message with requested information. Normal Wired Tracker communication takes place over a TCP/IP connection using TLS [2]. The default port is TCP 2002. Servers also send status updates to the tracker over UDP on the same port. 2 Sequences 2.1 Login Sequence The login sequence takes place directly after the client has established a connection with the tracker. 1. The client initiates the sequence by sending the "HELLO" command. 2. The tracker responds with the 200 Tracker Information or 511 Banned message. 3. The client optionally sends the "CLIENT" command. 3 Registration Maintaining a server in the servers list requires that the server first connects to the tracker and registers itself, and then sends regular status update to verify that it is online. Registration takes place over the normal TCP/IP connection, using the "REGISTER" command. When registering, the tracker associates the server with a key, that the server needs to retain. The key is sent in the 700 message. If the URL [3] given in the "REGISTER" command does not match the originating host, the tracker can refuse registration. To send a status update, send the "UPDATE" command to the tracker over UDP, with the key as the first argument. It is recommended that status updates are sent every minute or so. The tracker can interpret a missing status update as a disconnected server and remove it from the listing. Status update messages should be encrypted with the public key used for TLS communication over the TCP/IP channel. The tracker should support re-registration, that is, sending a "REGISTER" command with the same URL. This is the only way to update the name and description fields. 4 Commands 4.1 Command Format A command from a client to a server includes a unique command, optionally followed by a single space and arguments. The command is terminated with EOT. command = name [SP argument] EOT name = "CATEGORIES" | "CLIENT" | "HELLO" | "REGISTER" | "SERVERS" | "UPDATE" 4.2 Command Listing 4.2.1 CATEGORIES "CATEGORIES" EOT Retrieve the categories list. On success, returns a chain of 710 and a terminating 711. 4.2.2 CLIENT "CLIENT" SP app-version EOT Send the client version information. See section 2.1 for more information on the login sequence. 4.2.3 HELLO "HELLO" EOT Start a conversation with a tracker. See section 2.1 for more information on the login sequence. On success, returns a 200. On failure, may return the error 511. 4.2.4 REGISTER "REGISTER" SP category FS url FS name FS bandwidth FS description EOT category = STRING url = STRING name = URL bandwidth = 1*DIGIT description = STRING Register the sender as a new server. The server will be listed under "category", with the URL "url", with "name" and "description" as strings that are presented to the user. "bandwidth" is the registering server's available bandwidth in bytes/second. See section 3 for more information on registration. On success, returns a 700. On failure, may return the errors 516, 530 or 531. 4.2.5 SERVERS "SERVERS" EOT Retrieve the servers list. On success, returns a chain of 720 and a terminating 721. 4.2.6 UPDATE "UPDATE" SP hash FS users FS guest FS download FS files FS size EOT hash = STRING users = 1*DIGIT guest = BOOLEAN download = BOOLEAN files = 1*DIGIT size = 1*DIGIT Updates a previously registered server with "hash". "users" is the number of online users, "guest" indicates whether the guest account can connect, "download" whether the guest account can download files, "files" is the number of files and "size" is the total byte size of all files. 5 Server Messages 5.1 Message Format A message from a server to a client includes a unique three-digit number, followed by a space, then optional fields, and a terminator. message = identifier [SP argument] EOT identifier = "200" "500" | "501" | "502" | "503" | "511" | "516" | "530" "700" | "710" | "711" | "720" | "720" The first digit of the identifier defines the class of response. The last two digits do not have any categorization role. There are three values for the first digit: 2xx Information 5xx Errors 7xx Tracker 5.2 200 Class Messages 5.2.1 200 Tracker Information "200" SP app-version FS protocol-version FS server-name FS server-description FS start-time server-name = STRING server-description = STRING start-time = date-time Basic information about the tracker. In response to "HELLO". 5.3 500 Class Messages 5.3.1 500 Command Failed "500" SP "Command Failed" EOT An undefined internal error prevented the command from completing. 5.3.2 501 Command Not Recognized "501" SP "Command Not Recognized" EOT The command was not recognized. 5.3.3 502 Command Not Implemented "502" SP "Command Not Implemented" EOT The command has not been implemented by the server. 5.3.4 503 Syntax Error "503 Syntax Error" EOT There was a syntax error in the command. 5.3.6 511 Banned "511" SP "Banned" EOT The login could not complete, the user is banned. 5.3.11 516 Permission Denied "516" SP "Permission Denied" EOT The command could not complete, the client lacks sufficient privileges. 5.3.11 530 Address Registered "530" SP "Address Registered" EOT Registration could not complete, a server with that address has already been registered. 5.3.11 531 Address Mismatch "531" SP "Address Mismatch" EOT Registration could not complete, the address given does not resolve back to the originating host. 5.4 500 Class Messages 5.4.1 700 Registered "700" SP hash EOT The server was successfully registered and has been associated with the key "hash". In response to "REGISTER". 5.4.2 710 Category Listing "711" SP category EOT A category in the categories listing. The sorting of the categories listing is undefined. In response to "CATEGORIES". 5.4.3 711 Category Listing Done "711" SP "Done" EOT End of categories listing. In response to "CATEGORIES". 5.4.4 720 Server Listing "720" SP category FS url FS name FS users FS bandwidth FS guest FS download FS files FS size FS description EOT url = STRING name = STRING users = 1*DIGIT bandwidth = 1*DIGIT guest = BOOLEAN download = BOOLEAN files = 1*DIGIT size = 1*DIGIT description = STRING The server was successfully registered and has been associated with the A server in the servers listing. "url" is the full URL to server, "name" is the name of the server, "users" the number of online clients, "bandwidth" the available bandwidth in bytes/second. "guest" indicates whether the guest account can connect, and "download" whether the guest account can download files. "files" is the number of files on the server, and "size" the total size of all files in bytes. "description" is a description of the server. The sorting of the servers listing is undefined. In response to "SERVERS". 5.4.5 721 Server Listing Done "721" SP "Done" EOT End of servers listing. In response to "SERVERS". 6 References [1] Andersson, A., "Wired Protocol 1.1", Zanka Software RFC 2, August 2004. [2] Dierks, D. and Allen, C., "The TLS Protocol Version 1.0", RFC 2246, January 1999. [3] Berners-Lee T. et al, "Uniform Resource Locators (URL)", RFC 1738, December 1994. 7 Author's Address Axel Andersson, axel@zankasoftware.com 8 Full Copyright Statement Copyright (C) Axel Andersson 2004-2005. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice, this paragraph and the following disclaimer are included on all such copies and derivative works. THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.