RCon protocol

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.