Difference between revisions of "RCON"

From wiki.vg
Jump to navigation Jump to search
(mention rcon.port server config entry)
 
m (make it clear it's a TCP protocol)
(47 intermediate revisions by 24 users not shown)
Line 1: Line 1:
−
RCON is a protocol introduced in 1.9pre4 for the purpose of remote administration of a server. It's basically a shitty implementation of the Source RCON protocol [http://developer.valvesoftware.com/wiki/Source_RCON_Protocol]
+
'''RCON''' is a TCP/IP-based protocol that allows server administrators to remotely execute {{Minecraft Wiki|Commands|Minecraft commands}}. Introduced in Beta 1.9-pre4, it's basically an implementation of the [http://developer.valvesoftware.com/wiki/Source_RCON_Protocol Source RCON protocol] for Minecraft.
−
+
 
 
== Server Config ==
 
== Server Config ==
  
Line 6: Line 6:
 
     rcon.password=<your password>
 
     rcon.password=<your password>
 
     rcon.port=<1-65535>
 
     rcon.port=<1-65535>
 +
    broadcast-rcon-to-ops=false
  
 
The default port is 25575.
 
The default port is 25575.
Line 11: Line 12:
 
== Packet Format ==
 
== Packet Format ==
  
−
Integers are little-endian, in contrast with the [[Protocol|Beta protocol]].
+
Integers are little-endian, in contrast with the [[Protocol|Minecraft protocol]].
 +
 
 +
Responses are sent back with the same Request ID that you send. In the event of an auth failure (i.e. your login is incorrect, or you're trying to send commands without first logging in), request ID will be set to <code>-1</code>.
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Field name
 +
! Field type
 +
! Notes
 +
|-
 +
| Length
 +
| int32
 +
| Length of ''remainder'' of packet
 +
|-
 +
| Request ID
 +
| int32
 +
| Client-generated ID
 +
|-
 +
| Type
 +
| int32
 +
| <code>3</code> for login, <code>2</code> to run a command, <code>0</code> for a multi-packet response
 +
|-
 +
| Payload
 +
| byte[]
 +
| NULL-terminated ASCII text
 +
|-
 +
| 1-byte pad
 +
| byte
 +
| NULL
 +
|}
 +
 
 +
Note on ASCII text:
 +
Some servers reply with color codes prefixed by a section sign in their replies (for example Craftbukkit for Minecraft 1.4.7).
  
−
Responses are sent back with the same Request ID that you send.  
+
The section sign is sent by those servers as byte 0xA7 or 167. This is not part of the US-ASCII charset and will cause errors for clients that strictly use the US-ASCII charset.
  
−
In the event of an auth failure (i.e. your login is incorrect, or you're trying to send commands without first logging in), request ID will be set to <code>-1</code>
+
Using the ISO-LATIN-1/ISO-8859_1 charset instead of the US-ASCII charset yields much better results for those servers.
  
−
{| class="wikitable"
+
Alternatively removing byte 167 and one subsequent byte from the payload will remove all color tokens making the text more human readable for clients that do not subsequently colorize those tokens.
−
|-
 
−
! Field name
 
−
! Field Type
 
−
! Notes
 
−
|-
 
−
| Length
 
−
| int
 
−
| Length of ''remainder'' of packet
 
−
|-
 
−
| Request ID
 
−
| int
 
−
| Client-generated ID
 
−
|-
 
−
| Type
 
−
| int
 
−
| <code>3</code> for login, <code>2</code> to run a command
 
−
|-
 
−
| Payload
 
−
| byte[]
 
−
| ASCII text
 
−
|-
 
−
| 2-byte pad
 
−
| byte, byte
 
−
| Two null bytes
 
−
|}
 
  
 
== Packets ==
 
== Packets ==
Line 50: Line 58:
 
Outgoing payload: password.  
 
Outgoing payload: password.  
  
−
If the server returns a packet with the same request ID, auth was successful (note: packet type is 2, not 3). If you get an request ID of -1, auth failed (wrong password).
+
If the server returns a packet with the same request ID, auth was successful (note: packet type is 2, not 3). If you get a request ID of -1, auth failed (wrong password).
  
 
=== 2: Command ===
 
=== 2: Command ===
  
 
Outgoing payload should be the command to run, e.g. <code>time set 0</code>
 
Outgoing payload should be the command to run, e.g. <code>time set 0</code>
 +
 +
=== 0: Command response ===
  
 
Incoming payload is the output of the command, though many commands return nothing, and there's no way of detecting unknown commands.
 
Incoming payload is the output of the command, though many commands return nothing, and there's no way of detecting unknown commands.
  
−
== Implementation details ==
+
The output of the command may be split over multiple packets, each containing 4096 bytes (less for the last packet). Each packet contains part of the payload (and the two-byte padding). The last packet sent is the end of the output.
  
−
Maximum request length: 1460 (giving a max payload length of 1446)
+
== Fragmentation ==
  
−
Code exists in the notchian server to split large responses (>4096 bytes) into multiple smaller packets. However, the code that actually encodes each packet expects a max length of 1248, giving a max response payload length of 1234 bytes.
+
Maximum C->S packet payload length: 1446 (total: 1460) - outdated?
 +
 
 +
Maximum S->C packet payload length: 4096 (total: 4110)
 +
 
 +
The Minecraft server can fragment responses across multiple packets. There's no simple way to know when the last response packet has been received; approaches include:
 +
 
 +
# Wait until we receive a packet with a payload length < 4096 (not 100% reliable!)
 +
# Wait for ''n'' seconds
 +
# Send ''two'' command packets; the second command triggers a response from the server with the same Request ID, and from this we know that we've already received the full response to the first command.
 +
#* The second packet should use a command that will not produce fragmented output
 +
#* An alternative is for the second C->S packet to use an invalid type (say, 100); the server will respond with a 'Command response' packet with its payload set to 'Unknown request c8'. (100 in hexadecimal)
  
 
== Example implementations ==
 
== Example implementations ==
  
−
* https://github.com/barneygale/MCRcon (python, basic, synchronous)
+
* C
−
* https://gist.github.com/1292348 (php, basic, synchronous)
+
** https://github.com/tiiffi/mcrcon (synchronous, Zlib license)
−
* https://github.com/tehbeard/node-rcon (node.js, basic, asyncronous)
+
* C#
−
* https://bitbucket.org/jyc/rcon.js (RingoJS, synchronous, BSD-licensed)
+
** https://github.com/willroberts/minecraft-client-csharp (synchronous, GPL 3.0 license)
−
* https://bitbucket.org/jyc/rcon (PHP, synchronous, BSD-licensed)
+
* Dart
 +
** https://github.com/aidanlok/mc_rcon (client, asynchronous, BSD 3-Clause license)
 +
* Go
 +
** https://github.com/micvbang/pocketmine-rcon (synchronous, MIT license)
 +
** https://github.com/willroberts/minecraft-client (asynchronous, GPL 3.0 license)
 +
** https://godoc.org/github.com/Tnze/go-mc/net#RCONConn (client and server, synchronous, MIT license)
 +
* Java
 +
** https://github.com/jobfeikens/rcon (synchronous, GPL 3.0 license)
 +
** https://github.com/CatCoderr/JRcon (asynchronous, AGPL-3.0 license)
 +
* JavaScript
 +
** https://github.com/tehbeard/node-rcon (Node.js, asynchronous, no license)
 +
* Kotlin
 +
** https://github.com/willroberts/minecraft-client-kotlin (synchronous, GPL 3.0 license)
 +
* PHP
 +
** https://gist.github.com/1292348 (synchronous, no license)
 +
* Python 3
 +
** https://github.com/Iapetus-11/aio-mc-rcon (asynchronous, MIT license)
 +
** https://github.com/MrReacher/async-mcrcon (asynchronous, MIT license)
 +
** https://github.com/barneygale/MCRcon (synchronous, MIT license)
 +
** https://github.com/coNQP/mcipc (synchronous, GPL 3.0 license)
 +
* Rust
 +
** https://github.com/willroberts/minecraft-client-rs (synchronous, GPL 3.0 license)
 +
* Scala
 +
** https://github.com/A2PLab/minelib (connection-per-request, no license)
 +
** https://github.com/willroberts/minecraft-client-scala (synchronous, GPL 3.0 license)
 +
* TypeScript
 +
** https://github.com/MinecraftJS/rcon (Node.js, asynchronous, MIT license)
 +
** https://github.com/EnriqCG/rcon-srcds (Node.js, asynchronous, MIT license)
 +
** https://github.com/willroberts/minecraft-client-ts (Node.js, asynchronous, GPL 3.0 license)
 +
** https://github.com/janispritzkau/rcon-client (Node.js, asynchronous, no license)
 +
 
 +
[[Category:Minecraft Modern]]

Revision as of 20:43, 2 July 2023

RCON is a TCP/IP-based protocol that allows server administrators to remotely execute Minecraft commands. Introduced in Beta 1.9-pre4, it's basically an implementation of the Source RCON protocol for Minecraft.

Server Config

   enable-rcon=true
   rcon.password=<your password>
   rcon.port=<1-65535>
   broadcast-rcon-to-ops=false

The default port is 25575.

Packet Format

Integers are little-endian, in contrast with the Minecraft protocol.

Responses are sent back with the same Request ID that you send. In the event of an auth failure (i.e. your login is incorrect, or you're trying to send commands without first logging in), request ID will be set to -1.

Field name Field type Notes
Length int32 Length of remainder of packet
Request ID int32 Client-generated ID
Type int32 3 for login, 2 to run a command, 0 for a multi-packet response
Payload byte[] NULL-terminated ASCII text
1-byte pad byte NULL

Note on ASCII text: Some servers reply with color codes prefixed by a section sign in their replies (for example Craftbukkit for Minecraft 1.4.7).

The section sign is sent by those servers as byte 0xA7 or 167. This is not part of the US-ASCII charset and will cause errors for clients that strictly use the US-ASCII charset.

Using the ISO-LATIN-1/ISO-8859_1 charset instead of the US-ASCII charset yields much better results for those servers.

Alternatively removing byte 167 and one subsequent byte from the payload will remove all color tokens making the text more human readable for clients that do not subsequently colorize those tokens.

Packets

3: Login

Outgoing payload: password.

If the server returns a packet with the same request ID, auth was successful (note: packet type is 2, not 3). If you get a request ID of -1, auth failed (wrong password).

2: Command

Outgoing payload should be the command to run, e.g. time set 0

0: Command response

Incoming payload is the output of the command, though many commands return nothing, and there's no way of detecting unknown commands.

The output of the command may be split over multiple packets, each containing 4096 bytes (less for the last packet). Each packet contains part of the payload (and the two-byte padding). The last packet sent is the end of the output.

Fragmentation

Maximum C->S packet payload length: 1446 (total: 1460) - outdated?

Maximum S->C packet payload length: 4096 (total: 4110)

The Minecraft server can fragment responses across multiple packets. There's no simple way to know when the last response packet has been received; approaches include:

  1. Wait until we receive a packet with a payload length < 4096 (not 100% reliable!)
  2. Wait for n seconds
  3. Send two command packets; the second command triggers a response from the server with the same Request ID, and from this we know that we've already received the full response to the first command.
    • The second packet should use a command that will not produce fragmented output
    • An alternative is for the second C->S packet to use an invalid type (say, 100); the server will respond with a 'Command response' packet with its payload set to 'Unknown request c8'. (100 in hexadecimal)

Example implementations

Retrieved from "https://wiki.vg/index.php?title=RCON&oldid=18299"