Skip to content

Commit 74176fc

Browse files
zuedevzuedev
committed
Add fail2ban example for Hytale server protection
1 parent b5c4a5a commit 74176fc

5 files changed

Lines changed: 211 additions & 0 deletions

File tree

‎examples/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,10 @@
11
This directory contains ready-to-use examples for deploying the Hytale Server Docker image on multiple platforms.
2+
3+
## Available Examples
4+
5+
| Example | Description |
6+
| ------------------------- | ----------------------------------- |
7+
| [minimal](./minimal/) | Basic docker-compose setup |
8+
| [tailscale](./tailscale/) | VPN-based access via Tailscale |
9+
| [fail2ban](./fail2ban/) | DDoS/abuse protection with fail2ban |
10+
| [k8s](./k8s/) | Kubernetes deployment |

‎examples/fail2ban/README.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Hytale Server with fail2ban Protection
2+
3+
This example demonstrates how to protect your Hytale server from abuse using fail2ban in a sidecar container.
4+
5+
## How It Works
6+
7+
1. **Hytale server** runs and writes logs to a shared volume
8+
2. **fail2ban** monitors those logs for suspicious patterns
9+
3. When an IP exceeds the failure threshold, fail2ban adds an iptables rule to block it
10+
11+
## Requirements
12+
13+
- Docker with host network access (for iptables management)
14+
- Linux host (fail2ban needs iptables access)
15+
- `NET_ADMIN` and `NET_RAW` capabilities
16+
17+
> ⚠️ **Note**: fail2ban with Docker works best on Linux hosts. On Windows/macOS with Docker Desktop, iptables rules won't work as expected due to the VM layer.
18+
19+
## Configuration
20+
21+
### Jail Configuration (`fail2ban/jail.d/hytale.local`)
22+
23+
| Setting | Default | Description |
24+
| ---------- | ------- | ------------------------------------------ |
25+
| `bantime` | 3600 | Ban duration in seconds (1 hour) |
26+
| `findtime` | 600 | Time window to count failures (10 minutes) |
27+
| `maxretry` | 5 | Number of failures before ban |
28+
29+
### Filter Configuration (`fail2ban/filter.d/hytale.local`)
30+
31+
**Important**: The filter regex patterns are templates. You need to customize them based on actual Hytale server log output.
32+
33+
To find the correct patterns:
34+
35+
1. Start your server and check the logs:
36+
37+
```bash
38+
docker compose up -d
39+
docker compose logs -f hytale
40+
```
41+
42+
2. Look for log entries related to:
43+
- Failed authentication attempts
44+
- Invalid packets
45+
- Connection errors
46+
- Kicked players
47+
48+
3. Update the `failregex` patterns to match those log formats
49+
50+
## Usage
51+
52+
```bash
53+
# Start the services
54+
docker compose up -d
55+
56+
# Check fail2ban status
57+
docker compose exec fail2ban fail2ban-client status
58+
59+
# Check hytale jail status
60+
docker compose exec fail2ban fail2ban-client status hytale
61+
62+
# Manually unban an IP
63+
docker compose exec fail2ban fail2ban-client set hytale unbanip <IP>
64+
65+
# View banned IPs
66+
docker compose exec fail2ban fail2ban-client get hytale banip
67+
```
68+
69+
## UDP Considerations
70+
71+
Hytale uses UDP for its game protocol. fail2ban handles this by:
72+
73+
1. Using `protocol = udp` in the jail configuration
74+
2. Using `iptables-allports[protocol=udp]` as the ban action
75+
76+
This ensures that iptables rules are created for UDP traffic specifically.
77+
78+
## Alternative: Host-Level fail2ban
79+
80+
If you prefer to run fail2ban on the host instead of in a container:
81+
82+
1. Install fail2ban on your host:
83+
84+
```bash
85+
# Debian/Ubuntu
86+
sudo apt install fail2ban
87+
88+
# RHEL/CentOS/Fedora
89+
sudo dnf install fail2ban
90+
```
91+
92+
2. Copy the filter and jail files to host directories:
93+
94+
```bash
95+
sudo cp fail2ban/filter.d/hytale.local /etc/fail2ban/filter.d/
96+
sudo cp fail2ban/jail.d/hytale.local /etc/fail2ban/jail.d/
97+
```
98+
99+
3. Update the `logpath` in the jail file to point to your Docker volume location
100+
101+
4. Restart fail2ban:
102+
```bash
103+
sudo systemctl restart fail2ban
104+
```
105+
106+
## Troubleshooting
107+
108+
### fail2ban not banning IPs
109+
110+
1. Check if the filter matches your logs:
111+
112+
```bash
113+
docker compose exec fail2ban fail2ban-regex /var/log/hytale/server.log /data/filter.d/hytale.local
114+
```
115+
116+
2. Verify iptables rules are being created:
117+
```bash
118+
docker compose exec fail2ban iptables -L -n
119+
```
120+
121+
### Logs not appearing
122+
123+
Ensure the Hytale server is writing logs to the shared volume at `/app/Hytale/logs/`.
124+
125+
### Permission issues
126+
127+
The fail2ban container needs `NET_ADMIN` capability to manage iptables.

