Skip to content

Commit 1a061f9

Browse files
KamesutaKamesuta
committed
Add README and LICENSE
1 parent 9d778ab commit 1a061f9

File tree

3 files changed

+179
-0
lines changed

3 files changed

+179
-0
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Kamesuta
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# BungeeViaProxy
2+
3+
## Overview
4+
5+
**BungeeViaProxy** is a BungeeCord plugin designed to address compatibility issues when using [ViaProxy](https://github.com/ViaVersion/ViaProxy) with [BungeeCord](https://github.com/SpigotMC/BungeeCord).
6+
This plugin is especially useful for networks with multiple backend servers running different Minecraft versions, where you want to minimize the overhead of maintaining ViaVersion plugins on each backend server.
7+
8+
ViaBungee support was discontinued as of Minecraft 1.20.2, making it necessary to migrate to ViaProxy for compatibility with newer versions of the game.
9+
This guide is valuable for those who wish to continue using BungeeCord with the latest Minecraft versions while avoiding the burden of individually updating ViaVersion on each backend server.
10+
11+
By leveraging ViaProxy with wildcard-domain-handling, a single ViaProxy instance can support multiple backend servers, simplifying updates and reducing resource usage.
12+
13+
## Table of Contents
14+
- [Use Case](#use-case)
15+
- [How It Works](#how-it-works)
16+
- [Features](#features)
17+
- [Installation](#installation)
18+
- [Configuration](#configuration)
19+
- [Example Configuration](#example-configuration)
20+
21+
## Use Case
22+
23+
BungeeViaProxy is ideal for:
24+
25+
- Networks using BungeeCord to manage multiple backend servers running different Minecraft versions.
26+
- Administrators who want to maintain compatibility with the latest Minecraft versions using ViaProxy and Bungeecord.
27+
- Reducing the operational overhead of updating ViaVersion plugins on individual backend servers by centralizing version translation via ViaProxy.
28+
29+
**Important:** When using ViaProxy in such a setup, it must be placed between BungeeCord and the backend servers. Additionally, in ViaProxy's configuration:
30+
31+
- `proxy-online-mode` must be disabled.
32+
- `auth-method` must be set to `NONE`.
33+
- `wildcard-domain-handling` must be set to `PUBLIC`.
34+
- `target-address` is ignored (anything is OK) while using `wildcard-domain-handling`.
35+
36+
## How It Works
37+
38+
Normally, each backend server would require a separate ViaProxy instance.
39+
However, this can lead to increased memory consumption and additional update efforts.
40+
41+
To address this, ViaProxy supports the `wildcard-domain-handling` feature, allowing a single ViaProxy instance to handle connections to multiple backend servers.
42+
This is achieved by using a specific address format for each backend server:
43+
44+
```
45+
address.<backend-ip>.port.<backend-port>.version.<backend-version>.viaproxy.<viaproxy-ip>.nip.io:<viaproxy-port>
46+
```
47+
48+
These addresses can then be listed in the `config.yml` of BungeeCord, enabling seamless connection management through a single ViaProxy instance.
49+
However, this setup introduces certain challenges, which BungeeViaProxy resolves.
50+
51+
## Features
52+
53+
1. **Correct Hostname Forwarding:**
54+
When `wildcard-domain-handling: PUBLIC` is enabled in ViaProxy, it may fail to retrieve the hostname specified in BungeeCord's configuration, preventing proper server routing. BungeeViaProxy ensures that any address containing `.viaproxy.` is forwarded correctly to the backend server.
55+
56+
2. **Avoiding Duplicate Server Errors:**
57+
BungeeCord treats servers with different hostnames as identical if they resolve to the same IP address, resulting in the error: `You are already connected to this server!`. BungeeViaProxy resolves this by using unresolved `InetSocketAddress` objects, ensuring unique identification for servers with different hostnames.
58+
59+
## Installation
60+
61+
1. Download the latest release of BungeeViaProxy.
62+
2. Place the plugin `.jar` file into your BungeeCord `plugins` directory.
63+
3. Restart your BungeeCord server.
64+
65+
## Configuration
66+
67+
No additional configuration is required. BungeeViaProxy automatically handles `.viaproxy.` addresses and ensures proper server routing.
68+
69+
## Example Configuration
70+
71+
![Network Diagram](./assets/diagram.png)
72+
73+
Here is an example of how to configure BungeeCord to work with ViaProxy using wildcard-domain-handling
74+
75+
Assuming the following setup:
76+
| Server | IP:Port | Minecraft Version |
77+
|------------------|---------------------|-------------------|
78+
| BungeeCord | 127.0.0.1:25565 | N/A |
79+
| ViaProxy | 127.0.0.1:25566 | N/A |
80+
| Backend Server 1 | 127.0.0.1:3001 | 1.20.4 |
81+
| Backend Server 2 | 127.0.0.1:3002 | 1.16.5 |
82+
| Backend Server 3 | 127.0.0.1:3003 | 1.21 |
83+
84+
BungeeCord `config.yml` (only relevant options are shown):
85+
```yaml
86+
online_mode: true
87+
servers:
88+
server1:
89+
# ViaProxy address format: address.<backend-ip>.port.<backend-port>.version.<backend-version>.viaproxy.<viaproxy-ip>.nip.io:<viaproxy-port>
90+
address: address.127.0.0.1.port.3001.version.1.20.4.viaproxy.127.0.0.1.nip.io:25566
91+
motd: '&1Example Server 1'
92+
restricted: false
93+
server2:
94+
# In this example,
95+
# Backend server IP: 127.0.0.1:25566
96+
# ViaProxy IP: 127.0.0.1:3002
97+
address: address.127.0.0.1.port.3002.version.1.16.5.viaproxy.127.0.0.1.nip.io:25566
98+
motd: '&1Example Server 1'
99+
restricted: false
100+
server3:
101+
# Version can be omitted if not needed (version is automatically detected by ViaProxy)
102+
address: address.127.0.0.1.port.3003.viaproxy.127.0.0.1.nip.io:25566
103+
motd: '&1Example Server 3 (".version.1.20.4" can be omitted)'
104+
restricted: false
105+
listeners:
106+
- host: 0.0.0.0:25565
107+
prevent_proxy_connections: false
108+
ip_forward: true
109+
```
110+
111+
ViaProxy `config.yml` (only relevant options are shown):
112+
```yaml
113+
# ViaProxy configuration file
114+
115+
# The address ViaProxy should listen for connections.
116+
# This option is not reloadable.
117+
bind-address: 0.0.0.0:25566
118+
119+
# The address of the server ViaProxy should connect to.
120+
target-address: AnythingIsOK.ThisFieldIsIgnored.example.com
121+
122+
# Proxy Online Mode allows you to see skins on online mode servers and use the signed chat features.
123+
# Enabling Proxy Online Mode requires your client to have a valid minecraft account.
124+
proxy-online-mode: false
125+
126+
# The authentication method to use for joining the target server.
127+
# none: No authentication (Offline mode)
128+
# openauthmod: Requires the OpenAuthMod client mod (https://modrinth.com/mod/openauthmod)
129+
# account: Use an account for joining the target server. (Has to be configured in ViaProxy GUI)
130+
auth-method: NONE
131+
132+
# Allows clients to specify a target server and version using wildcard domains.
133+
# none: No wildcard domain handling.
134+
# public: Public wildcard domain handling. Intended for usage by external clients. (Example: address.<address>.port.<port>.version.<version>.viaproxy.127.0.0.1.nip.io (version is optional))
135+
# internal: Internal wildcard domain handling. Intended for local usage by custom clients. (Example: original-handshake-address\7address:port\7version\7classic-mppass)
136+
wildcard-domain-handling: PUBLIC
137+
```
138+
139+
Backend Server `server.properties` (only relevant options are shown):
140+
```properties
141+
server-port=3001
142+
online-mode=false
143+
```
144+
145+
Backend Server `spigot.yml` (only relevant options are shown):
146+
```yaml
147+
settings:
148+
bungeecord: true
149+
```
150+
151+
Note:
152+
- No ViaVersion plugin is required on the backend servers. (Because version translation is handled by ViaProxy)
153+
- Do not use [ViaProxyAuthHook](https://github.com/ViaVersionAddons/ViaProxyAuthHook) as ViaProxy is placed between BungeeCord and the backend servers.
154+
155+
## License
156+
157+
BungeeViaProxy is open-source and licensed under the MIT License. Contributions and feedback are welcome.
158+

‎assets/diagram.png‎

279 KB
Loading

0 commit comments

Comments
 (0)