path: root/README.md

# 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.

## Installation

To build this mod, you need to run `gradle build`, 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,
  "address": "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.

## Client API

Acron uses polymorphic JSONs when communicating with clients. Therefore, each JSON
has to contain a valid `type` parameter indicating its type:

```json
{
  "type": "cmd",
  "id": 1,
  "cmd": "list"
}
```

### Request ordering

To work in a full-duplex environment, each command can specify a `id` parameter. Acron will
return any results or errors with the same ID.

Sample request:

```json
{
  "type": "cmd",
  "id": 1,
  "cmd": "list"
}
```

The parameter `id` can be any integer, but it is the client developer's responsibility to
make it a unique value, so he or she can identify it.

Parameter `id` defaults to -1.

In response, any non-server-push responses (i. e. messages) will include the same `id` parameter:

```json
{
  "type": "cmd_result",
  "id": 1,
  "result": 0,
  "success": true
}
```

If the server fails to parse the request and returns an error, it will report the default ID `-2`.

### Error Handling

Error handling: Besides from the handshake request, which will send errors using HTTP status
codes, all faulty WebSocket requests will receive error in the following format:

```json
{
  "type": "error",
  "id": 1,
  "code": 500,
  "message": "Error message. Not machine-readable."
}
```

Parameters:

* `.code` (int, HTTP status codes, always present): The machine-readable error code (e. g. 400 for Bad Request).
* `.message` (string, any, always present): The human-readable error message.

Global error codes:

* 400: The request is invalid.
* 500: The server encountered an unknown error.

**`.type` and `.id` are included in every request / response, except for further noticed. Thus,
this document excludes them from the parameter lists.**

### Handshaking

Clients need to use the following connection string when connecting to the Acron server:

```
ws://host:port/ws?id=client_id&token=client_token&version=0
```

*A better approach for specifying the authentication parameters is using HTTP headers, 
but the JavaScript client does not allow so. To extend compatibility, Acron forces
all users to use HTTP query parameters to supply information.*

Parameters:

* `id` (required): Client ID set by the administrator.
* `token` (required): Client token set by the administrator.
* `version` (default: 0): API version. Only 0 is accepted at this time.

Responses:

* HTTP 400 (Bad Request): If either `id` or `token` is missing, or `version` is not 0.
* HTTP 401 (Unauthorized): If either `id` is not found or `token` does not match the record.
* HTTP 101 (Switching Protocols): The handshake is complete, and the server is upgrading to
WebSocket.

### Setting Configuration

This allows clients to set a per-connection default configuration to execute commands.

Clients can override the configuration temporarily when executing commands.

Request:
```json
{
  "type": "set_config",
  "id": 1,
  "world": "overworld",
  "pos": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.0
  },
  "rot": {
    "x": 0.0,
    "y": 0.0
  },
  "name": ""
}
```

Parameters:

* `.world` (enum, overworld / nether / end, overworld): The world to run commands in.
* `.pos` (vec3d, *see below*, spawn point of `.world`): The position to run commands at.
  * `.x` (double, any within border limit, 0.0): X
  * `.y` (double, any within border limit, 0.0): Y
  * `.z` (double, any within border limit, 0.0): Z
* `.rot` (vec2f, *see below*, `0.0 0.0`): Rotation.
  * `.x` (float, ?, 0.0): X
  * `.z` (float, ?, 0.0): Z
* `.name` (string, any, random): Name when running commands.

When the client connects, Acron will set the configuration to default values.

Successful response:

```json
{
  "type": "ok"
}
```

This shows that the configuration update is successful.

### Executing Commands

The main goal of Acron is to allow clients to run commands. A client can send
any commands, and Acron will schedule them in the background.

Request:

```json
{
  "type": "cmd",
  "id": 1,
  "cmd": "list",
  "config": {
    
  }
}
```

Parameters:

* `.cmd` (string, any valid command, required): The command to execute. It may or may not begin with `/`.
* `.config` (set_config, *see above*, current connection default configuration): Temporary configuration 
when running this command. It is the same `set_config` object in the above section, but `type` and `id` 
must not be supplied.

Successful response:

```json
{
  "type": "ok"
}
```

This shows that the command is scheduled.

If the connection breaks before it is done, it is still executed without any output to the connection.

Possible failures:

* 403: This client is not allowed to execute this command. (Configured by rules)

**Command output:**

When the command prints a line, Acron will send the following response:

```json
{
  "type": "cmd_out",
  "id": 1,
  "sender": "UUID",
  "out": "..."
}
```

Parameters:

