Installation#
Requirements#
| Supported | |
|---|---|
| Server | Spigot, Paper, Purpur, Folia |
| Minecraft | 1.17.1 → 26.2 (including 26.1.x) |
| Java | 17+ (Minecraft 26.1 and 26.2 need Java 25) |
| Required plugin | PacketEvents 2.14+ (free) |
| Works next to | ViaVersion, ProtocolLib, PlaceholderAPI, LuckPerms, anticheats |
Steps#
- Stop the server.
- Download PacketEvents for your platform (Spigot/Paper build) and copy it into
plugins/. - Copy
OmniGuard-x.y.z.jarintoplugins/. - Start the server. You should see
OmniGuard x.y.z enabled on Paper in … ms. - Run
/og doctorin game or in the console.
Never install or update OmniGuard with /reload or plugin managers. Netty handlers must be injected while the server starts.
Bedrock players (Geyser / Floodgate)#
Fully supported. Floodgate name prefixes (. and * by default, see login-guard.bedrock-prefixes) are accepted,
Geyser's local connections are never rate-limited, and Geyser-translated inventory clicks are not judged by
Java-only rules.
Behind a proxy (BungeeCord / Velocity)#
checks.connection-flood.behind-proxy: auto detects forwarding (spigot.yml bungeecord, Paper Velocity settings).
In proxy mode, per-IP connection limits switch off because all traffic comes from the proxy. Every other protection keeps working,
including per-IP login limits, which use the forwarded player IP.
Updating#
Replace the jar and restart. New config keys fall back to their defaults until you add them. /og reload lists
anything it had to fall back on.
Files#
| Path | Content |
|---|---|
config.yml |
All settings (never rewritten by OmniGuard) |
lang/en.yml, lang/tr.yml |
Messages |
state.yml |
In-game toggles, learned limits, lockdown |
logs/<date>.log |
Every alert |
forensics/<date>/*.txt |
Evidence of each punishment |
reports/<date>.txt |
Daily security report |
ledger/ |
Ignored and compromised item identities |
alts.yml, verified-ips.txt |
Account links, verified IPs |