Source RCON Protocol

This article was taken from a HLDS_APPS posting by Alfred Reynolds.

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)
  • If the response spans over multiple packets only the first has these fields. The Other packets are just data.
    • It seems to me, that this has been changed, my response are including those fields. --Plastofix 18:46, 19 Dec 2007 (PST)
• 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.

• 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.
  • It seems this junk packet is also valid under HL2:DM, not just CS:Source, so probably applies to all Source games (unless Rcon stuff is done differently in other Source powered games by 3rd parties). --Bartk 12:13, 2 Oct 2006 (PDT)
• 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.

Other User Comments:

• For a detailed packet structure, run Wireshark (ethereal) in tandem with hlsw and follow the TCP packet stream. --TGAcid 13:22, 13 Jan 2008 (PST)

Packet Structure Client/Server Communication Examples

Example of TCP communication authentication request with rcon password "passwrd", then subsequent rcon commands and responses for "echo HLSW: Test", "log", and "status" --TGAcid 13:22, 13 Jan 2008 (PST)

00000000  11 00 00 00 00 00 00 00  03 00 00 00 62 34 62 79 ........ ....pass           <-- password is 7 chars long
00000010  6c 30 6e 00 00                                   wrd..
                                                                             00000000  0a 00 00 00 00 00 00 00  00 00 00 00 00 00       ........ ......
                                                                             0000000E  0a 00 00 00 00 00 00 00  02 00 00 00 00 00       ........ ......
00000015  19 00 00 00 00 00 00 00  02 00 00 00 65 63 68 6f ........ ....echo
00000025  20 48 4c 53 57 3a 20 54  65 73 74 00 00           HLSW: T est..
                                                                             0000001C  17 00 00 00 00 00 00 00  00 00 00 00 48 4c 53 57 ........ ....HLSW
                                                                             0000002C  20 3a 20 54 65 73 74 20  0a 00 00                 : Test  ...
00000032  0d 00 00 00 00 00 00 00  02 00 00 00 6c 6f 67 00 ........ ....log.
00000042  00                                               .
                                                                             00000037  4c 00 00 00 00 00 00 00  00 00 00 00 55 73 61 67 L....... ....Usag
                                                                             00000047  65 3a 20 20 6c 6f 67 20  3c 20 6f 6e 20 7c 20 6f e:  log  < on | o
                                                                             00000057  66 66 20 3e 0a 63 75 72  72 65 6e 74 6c 79 20 6c ff >.cur rently l
                                                                             00000067  6f 67 67 69 6e 67 20 74  6f 3a 20 66 69 6c 65 2c ogging t o: file,
                                                                             00000077  20 63 6f 6e 73 6f 6c 65  2c 20 75 64 70 0a 00 00  console , udp...
000000D6  10 00 00 00 00 00 00 00  02 00 00 00 73 74 61 74 ........ ....stat
000000E6  75 73 00 00                                      us..
                                                                             00000134  e4 00 00 00 00 00 00 00  00 00 00 00 68 6f 73 74 ........ ....host
                                                                             00000144  6e 61 6d 65 3a 20 54 61  73 6b 66 6f 72 63 65 72 name: Ta skforcer
                                                                             00000154  61 6e 67 65 72 2e 6e 65  74 20 54 46 32 20 2d 20 anger.ne t TF2 - 
                                                                             00000164  54 65 61 6d 77 6f 72 6b  21 0a 76 65 72 73 69 6f Teamwork !.versio
                                                                             00000174  6e 20 3a 20 31 2e 30 2e  31 2e 34 2f 31 34 20 33 n : 1.0. 1.4/14 3
                                                                             00000184  33 34 35 20 73 65 63 75  72 65 20 0a 75 64 70 2f 345 secu re .udp/
                                                                             00000194  69 70 20 20 3a 20 20 38  2e 32 2e 30 2e 32 38 3a ip  :  8 .2.0.28:
                                                                             000001A4  32 37 30 31 35 0a 6d 61  70 20 20 20 20 20 3a 20 27015.ma p     : 
                                                                             000001B4  74 63 5f 68 79 64 72 6f  20 61 74 3a 20 30 20 78 tc_hydro  at: 0 x
                                                                             000001C4  2c 20 30 20 79 2c 20 30  20 7a 0a 70 6c 61 79 65 , 0 y, 0  z.playe
                                                                             000001D4  72 73 20 3a 20 30 20 28  32 30 20 6d 61 78 29 0a rs : 0 ( 20 max).
                                                                             000001E4  0a 23 20 75 73 65 72 69  64 20 6e 61 6d 65 20 75 .# useri d name u
                                                                             000001F4  6e 69 71 75 65 69 64 20  63 6f 6e 6e 65 63 74 65 niqueid  connecte
                                                                             00000204  64 20 70 69 6e 67 20 6c  6f 73 73 20 73 74 61 74 d ping l oss stat
                                                                             00000214  65 20 61 64 72 0a 00 00                          e adr...

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 (by Andrew Simpson)
• Java Java RCON Library for Source (also HL1, COD/2, and BF2)
• VB6 VisualBasic 6.0 (Source RCON only) sample up to you to process DataArrival (by: Jaime Gavin)