‎examples/fail2ban/docker-compose.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
services:
2+
hytale:
3+
image: ghcr.io/zuedev/hytale-server-docker:main
4+
ports:
5+
- "5520:5520/udp"
6+
volumes:
7+
- ./hytale-data:/app/Hytale
8+
restart: unless-stopped
9+
stdin_open: true
10+
tty: true
11+
12+
fail2ban:
13+
image: crazymax/fail2ban:latest
14+
container_name: fail2ban
15+
restart: unless-stopped
16+
network_mode: host
17+
cap_add:
18+
- NET_ADMIN
19+
- NET_RAW
20+
volumes:
21+
- ./hytale-data/logs:/var/log/hytale:ro
22+
- ./fail2ban/jail.d:/data/jail.d:ro
23+
- ./fail2ban/filter.d:/data/filter.d:ro
24+
- ./fail2ban-data:/data/db
25+
environment:
26+
- TZ=UTC
27+
- F2B_LOG_TARGET=STDOUT
28+
- F2B_LOG_LEVEL=INFO
29+
- F2B_DB_PURGE_AGE=1d

‎examples/fail2ban/fail2ban/filter.d/hytale.local‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Fail2Ban filter for Hytale server
2+
#
3+
# NOTE: This is a template filter. You'll need to adjust the regex patterns
4+
# based on actual Hytale server log output for authentication failures,
5+
# invalid packets, or other malicious activity.
6+
#
7+
# Common patterns to look for:
8+
# - Failed authentication attempts
9+
# - Invalid packet/protocol errors
10+
# - Connection floods from single IP
11+
# - Malformed requests
12+
13+
[Definition]
14+
15+
# Example patterns - adjust based on actual Hytale server log format
16+
# These are placeholder patterns that need to be customized
17+
18+
# Failed authentication pattern (adjust regex to match actual logs)
19+
failregex = ^.*\[WARN\].*Failed authentication from <HOST>.*$
20+
^.*\[ERROR\].*Invalid packet from <HOST>.*$
21+
^.*\[WARN\].*Connection refused from <HOST>.*$
22+
^.*\[WARN\].*Kicked <HOST>.*$
23+
^.*Connection from <HOST>.*failed.*$
24+
25+
# Ignore legitimate connections
26+
ignoreregex =
27+
28+
# Notes:
29+
# - <HOST> is a special fail2ban tag that matches IP addresses
30+
# - Adjust patterns after examining actual Hytale server logs
31+
# - Check /app/Hytale/logs/ for log file format

‎examples/fail2ban/fail2ban/jail.d/hytale.local‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[hytale]
2+
enabled = true
3+
filter = hytale
4+
logpath = /var/log/hytale/*.log
5+
# UDP port for Hytale
6+
port = 5520
7+
protocol = udp
8+
# Ban time in seconds (1 hour)
9+
bantime = 3600
10+
# Time window to count failures (10 minutes)
11+
findtime = 600
12+
# Number of failures before ban
13+
maxretry = 5
14+
# Use iptables for UDP
15+
banaction = iptables-allports[protocol=udp]

0 commit comments

Comments
 (0)