* `.sender` (UUID, any UUID, always present): Sender UUID.
* `.out` (string, any, always present): Output.

**Command result:**

When the command finishes without issues (?), Acron will send the following response:

```json
{
  "type": "cmd_result",
  "id": 1,
  "result": 0,
  "success": true
}
```

All parameters always present.

> **Note**
> 
> The result completely depends on Minecraft server's response.
> It may not be reliable, and the values of `.result` and `.success` are
> undocumented.

### Receiving Messages

Another major part of Acron is to allow clients receive events from the server.

Every event will have a pre-defined `type` with other custom parameters. Parameter `id` will not
present in events.

> **Contributor Guide**
> 
> Internally, all message Acron sends to clients are called events, including
> command results.

#### Player joined

Response:

```json
{
  "type": "join",
  "player": {
    "name": "",
    "uuid": "",
    "pos": {
      "x": 0.0,
      "y": 0.0,
      "z": 0.0
    },
    "world": "end"
  }
}
```

Parameters:

* `.player` (entity, see below, always present): The player.
  * `.name` (string, any valid Minecraft username, always present): Username.
  * `.uuid` (uuid, UUID, always present): UUID.
  * `.pos` (vec3d, see below, always present): The position he or she joins.
    * `.x` (double, any within border limit, 0.0): X
    * `.y` (double, any within border limit, 0.0): Y
    * `.z` (double, any within border limit, 0.0): Z
  * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension
he or she joins.

#### Player Disconnected

Response:

```json
{
  "type": "disconnect",
  "player": {
    "name": "",
    "uuid": "",
    "pos": {
      "x": 0.0,
      "y": 0.0,
      "z": 0.0
    },
    "world": "end"
  },
  "reason": ""
}
```

Parameters:

* `.player` (entity, see below, null only when the server cannot verify the user): The player.
  * `.name` (string, any valid Minecraft username, always present): Username.
  * `.uuid` (uuid, UUID, always present): UUID.
  * `.pos` (vec3d, see below, always present): The position he or she leaves.
    * `.x` (double, any within border limit, 0.0): X
    * `.y` (double, any within border limit, 0.0): Y
    * `.z` (double, any within border limit, 0.0): Z
  * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension
    he or she leaves.
* `.reason` (string, any valid disconnect reason, always present): Disconnect reason.

#### Player Message

Response:

```json
{
  "type": "message",
  "player": {
    "name": "",
    "uuid": "",
    "pos": {
      "x": 0.0,
      "y": 0.0,
      "z": 0.0
    },
    "world": "end"
  },
  "text": ""
}
```

Parameters:

* `.player` (entity, see below, always present): The player.
  * `.name` (string, any valid Minecraft username, always present): Username.
  * `.uuid` (uuid, UUID, always present): UUID.
  * `.pos` (vec3d, see below, always present): The position he or she sends the message.
    * `.x` (double, any within border limit, 0.0): X
    * `.y` (double, any within border limit, 0.0): Y
    * `.z` (double, any within border limit, 0.0): Z
  * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension
he or she sends the message.
* `.text` (string, any valid Minecraft message, always present): The message.

#### Entity Death

Response:

```json
{
  "type": "death",
  "entity": {
    "name": "",
    "uuid": "",
    "pos": {
      "x": 0.0,
      "y": 0.0,
      "z": 0.0
    },
    "world": "end"
  },
  "message": ""
}
```

Parameters:

* `.entity` (entity, see below, always present): The entity.
  * `.name` (string, any, always present): Default name or custom name of the entity.
  * `.uuid` (uuid, UUID, always present): UUID.
  * `.pos` (vec3d, see below, always present): The position of the entity when died.
    * `.x` (double, any within border limit, 0.0): X
    * `.y` (double, any within border limit, 0.0): Y
    * `.z` (double, any within border limit, 0.0): Z
  * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension
of the entity when died.
* `.message` (string, any valid death message, always present): The user-readable death message.

> **Roadmap**
> 
> Parsing the death message and sending a more machine-readable message is on the roadmap.

#### Server Lagging

Acron will send this event when the server prints 
`Can't keep up! Is the server overloaded? Running 4313ms or 86 ticks behind` to the standard output.

Response:

```json
{
  "type": "lagging",
  "ms": 100,
  "ticks": 1000
}
```

Parameters:

* `.ms` (long, >= 0, always present): Running {}ms behind.
* `.ticks` (long, >= 0, always present): Running {} ticks behind.

## 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 include `[PATCH]` in the subject as well. Thank you very much.

## License

Acron is licensed under GPL-2.0-only except libac is licensed under LGPL-2.1-only.