Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lDEVinux/eaglercraft/llms.txt

Use this file to discover all available pages before exploring further.

EaglercraftBungee includes built-in moderation tools for banning users, blocking IPs, filtering client origins, and rate limiting connections. Most commands are run directly from the BungeeCord console. Where noted, some features require an NGINX reverse proxy with forward_ip: true to function.

​
Username Bans

Username bans prevent specific players — or patterns of usernames — from connecting to your server. All ban commands are run from the EaglercraftBungee console.
CommandDescription
eag-ban <username>Ban an exact username
eag-ban-regex <regex>Ban all usernames matching a regular expression (matched against the lowercase username)
eag-ban-wildcard <pattern>Ban usernames matching a wildcard (*) pattern, e.g. eag-ban-wildcard *hacker*
eag-unban <username>Remove an existing ban
eag-banned <username>Check whether a username is currently banned
eag-banlistDisplay all active username bans
You can also edit bans.txt directly in your EaglercraftBungee folder. The server automatically reloads the file when it is saved, so changes take effect immediately without a restart.
Bukkit’s /op command is case-insensitive — opping LAX1DUDE also grants operator permissions to anyone joining as lax1dude, LaX1DuDe, or any other capitalisation variant. To prevent privilege escalation, install BitchFilterPlugin.jar into java/bukkit_command/plugins and always register operator usernames in all lowercase. See Bukkit Setup for details.

​
IP Bans

IP bans block connections from specific addresses or subnets. The following commands are available from the EaglercraftBungee console:
CommandDescription
eag-ban-ip <ip>Ban a specific IP address
eag-ban-ip <username>Ban the IP address of a currently connected player
eag-ban-ip 192.168.0.0/8Ban an entire subnet using CIDR notation
IP bans require forward_ip: true in config.yml and an NGINX reverse proxy configured to pass proxy_set_header X-Real-IP $remote_addr. Without these, EaglercraftBungee cannot determine the player’s real IP address and IP banning is disabled. See NGINX Reverse Proxy.

​
Origin / Client Blacklisting

EaglercraftBungee includes a built-in domain blacklist that updates automatically from a remote subscription list. This allows you to block clients hosted on known malicious or unauthorised domains. The feature is enabled by default. The following options in config.yml control origin filtering behaviour:
config.yml
enable_web_origin_blacklist: true
origin_blacklist_block_replit_clients: false
origin_blacklist_block_offline_download: false
origin_blacklist_block_missing_origin_header: true
OptionDescription
enable_web_origin_blacklistEnables the auto-updating domain blacklist. Set to false to disable it entirely.
origin_blacklist_block_replit_clientsSet to true to block all clients hosted on Replit (.repl.co and similar domains).
origin_blacklist_block_offline_downloadSet to true to block clients running from the offline HTML download.
origin_blacklist_block_missing_origin_headerSet to true to block connections with no Origin header (e.g. the debug desktop runtime).

​
Console Commands

The following console commands let you inspect and manage the local origin blacklist without editing files directly:
CommandDescription
domain <player>View the origin domain of a connected player
block-domain <domain>Add a domain to the local blacklist
block-domain-name <name>Block a domain by display name
unblock-domain <domain>Remove a domain from the local blacklist

​
Custom Blacklist Regex

To add your own blocked domains, create a file called origin_blacklist.txt in your bungee_command directory. Add one regular expression per line. The file reloads automatically when changes are detected — no restart required. Example entries from the default upstream blacklist: 
.*x.?ray.*
.*ha(ck|x).*
.*gitpod\.io$
.*neocities\.org$
The blacklist subscription URLs (fetched automatically on startup) are defined in config.yml:
config.yml
origin_blacklist_subscriptions:
- https://g.lax1dude.net/eaglercraft/origin_blacklist.txt
- https://raw.githubusercontent.com/LAX1DUDE/eaglercraft/main/stable-download/origin_blacklist.txt

​
Whitelist Mode

To restrict your server so that only your own client can connect, enable simple whitelist mode:
config.yml
origin_blacklist_use_simple_whitelist: true
origin_blacklist_simple_whitelist:
- your-domain.example.com
origin_blacklist_block_offline_download: true
Add your client’s domain to origin_blacklist_simple_whitelist. Only connections originating from that domain will be permitted; all others are rejected.
Always set origin_blacklist_block_offline_download: true when using whitelist mode. The offline download client does not send a matching Origin header and is not blocked by the whitelist by default, which would allow players to use the offline download to bypass your domain restriction.

​
Rate Limiting

EaglercraftBungee has built-in DoS protection with configurable per-IP rate limiting. The full configuration reference for the ratelimit block — including the ip, login, motd, and query sub-sections — is covered in Configuration. To reset the DoS protection state (e.g. to unblock an IP that was locked out), run from the EaglercraftBungee console: 
eag-ratelimit reset
Rate limiting requires forward_ip: true and an NGINX reverse proxy. Without these, DoS protection operates at the connection level only and per-IP limits are not enforced.

​
Permissions

EaglercraftBungee uses BungeeCord’s standard permission system. The default permission groups are defined in config.yml and can be extended with a permissions plugin.
config.yml
permissions:
  default:
  - bungeecord.command.server
  - bungeecord.command.list
  - bungeecord.command.eag.domain
  admin:
  - bungeecord.command.alert
  - bungeecord.command.end
  - bungeecord.command.ip
  - bungeecord.command.reload
  - bungeecord.command.eag.ban
  - bungeecord.command.eag.banwildcard
  - bungeecord.command.eag.banip
  - bungeecord.command.eag.banregex
  - bungeecord.command.eag.reloadban
  - bungeecord.command.eag.banned
  - bungeecord.command.eag.banlist
  - bungeecord.command.eag.unban
  - bungeecord.command.eag.ratelimit
  - bungeecord.command.eag.blockdomain
  - bungeecord.command.eag.blockdomainname
  - bungeecord.command.eag.unblockdomain
All players receive the default permissions group. The admin group grants access to all ban, rate-limit, and domain-blocking commands. Assign the admin group to trusted staff members via BungeeCord’s groups config or a compatible permissions plugin.

Build docs developers (and LLMs) love

Get started for freeTalk to us