JSON-Manage
As a server owner myself, I know how difficult it can be when there are sever issues while you're not at your computer, or how difficult it is to manage a server from a mobile device (i.e. impossible). I decided to write this mod up as a way to help ease some of the pain of managing a server on the go. Through a JSON API, any end client can connect to the server and preform some of the day to day management tasks that normally would require something more arduous like ssh+screen or a VNC connection to achieve.
My hope is that this mod will help all the server owners out there alleviate some of the stress we've all felt before when something's gone wrong with the server and we just left home to go shopping.
Documentation:
No API is complete without documentation, and this one is certainly no different. The JSON format is as follows:
{"command":"[command]","args":{[args]}}
The args field is where data is passed to/from the server backend as well as return codes and additional information.
Currently Supported Commands
- Sending a message to a specific player (SINGLE_MESSAGE)
- Broadcasting a message to the entire server (BROADCAST_MESSAGE)
- Getting a list of currently connected players (GET_PLAYERS)
- Get memory usage statistics from the server (USAGE)
- Get TPS data from all dimensions (GET_TPS)
- Get a list of installed mods (GET_MODS)
- Stop the server (STOP_SERVER)
- Start the server (START_SERVER)
- Restart the server (RESTART_SERVER)
- Get the command line arguments (GET_CMD_ARGS)
- Set the command line arguments (SET_CMD_ARGS)
- Set the initial stack size (-Xms option) (SET_INIT_STACK_SIZE)
- Set the maximum stack size (-Xmx option) (SET_MAX_STACK_SIZE)
- Get Minecraft property from server.properties (GET_MC_PROP)
- Set Minecraft property from server.properties (SET_MC_PROP)
Table 1: English descriptions of commands and arguments
| Command | English Description | Arguments | Returns |
|---|---|---|---|
| USAGE | Returns maximum available memory, currently allocated memory, and free memory for the current Java VM in bytes | None | Three strings: "maxMemory", "allocatedMemory", and "freeMemory" |
| GET_PLAYERS | Returns a list of currently connected players | None | List of strings: "players" |
| STOP_SERVER | Stops the server | None | Success/Failure : "ret_code" |
| START_SERVER | Starts the server | None | Success/Failure : "ret_code" |
| RESTART_SERVER | Restarts the server | None | Success/Failure : "ret_code" |
| SINGLE_MESSAGE | Sends a message to a specific player | "to" and "msg" | Success/Failure : "ret_code" |
| BROADCAST_MESSAGE | Broadcasts a message to the whole server | "msg" | Success/Failure : "ret_code" |
| GET_MODS | Returns the list of currently installed mods | None | List of strings: "mods" |
| GET_TPS | Returns TPS data for all loaded dimensions | None | Map of ints to strings: "tps_data" |
| GET_CMD_ARGS | Returns current command line arguments | None | String: "cmd_args" |
| SET_CMD_ARGS | Sets command line arguments (does not take effect until after server restart) | "cmd_args" | Success/Failure : "ret_code" |
| SET_MAX_STACK_SIZE | Sets the maximum stack size (-Xmx VM arg, does not take effect until after server restart) | "max_stack_size" (Value is string to go after -Xmx, ex: "max_stack_size":"1024M") | Success/Failure : "ret_code" |
| SET_INIT_STACK_SIZE | Sets the initial stack size (-Xms VM arg, does not take effect until after server restart) | "init_stack_size" (Value is string to go after -Xms, ex: "max_stack_size":"1024M") | Success/Failure : "ret_code" |
| GET_MC_PROP | Gets a Minecraft property from the server.properties file | "mc_property" | String: "property_value" |
| SET_MC_PROP | Sets a Minecraft property (does not take effect until after server restart) | "mc_property" and "property_value" | Success/Failure : "ret_code" |
Table 2: Sample JSON for currently supported commands
| Command | Sample Input | Sample Return |
|---|---|---|
| USAGE | {"command":"USAGE"} | {"command":"USAGE","args":{"ret_code":"SUCCESS"}} |
| GET_PLAYERS | {"command":"GET_PLAYERS"} | {"command":"GET_PLAYERS","args":{"players":["conman2305"],"ret_code":"SUCCESS"}} |
| STOP_SERVER | {"command":"STOP_SERVER"} | {"command":"STOP_SERVER","args":{"ret_code":"SUCCESS"}} |
| START_SERVER | {"command":"START_SERVER"} | {"command":"START_SERVER","args":{"ret_code":"SUCCESS"}} |
| RESTART_SERVER | {"command":"RESTART_SERVER"} | {"command":"RESTART_SERVER"} |
| SINGLE_MESSAGE | {"command":"SINGLE_MESSAGE","args":{"to":"conman2305","message":"Hello World!"}} | {"command":"SINGLE_MESSAGE","args":{"ret_code":"SUCCESS"}} |
| BROADCAST_MESSAGE | {"command":"BROADCAST_MESSAGE","args":{"message":"Hello World!"}} | {"command":"BROADCAST_MESSAGE","args":{"ret_code":"SUCCESS"}} |
| GET_MODS | {"command":"GET_MODS"} | {"command":"GET_MODS","args":{"mods":["Minecraft Coder Pack","Forge Mod Loader","Minecraft Forge","JSONManage"],"ret_code":"SUCCESS"}} |
| GET_TPS | {"command":"GET_TPS"} | {"command":"GET_TPS","args":{"tps_data":{"0":"2.565826812878905","1":"20.0","-1":"20.0"},"ret_code":"SUCCESS"}} |
| GET_CMD_ARGS | {"command":"GET_CMD_ARGS"} | {"command":"GET_CMD_ARGS","args":{"ret_code":"SUCCESS","cmd_args":"-Xincgc -Dfml.ignoreInvalidMinecraftCertificates\u003dtrue "}} |
| SET_CMD_ARGS | {"command":"SET_CMD_ARGS","args":{"cmd_args":"-Xmx512M -Xms512M -Xincgc -Dfml.ignoreInvalidMinecraftCertificates\u003dtrue"}} | {"command":"SET_CMD_ARGS","args":{"ret_code":"SUCCESS"}} |
| SET_MAX_STACK_SIZE | {"command":"SET_MAX_STACK_SIZE","args":{"max_stack_size":"1024M"}} | {"command":"SET_MAX_STACK_SIZE","args":{"ret_code":"SUCCESS"}} |
| SET_INIT_STACK_SIZE | {"command":"SET_INIT_STACK_SIZE","args":{"init_stack_size":"1024M"}} | {"command":"SET_INIT_STACK_SIZE","args":{"ret_code":"SUCCESS"}} |
| GET_MC_PROP | {"command":"GET_MC_PROP","args":{"mc_property":"server-port"}} | {"command":"GET_MC_PROP","args":{"property_value":"25565","ret_code":"SUCCESS"}} |
| SET_MC_PROP | {"command":"SET_MC_PROP","args":{"mc_property":"server-port", "property_value":"25566"}} | {"command":"SET_MC_PROP","args":{"ret_code":"SUCCESS"}} |
More Information:
This is an open source mod, and is available on github at: https://github.com/conman2305/JSON-Manage
Any issues and feature requests should also be made on that same GitHub.
The JSON-Manage Team
