RCon protocol: Difference between revisions
DrinkyBird (talk | contribs) (Created page with "Server admins often need to manage their servers, but launching Zandronum is slow and inconvenient. The ''RCON protocol'' allows us to make tools that connect to servers quick...") |
DrinkyBird (talk | contribs) No edit summary |
||
Line 20: | Line 20: | ||
Messages that the server sends to the client always begin with one of the following bytes: | Messages that the server sends to the client always begin with one of the following bytes: | ||
< | <syntaxhighlight lang="cpp" line="1" > | ||
enum | enum | ||
{ | { | ||
SVRC_OLDPROTOCOL = 32, //This set of enumerations starts at 32, increments by one | |||
SVRC_BANNED, | |||
SVRC_SALT, | |||
SVRC_LOGGEDIN, | |||
SVRC_INVALIDPASSWORD, | |||
SVRC_MESSAGE, | |||
SVRC_UPDATE, | |||
SVRC_TABCOMPLETE, | |||
SVRC_TOOMANYTABCOMPLETES, | |||
}; | }; | ||
</ | </syntaxhighlight> | ||
Messages that the client sends to the server always begin with one of the following bytes: | Messages that the client sends to the server always begin with one of the following bytes: | ||
< | <syntaxhighlight lang="cpp" line="1" > | ||
enum | enum | ||
{ | { | ||
CLRC_BEGINCONNECTION = 52, // Also increments by one | |||
CLRC_PASSWORD, | |||
CLRC_COMMAND, | |||
CLRC_PONG, | |||
CLRC_DISCONNECT, | |||
CLRC_TABCOMPLETE, | |||
}; | }; | ||
</ | </syntaxhighlight> | ||
Also, when the server sends SVRC_UPDATE, it's immediately followed by another byte: | Also, when the server sends SVRC_UPDATE, it's immediately followed by another byte: | ||
< | <syntaxhighlight lang="cpp" line="1" > | ||
enum | enum | ||
{ | { | ||
SVRCU_PLAYERDATA = 0, | |||
SVRCU_ADMINCOUNT, | |||
SVRCU_MAP, | |||
}; | }; | ||
</ | </syntaxhighlight> | ||
== Connecting to a server == | == Connecting to a server == |
Revision as of 14:32, 21 August 2016
Server admins often need to manage their servers, but launching Zandronum is slow and inconvenient. The RCON protocol allows us to make tools that connect to servers quickly and directly, letting administrators manage their servers with ease.
This article describes how to create RCON clients of your own that connect to Zandronum servers.
Protocol information
Version: 4 (backwards compatible with version 3)
See "article history" to look up the protocol for prior versions.
The basics
All Zandronum servers use UDP as their network protocol. Additionally, all traffic is compressed using the Huffman algorithm to save bandwidth. Therefore, you'll need a copy of huffman.cpp or huffman.java to encode and decode your traffic appropriately.
Definition of data types used in this article:
Byte: 8 bit integer (see the enumerated types below) String: null-terminated series of Bytes
Message headers
Messages that the server sends to the client always begin with one of the following bytes:
enum
{
SVRC_OLDPROTOCOL = 32, //This set of enumerations starts at 32, increments by one
SVRC_BANNED,
SVRC_SALT,
SVRC_LOGGEDIN,
SVRC_INVALIDPASSWORD,
SVRC_MESSAGE,
SVRC_UPDATE,
SVRC_TABCOMPLETE,
SVRC_TOOMANYTABCOMPLETES,
};
Messages that the client sends to the server always begin with one of the following bytes:
enum
{
CLRC_BEGINCONNECTION = 52, // Also increments by one
CLRC_PASSWORD,
CLRC_COMMAND,
CLRC_PONG,
CLRC_DISCONNECT,
CLRC_TABCOMPLETE,
};
Also, when the server sends SVRC_UPDATE, it's immediately followed by another byte:
enum
{
SVRCU_PLAYERDATA = 0,
SVRCU_ADMINCOUNT,
SVRCU_MAP,
};
Connecting to a server
Begin by sending two bytes to the server: CLRC_BEGINCONNECTION, followed by the protocol version you support (see above).
If you're banned by the server, you'll receive SVRC_BANNED.
If your version of the protocol is too old, you'll receive SVRC_OLDPROTOCOL, followed by the server's protocol version (byte), and the server's version string (string).
Otherwise, you'll receive the all-clear with SVRC_SALT, followed by a salt you'll use when you hash your password (string). This should be a 32 byte salt.
Now, create an MD5 hash of the provided salt, followed by the server's RCON password. You want to concatenate the salt and password together (salt first, password second), and then digest it into an MD5 hash. You have to send the hex version of the hash to the server. Send the server a packet with CLRC_PASSWORD and the hash. The pre-digested password does not need to be null-terminated.
If the password is incorrect, you'll receive SVRC_INVALIDPASSWORD.
Otherwise, you'll receive SVRC_LOGGEDIN. You're in! This is followed by the server's protocol version (byte), hostname (string) and some information on the server using the SVRC_UPDATE method described below. Basically, the server sends you the number of updates you're about to receive (byte), then the data for each one (which includes the header (SVRCU_MAP, SVRCU_ADMINCOUNT, etc), but not SVRC_UPDATE). Finally, some recent lines of the console are sent: first the number of lines (byte) followed by each line (strings).
Receiving updates
The server will now send you information as events occur on the server.
When a new line is printed on the server console, you'll receive SVRC_MESSAGE, followed by the message (string).
Other types of updates have been streamlined a little. They all start with SVRC_UPDATE. Then...
When the map changes, it's followed by SVRCU_MAP and the new map name (string).
When the number of other RCON admins changes, it's followed by SVRCU_ADMINCOUNT and the number (byte).
When the number of players changes, or a players changes his name, you'll receive SVRCU_PLAYERDATA, followed by the number of players (byte), and each of their names (strings).
Sending commands
Send the server CLRC_COMMAND, followed by the command (string). This should be a console command, and the server will execute it verbatim.
Tab completion for commands
Send CLRC_TABCOMPLETE
and a string of the command you want tab-completed.
If there are less than 50 results, the server will send SVRC_TABCOMPLETE
, the amount of completions as a byte, then the completetions as a series of strings.
If there are more than 50 results, the server will send SVRC_TOOMANYTABCOMPLETES
and the amount of completions as a byte.
Staying connected
By default, RCON clients not heard from within 10 seconds are timed out by the server. Therefore, you need to send the server CLRC_PONG regularly (we suggest every 5 seconds or so, to compensate for lag).
Disconnecting
Send the server CLRC_DISCONNECT.
Notes
That's all there is to it. Happy coding!
To discuss the protocol, use this forum and create a new topic.