# Acron

Acron meas *another rcon*. It is a WebSocket based rcon replacement with advanced features.

## Problems with rcon

* [Security] No authorization: All rcon clients are hardcoded with OP level 4 in the Minecraft source code. There are also no permission control, giving any faulty or even malicious client full control over the server.
* [Security] Simple authentication: All clients are sharing the same secret, making the secret easy to leak and granting attackers unlimited access to the server.
* [Efficiency] Rcon executes commands in a blocking manner. The server joins the main thread and waits for the command to complete before reading more from the client.
* [Limit] Rcon does not support pushing server messages to the client. This includes player messages, death messages, server logs, etc. A lot of use cases need such information.
* [Limit] Rcon has a fixed command length. Although it is not likely for a command to exceed this limit, it still restricts the use cases of rcon.
* [Limit] Rcon commands are hard coded to run at the spawn point of Overworld. It is impossible to execute commands in other positions or dimensions if the command does not support so itself.
* [Limit] No Unix domain socket support. Unix domain socket is a great way to do localhost IPC and controlling access using Unix user and groups. However, rcon is forced to listen on a TCP address and port.
* [Performance] Minecraft creates a new thread per connection accepted, and it blocks for input. Using a thread pool or async IO is much more performant.
* [Security] Rcon does not support TLS. It is just using plain TCP.

To solve these problems, a better approach is to rewrite rcon.

## Problems Acron solved

* [Security] Authentication and Authorization: With Acron, administrators are able to specify unique tokens for each client, and it is also possible to easily define the commands clients are permitted to execute using regex rules.
* [Efficiency] Acron uses a command queue to schedule commands. Clients need to specify an ID, and Acron will return the result with the same ID once the command is done. In the meantime, clients can enqueue more commands.
* [Limit] Server push: Acron will send player messages, death messages of living entities, player join / leave messages, and server lag warnings to the client. Acron also classifies the messages, so clients do not need to parse them manually.
* [Limit] Command length: Acron does not limit command length.
* [Limit] Locations and other configurations: Acron clients can specify the world, position, rotation, and name for each command they execute, or they can set a per-connection default.
* [Limit] **Unix domain socket: Sorry, currently Acron does not support Unix domain socket either. Unix domain sockets will be available in later versions.**
* [Performance] Acron uses Netty, which is built-in in Minecraft, to performance async IO using thread pools.
* [Security] TLS: Although Acron does not support TLS itself, it is using WebSocket, which gives the choice of adding a reverse proxy with TLS support.

## Technical Specification

Acron is based on:

1. WebSocket: Instead of designing a Layer 5 protocol, Acron chooses WebSocket to make the implementation of server and client easier. Moreover, WebSocket has a wide range of support compared to plain TCP sockets.
2. JSON: Although JSON is slow and schema-less, it comes with no addition dependencies as a Minecraft mod because Minecraft depends on GSON internally.
3. Netty: The WebSocket server is based on Netty because it is built-in in the Minecraft server.
4. GSON: Acron uses GSON to deserialize / serialize JSON since GSON is also a Minecraft dependency.

## Documentation Notes

For each request JSON parameter, the format is:

`(JSON path)` (type, limit, default value or required): Description.

For each response JSON parameter, the format is:

`(JSON path)` (type, limit, always present or conditions): Description.

## Installing the mod

To build this mod, you need to run `gradle build` inside `mod/`, and the output JAR will be at `build/libs/acron-x.x.jar`.

Then, copy it to the `mods/` folder in your Minecraft server working directory.

Finally, edit `<Minecraft server working directory>/config/acron.json` as follows:

```json
{
  "port": 25575,
  "listen": "127.0.0.1",
  "native_transport": false,
  "clients": [
    {
      "id": "client1",
      "token": "61fe277334300860dbcf8320ad866788e08b7dd930f9f04a3dc4db5e7f6521e2",
      "policy_mode": "deny",
      "rules": [
        {
          "regex": "^list$",
          "action": "allow",
          "display": false
        },
        {
          "regex": "^kick .*$",
          "action": "allow",
          "display": true
        },
        {
          "regex": "^stop .*$",
          "action": "deny"
        }
      ]
    }
  ]
}
```

Finally, start the server.

> **Notes**
> 
> JSON is not the first choice for configuration files because it takes too much manual labor to write it correctly.
> However, since Minecraft server bundles GSON, it is redundant for this mod to depend on another configuration parsing library
> for the sole purpose of loading configurations.
> 
> To save users' time, we are planning to release a online GUI configuration editor.

## Configuration

### Server configuration

JSON Path: `.`

* `port` (int, [0, 65535], 25575): Port to listen.
* `address` (string, IPv4 or IPv6 address, "127.0.0.1"): Address to listen.
* `native_transport` (boolean, true / false, false): Use Epoll when available.

### Client configuration

JSON Path: `.clients.[]`

* `id` (string, any, required): The ID of the client. The client needs to specify it in the connection string.
* `token` (string, SHA256, required): The SHA256 of the token. The token is generated by the administrator.
* `policy_mode` (enum, deny / allow, deny): The default rule if its command does not mach any rules in the `rules` array.
* `rules.[]regex` (string, regex, required): The regex to match the command.
* `rules.[]action` (enum, deny / allow, required): The action for this rule.
* `rules.[]display` (boolean, true / false, false): Display the output of the command on chat.

## Client Management

Each client has a unique ID (like a username), and it has a token used to authenticate itself. The administrator needs to add the client to the configuration with an ID (administrator chosen) and a token (administrator generated).

When the client connects, it needs to supply the ID - token pair, or Acron will return HTTP 401 in the WebSocket handshake request.

Each client has some rules and a default policy mode. When it executes a command, Acron will match the command string against the rules, 
from the first to the last, until a match is found, and the corresponding action in the rule is taken.
It Acron cannot match any rules, it will take the default policy mode.

Auditing is also available. Users may specify the `display` parameter in rules to make the command output to both server logs and chat.

> **Note**
> 
> Internally, the command will run at OP level 4 (the highest level) after
> passing rules check.

> **Note**
> 
> Minecraft accepts commands both starting with `/` or not (but
> not commands starting with two or more `/`). However, Acron will remove 
> the leading slash if present when matching against rules.

> **Note**
> 
> If the format of `.port`, `.listen` or `.native_transport` is wrong, Acron will prevent
> Minecraft server from starting up.
> 
> However, if the format of anything in `.clients` is wrong, it will print a warning and skip
> that part because administrators can reload clients during runtime.

### Configuration reloading

Any administrator with OP level 4 can execute the command `/acron rule update`.
It will instantly read the configuration file
and apply the changes to clients and rules.

However, this does not affect existing connections since authentication happens
during WebSocket handshaking.

Note, listen port and address cannot be changed during runtime.

> **Note**
> 
> Similarly, if Acron finds an error in `.clients` after running `/acron rule update`,
> it will print a warning and skip the whole new configuration file until the
> error is fixed.

## Using the client

As Acron has an open protocol, it is easy to implement the client-side service on your own. However, Acron officially
has [libacron](client/libacron), a client library written in C.

Acron also provides a cli tool: [acronc(1)](client/acronc) for administrators.

## Contributing

As a community project, I highly appreciate any help to this project. If you have any suggestions or
patches, or if you find a bug or security issue, please send them to `yuuta@yuuta.moe`, and mention Acron in
the email subject. If you are sending a patch, please read [Contributing Guide](CONTRIBUTING.md).

## License

Acron is licensed under GPL-2.0-only except [libacron](client/libacron) is licensed under LGPL-2.1-only.