RCON Tutorial¶
Introduction¶
Welcome to the tutorial for RCONClient! This section aims to give you a basic understanding of RCONClient usage.
Basic RCON Usage¶
mctools gives you the ability to interact with a server via RCON. The Minecraft RCON protocol allows admins to remotely execute Minecraft commands. The Minecraft RCON protocol is an implementation of the Source RCON protocol.
Note
While the RCON protocol is a common standard, we do not recommend using RCONClient for anything other than Minecraft. There has been no testing done on other RCON implementations.
Creating The Instance¶
First, you must create a RCONClient instance:
from mctools import RCONClient
rcon = RCONClient('mc.server.net')
This will create a RCONClient instance with the default configuration. All of the options can be set as you see fit, but the default configuration is recommended for most users. RCON can only be used if the server has RCON functionality enabled.
Note
For more information on general client configuration and instantiation, see the client tutorial.
Authenticating with the RCON server¶
Before you can start sending commands, you must first authenticate like so:
success = rcon.login('password')
Where ‘password’ is the password used to authenticate.
The function will return True for success, and False for failure. Most servers will require you to specify a password before you can send commands.
Note
By default, RCONClient will raise an exception if you attempt to send commands when not authenticated. You can read about disabling this feature below, but be aware that sending commands while not authenticated can lead to unstable operation.
If you have failed to authenticate, you may try again. mctools will allow you to attempt to authenticate as many times as you need, but the RCON server may have security features in place to block repeated login attempts.
If you have successfully authenticated, you can now start sending commands to the RCON server.
You can check if you are authenticated like so:
auth = rcon.is_authenticated()
This function will return True if you are authenticated, False if not.
Interacting with the RCON server¶
You may now send Minecraft commands to the server like so:
response = rcon.command("command")
Where ‘command’ is the command you wish to send to the RCON server. The function will return the response in string format from the server, formatted appropriately.
Note
You can disable the authentication check by passing ‘no_auth=True’ to the command function, which will disable the check for this command. Be aware that if the server refuses to serve you, then a RCONAuthenticationError exception will be raised.
For example, if you wanted to broadcast ‘Hello RCON!’ to every player on the server, you would issue the following:
response = rcon.command("broadcast Hello RCON!")
The command sent will broadcast “Hello RCON!” to every player on the server.
Note
Sometimes, the server will respond with an empty string. Some commands have no output, or return an empty string when issued over RCON, so this is usually a normal operation. It can also mean that the server doesn’t understand the command issued.
RCON Outgoing Packet length¶
The RCON Protocol has an outgoing(client to server) packet size limitation of 1460 bytes. Taking into account the mandatory information we have to send(request ID, type, padding, ect.), the maximum command size that can be sent is 1446 bytes.
This limitation unfortunately has no workaround, and is an issue with the RCON protocol, and therefore beyond our control. mctools does implement a length check to make sure outgoing packets are not too big.
If an outgoing packet is too big, and the length check is enabled, then an ‘RCONLengthError’ exception will be raised, and the packet will not be sent. This ensures that any nasty side effects of going over the outgoing limit will be avoided, thus keeping the connection in a stable state.
You can optionally disable the outgoing length check by passing ‘length_check=False’ to the command method.
Warning
Disabling outgoing length checks is not recommended! Doing so could mess up the state of your client!
Here is an example of disabling outgoing length checks:
# Lets send a HUGE command:
# (Assume 'huge_command' is a string containing a command larger than 1446 bytes)
resp = rcon.command(huge_command, length_check=False)
This will prevent the ‘RCONLengthError’ exception from being raised, and mctools will send the large packet normally.
If a large packet is sent to the RCON server, then some nasty things could occur. The most likely is that the server will forcefully close the connection, although other unsavory events could occur. This is why we recommend keeping the outgoing length check enabled.
RCON Incoming Packet Fragmentation¶
Sometimes, the RCON server will send fragmented packets. This is because RCON has an incoming(server to client) maximum packet size of 4096 bytes. RCONClient will automatically handle incoming packet fragmentation for you.
If the incoming packet is 4096 bytes in length, then we will assume the packet is fragmented. If this is the case, then mctools sends a junk packet to the server, and reads packets until the server acknowledges the junk packet. The RCON protocol ensures that all packets are sent in the order that they are received, meaning that once the server responds to the junk packet, then we can be sure that we have all of the relevant packets. We then concatenate the packets we received, and return it as one.
However, you can disable the check by passing ‘frag_check=False’ to the command method.
Warning
Disabling fragmentation checks is not recommended! Doing so could mess up the state of your client!
Here is an example of disabling RCON packet fragmentation:
# Lets run a command that generates fragmentation:
resp = rcon.command("help", frag_check=False)
This will return the content of the first 4096 bytes. Any subsequent call to ‘command’ or ‘raw_send’ will return the rest of the fragmented packets. This means that you will have incomplete content, and subsequent calls will return irrelevant information. Unless you have a reason for this, it is recommended to keep packet fragmentation enabled.
Ending the session¶
To end the session with the server correctly, do the following:
rcon.stop()
This will stop the underlying TCP connection to the server. It is ALWAYS recommended to stop the instance, as not doing so could cause problems server-side.
Conclusion¶
And that concludes the basic usage for RCONClient!