Source RCON Protocol

From Valve Developer Community
Revision as of 19:51, 4 February 2006 by Erik Hollensbe (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This article was taken from a HLDS_APPS posting by Alfred Reynolds. If you have access to the hlds_apps list, you can view the original posting here.

Additional Remarks have been added to Alfred's Documentation. This is taken from the KQuery Wiki, as unfortunately the page is defaced. One can dig deeply through the revision history to obtain the information, some of which is vital to creating a working implementation.. I have taken the liberty of echoing it here.

Source Server RCON format

The protocol is based around command/response packets encapsulated in a TCP/IP stream. The stream can have multiple outstanding commands and can be extended to allow for multiple sub-channels of data.

Sending

The command packet format consists of:

  • packet size (int)
    • the number of bytes from the start of the requestid to the end of string2 (including the null byte). It must be at least 10.
  • request id (int)
  • SERVERDATA_EXECCOMMAND / SERVERDATA_AUTH (int)
    • SERVERDATA_AUTH is currently 3
    • SERVERDATA_EXECCOMMAND is currently 2
  • string1 (is the command to run).
  • string2 must be null ("");

For RCON connections the first command must be a SERVERDATA_AUTH command. If a SERVERDATA_EXECCOMMAND command is sent prior to successful authentication then a SERVERDATA_AUTH_RESPONSE response packet with the failure condition is sent (see the response section for details). The INT's are 32 Bit Little Endian byte order.

Receiving

The response packet is the same as the command packet, which is:

  • packet size (int)
    • It seems that if the response spans over multiple packets only the first has these fields. The Other packets are just data.
  • request id (int)
  • command response (int)
    • valid command responses being:
      SERVERDATA_RESPONSE_VALUE = 0
      or SERVERDATA_AUTH_RESPONSE = 2
  • string1 (null delimited string)
  • string2 (null delimited string)

SERVERDATA_AUTH_RESPONSE is sent in response to a SERVERDATA_AUTH command (or to a SERVERDATA_EXECCOMMAND command if the connection is not successfully authenticated). Both strings are set to null. If the request id is -1 (0xffffffff) then the authentication attempt failed (due to a bad password). If the request id is the same value as sent in the command (i.e the value was mirrored back) then authentication was successful. Any other request id is an error and the SERVERDATA_AUTH command should be resent.

SERVERDATA_RESPONSE_VALUE is sent in response to a SERVERDATA_EXECCOMMAND command. string1 contains the response to the command and string2 is null (""). string1 is at most 4096 characters, so a single SERVERDATA_EXECCOMMAND command may result in multiple SERVERDATA_RESPONSE_VALUE response packets.

Additional Comments

These are additional comments added by an anonymous reader on the KQuery wiki. These are accurate and recommended (and in some cases required) for proper implementation of the RCON protocol in Source.

  • Mutli packet responses do appear to give packet length, id and command in each packet HEX dump of cvarlist response
  • Request ID is mirrored back properly
  • CS:Source server sends one junk packet during the authentication step, before it responds with the correct authentication response.
  • The packet size field does NOT include the size of the packet size field itself. That is why the minimum length is 10 -- four bytes for the two integers (request ID and command) plus two bytes for the potentially empty ASCIIZ strings.
  • Make sure that you code the ability to handle multiple response "packets". With a 32-player server, it will use these commonly for status commands (for instance), just as HLDS often did. Also, keep in mind that you won't be able to read the whole "packet" at one time -- you need to keep reading in a loop until you receive the entire packet before processing it.

Implementations

A (hopefully comprehensive) listing of library implementations of the Source RCON protocol.

  • Ruby RCon RCon library for Source and Quake RCON derivatives (such as HLDS) written in Ruby.
  • C++ Sample class to do Source RCON in C++
  • CLI A command-line program to issue RCON commands, written in C
  • Python SRCDSpy Python Library to handle all Source Queries, including RCON
  • C# C# Library and Sample Program