122 lines
3.8 KiB
Diff
122 lines
3.8 KiB
Diff
--- /dev/null
|
|
+++ b/docs/configuration/inbound/minecraft.md
|
|
@@ -0,0 +1,118 @@
|
|
+### Structure
|
|
+
|
|
+```json
|
|
+{
|
|
+ "type": "minecraft",
|
|
+ "tag": "mc-in",
|
|
+
|
|
+ ... // Listen Fields
|
|
+
|
|
+ "users": [
|
|
+ {
|
|
+ "username": "Steve",
|
|
+ "password": "my-secret-password"
|
|
+ }
|
|
+ ],
|
|
+ "status": {
|
|
+ "forward": false,
|
|
+ "version": {
|
|
+ "name": "1.20.4",
|
|
+ "protocol": 765
|
|
+ },
|
|
+ "description": "A Minecraft Server",
|
|
+ "players": {
|
|
+ "max": 20,
|
|
+ "online": 1,
|
|
+ "sample": [
|
|
+ {
|
|
+ "name": "Notch",
|
|
+ "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
|
|
+ }
|
|
+ ]
|
|
+ },
|
|
+ "favicon": "data:image/png;base64,<data>",
|
|
+ "enforces_secure_chat": false
|
|
+ },
|
|
+ "fallback": {
|
|
+ "server": "mc.example.com",
|
|
+ "server_port": 25565,
|
|
+ "tag": "mc-fallback"
|
|
+ }
|
|
+}
|
|
+```
|
|
+
|
|
+### Listen Fields
|
|
+
|
|
+See [Listen Fields](/configuration/shared/listen/) for details.
|
|
+
|
|
+### Fields
|
|
+
|
|
+#### users
|
|
+
|
|
+List of users allowed to authenticate through the proxy. Each entry has a `username` and `password`.
|
|
+
|
|
+Connections from usernames not in this list are forwarded to the `fallback` server (if configured), allowing real Minecraft players to connect transparently.
|
|
+
|
|
+#### status
|
|
+
|
|
+Controls the server list ping response shown to Minecraft clients.
|
|
+
|
|
+##### status.forward
|
|
+
|
|
+If `true`, status pings are forwarded to the `fallback` server instead of being answered locally. Requires `fallback` to be configured.
|
|
+
|
|
+##### status.version
|
|
+
|
|
+The version info shown in the server list.
|
|
+
|
|
+- `name`: Version string (e.g. `"1.20.4"`)
|
|
+- `protocol`: Protocol number (e.g. `765`). Defaults to `765` (1.20.4).
|
|
+
|
|
+##### status.description
|
|
+
|
|
+The MOTD shown in the server list. Accepts either a plain string or a [JSON Chat Component](https://wiki.vg/Text_formatting#JSON_text_component) object for rich formatting:
|
|
+
|
|
+```json
|
|
+"description": "A plain text MOTD"
|
|
+```
|
|
+
|
|
+```json
|
|
+"description": {"text": "A colored MOTD", "color": "green"}
|
|
+```
|
|
+
|
|
+##### status.players
|
|
+
|
|
+- `max`: Maximum player count shown.
|
|
+- `online`: Online player count shown.
|
|
+- `sample`: Player list shown on hover. Each entry has `name` and optionally `id` (UUID). If `id` is omitted, a deterministic offline UUID is generated from the name.
|
|
+
|
|
+##### status.favicon
|
|
+
|
|
+Server icon in `data:image/png;base64,<data>` format, shown in the server list.
|
|
+
|
|
+##### status.enforces_secure_chat
|
|
+
|
|
+Whether the server enforces signed chat messages. Passed through to the client as-is.
|
|
+
|
|
+#### fallback
|
|
+
|
|
+If configured, connections from unknown users are proxied transparently to this Minecraft server via the sing-box router.
|
|
+
|
|
+- `server`: Hostname or IP of the fallback server.
|
|
+- `server_port`: Port of the fallback server. Defaults to `25565`.
|
|
+- `tag`: When set, fallback connections are identified by this tag in routing metadata, allowing routing rules to send fallback traffic through a different outbound than proxy traffic.
|
|
+
|
|
+### Description
|
|
+
|
|
+The Minecraft inbound disguises proxy traffic as Minecraft Java Edition protocol traffic.
|
|
+
|
|
+The connection flow is:
|
|
+
|
|
+1. Client connects and sends a Minecraft handshake packet
|
|
+2. If the next state is **Status**: the server responds with a fake server list ping (or forwards to fallback if `status.forward` is enabled)
|
|
+3. If the next state is **Login**: the server performs the standard Minecraft encryption handshake (RSA key exchange + AES/CFB8)
|
|
+4. Authentication is verified by deriving a shared secret from `SHA-256(password + verify_token)[:16]`; real Minecraft clients naturally fail this check and receive an authentic "Failed to verify username!" error
|
|
+5. After login, smux multiplexing runs over the AES/CFB8 encrypted connection
|
|
+6. Each smux stream carries a 1-byte command (`0x01` for TCP, `0x03` for UDP) followed by a SOCKS address header
|
|
+
|
|
+Legacy pre-1.7 pings (`0xFE`) are also handled and return a correctly formatted response.
|