https://github.com/northrealm/ngx_stream_minecraft_forward_module
Nginx module to proxy Minecraft Java servers
https://github.com/northrealm/ngx_stream_minecraft_forward_module
minecraft minecraft-proxy minecraft-server nginx nginx-module nginx-proxy nginx-reverse-proxy nginx-stream
Last synced: 3 months ago
JSON representation
Nginx module to proxy Minecraft Java servers
- Host: GitHub
- URL: https://github.com/northrealm/ngx_stream_minecraft_forward_module
- Owner: NorthRealm
- License: wtfpl
- Created: 2024-01-06T15:42:10.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-06-21T13:45:31.000Z (5 months ago)
- Last Synced: 2025-06-21T14:36:37.806Z (5 months ago)
- Topics: minecraft, minecraft-proxy, minecraft-server, nginx, nginx-module, nginx-proxy, nginx-reverse-proxy, nginx-stream
- Language: C++
- Homepage:
- Size: 159 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Nginx Stream Module ngx_stream_minecraft_forward_module
`ngx_stream_minecraft_forward_module` module is an Nginx module that can sieve Minecraft Java game traffic.
## Features
- Sieve and replace client-provided server hostname.
> [!IMPORTANT]
> - This module relies on [stream module](https://nginx.org/en/docs/stream/ngx_stream_core_module.html).
> - Only suitable for Minecraft Java protocol since Netty rewrite.
> - This module uses C++11. Add `--with-ld-opt="-lstdc++"` whilst compiling Nginx.
## Directives
- Syntax: `minecraft_server_forward off|on;`
Default: `minecraft_server_forward off;`
Context: server
Indicate a server block that proxies Minecraft Java tcp connections.
> [!CAUTION]
> Set to `on` only when upstream server is a Minecraft Java server, otherwise proxy won't function properly.
- Syntax: `minecraft_server_hostname hostname.to.be.replaced new.hostname;`
Default: None
Context: stream, server
When a client starts logging process, replace client-provided server hostname with a new hostname before proxying to remote Minecraft server.
> [!TIP]
> Due to differences in Minecraft Java protocol specification, should there be a SRV record `_minecraft._tcp.a.domain.for.example.com` that points to `another.domain.for.example.com`, consider define two replacements:
```
minecraft_server_hostname a.domain.for.example.com new.domain.for.example.com;
minecraft_server_hostname another.domain.for.example.com new.domain.for.example.com;
```
- Syntax: `minecraft_server_hostname_hash_max_size size;`
Default: `minecraft_server_hostname_hash_max_size 512;`
Context: stream, server
Set the maximum size of hash tables used by `minecraft_server_hostname` directive.
- Syntax: `minecraft_server_hostname_hash_bucket_size size;`
Default: `minecraft_server_hostname_hash_bucket_size 64;`
Context: stream, server
Set the bucket size for hash tables used by `minecraft_server_hostname` directive.
- Syntax: `minecraft_server_hostname_disconnect_on_nomatch off|on;`
Default: `minecraft_server_hostname_disconnect_on_nomatch off;`
Context: stream, server
Close connection if client-provided server hostname matches no replacement.
- Syntax: `minecraft_server_hostname_replace_on_ping off|on;`
Default: `minecraft_server_hostname_replace_on_ping on;`
Context: stream, server
When a client starts pinging, replace client-provided server hostname with a new hostname before proxying to remote Minecraft server. This option is recommended pinging servers hidden behind third-party services (e.g. TCPShield.com) that impose inspection on pinging packets.