Ravaged Remote Connection (RCon) Protocol DocumentationEdit
This article documents the Ravaged RCon protocol used in 2Dawn Games' upcoming title Ravaged (http://www.2dawn.com). It was last updated on June 20th, 2012.
RCon Life Cycle Edit
A high level overview of the Ravaged RCon system boils down to three parts:
- Establish a TCP socket connection to a Ravaged server's RCon port
- Authenticate an administrator
- Send UTF8 text to execute server commands that will return UTF8 responses
The TCP socket is non-blocking, so any number of admins may log in simultaneously. Use of "user" admins is helpful for many reasons that should become clear soon, and admins will be called "users" throughout this document. Authentication relies on a SHA1 hash of the password, which isn't perfect but provides a good balance for ease of implementation in an already relatively insecure system. The RCon system is in no way impervious to man in the middle attacks, so if you're really worried about the security of your server, you will probably not want to login as the superuser remotely.
Once logged in, the Ravaged server will not passively send any data to you. It only responds to requests made by sending commands which allows for more flexibility. Messages are sent from the server to RCon in the following format:
(<data byte count>)<command name>:<utf8 encoded result>
An example of this might be
[Client sends] testrcon ... some time later [Client recs] (16)testrcon:Ceská
The data section of this message, "testrcon:Ceská" gets UTF8 encoded into 16 bytes, since two chars are non-ASCII and require 2 bytes. This scheme allows for messages to come out of order, since the command being responded to is always the first part of the data. Length information is required for correctly receiving multiple messages in one packet - keep looking for new messages until your buffer is empty.
There are any number of ways to establish a TCP connection to the remote RCon port. Remember that all text sent needs to be UTF8 encoded, and all text received will also be UTF8 encoded. Once a connection is established, you will need to authenticate. This is done by optionally sending:
where "Admin" is the default name used for logging as the superuser, followed by:
PASS=<SHA1 hash of password UTF8 encoded>
If the login succeeds, you will receive the message
Login success as <username>.
and if it fails you will receive
Login failed - please send the password again.
This way a login using a thin RCon text client will get back human readable messages, but it should be trivial to parse "Login <success:failed> " out of the start of the message. On failure, you may send the PASS command again, but the connection may be closed after some amount of failures.
User Administration Edit
Once a user is logged in, commands can be sent to the server. If the user is logged in as "Admin", superuser commands can be used. At the moment these all pertain to user management.
useradd <new user name> <SHA1 hash of password UTF8 encoded> Creates a new admin user.
userdel <user name> YES Deletes an admin user. Requires YES for confirmation, will delete a user thus revoking their login privilege.
userpass <optional user name> <new password> Changes the password of an admin user. If the superuser runs this command, it will change the given user's password. If a user runs it, passing in only the new password, it will change their password. superuserAdminList Reports a list of all the users on this server. ** Name to change!
Player Names vs Steam IDs Edit
Player names are Steam names, so they may contain pretty much any unicode character. For the reason, it can be a hassle for admins (and this system can be abused by malicious players) to administrate by player name.
All commands listed below that take a <player> will take either a player name or a Steam ID. Note that the Steam ID for each player is returned on execution of the getplayerlist command.
Admin Commands Edit
This list is in progress, and it is likely these commands will change before release!
Here I will attempt to document all of the available commands that a user can execute on a Ravaged server. Each command that sends lists back to the user does it in the format of
<listname>:<space> <delimited> <elements>\n<space> <delimited> <elements>\n
where all items are space delimited and each group is new line delimited. Here lies a growing, incomplete command list:
addmap <mapname> <optional int index> Adds or inserts a map into the map queue. If <index> isn't given, the map is added to the end of the queue. If it is given, the map is inserted before i in the queue. Can use "addmap <mapname> 1" "nextmap" to change to a new map. Inserting at 0 is invalid, and your map will be inserted at 1 instead. dc Disconnects the client from the server.
exit Shuts down the server. When using the default text-based RCon client, this command requires a confirmation of YES ("exit YES") to shut down the server. getmaplist <optional bool annotated = true> Reports the map queue. For a human readable maplist, set annotated to true (default). If annotated is set to false, it returns a map list using the template "0 Map0Name\n1 Map1Name\n2 Map2Name\n", which is useful for visual map queues.
kick <player> <optional reason> Kicks player with the given name. kickban <player> <reason> <optional int durationOfDays> Locally bans player with the given name. Locally bans player with the given name, by SteamID, with reason of ban, banner's username and start/end dates of the ban. The granularity of duration might change from days (maybe just days as a float?), but in the actual .ini it can be for any duration up to minutes. movemap <number> <bool up> Moves map numbered <number> in the queue. If up == true, it moves towards 0 (up), while false moves it down towards the last map. nextmap Rotates map to the next in the queue. Can be used following the addmap command to insert and rotate to a new map. getplayerlist <optional bool annotated = true> Reports the current list of players. Pass annotated = false to get back an easier to parse list which returns newline delimited players following the message "playerlist:" of form: "<steamid> <score> <kills> <death> <ping> <playername>\n".
removemap <number> Removes map <number> from the map queue. Map 0 cannot be removed, as it is the current map. restartmap Restarts the current map. setmotd Changes the message of the day. Will also write the new message of the day to DedicatedServer.ini.
Ravaged RCon Client Edit
The text-based client that will be made available along with Ravaged has a set of commands used for managing connections that are also listed here for convenience.
connect <URL> <optional username> <optional password> Connects to a Ravaged server. Connects remotely to a ravaged server in order to execute Unreal commands. If no port is given, the default port of 13550 is used. Optionally, a username and password pair will log you in as a user. Only giving a password will result in an attempted login as the super user. No password is assumed to be a blank password (not recommended). Any URL, IP/Port combination should be acceptable. info Displays current connection information.
login <password> Logs in to a Ravage server once connected. This command can be used to authenticate if the initial authentication fails. It will probably be removed soon in favour of a more robust authentication system. help <optional command> Queries help system. If a command name is given, more information on that command will be displayed. Uses this documentation.
Features Currently Pending Edit
To cut down requests for new features, here is a list of things currently on my "todo" list:
- Admin broadcasts