Connection shield#

Built for shared IPs#

One IP is very often many real people: a family, a school, an internet café, or a mobile carrier that puts thousands of customers behind one address (CGNAT). OmniGuard therefore follows four rules:

Trusted IPs. Once a real player completes a join from an IP, that IP is trusted. It gets trusted-multiplier (5×) more connections and logins, it is never blocked, and attack mode never tightens it.
Refuse, do not block. Connections above the limit are refused one by one. A whole IP is blocked only after block-after-refusals (40) refusals within 10 seconds, which only a flood produces.
No account caps on trusted IPs. max-accounts-per-ip is 0 (off) by default. During attack mode, attack-max-accounts-per-ip applies to untrusted IPs only.
Never limit what is not a person. Unknown addresses and 127.0.0.1 / ::1 (Geyser, local proxies) are never limited.

This behaviour is covered by the test suite. For example, 10 players on one IP refresh the server list and join together, and all of them get in without a single alert.

Check	What it does
`connection-flood`	Per-IP connections at the Netty level; floods are blocked for 60 s
`login-guard`	Username pattern (offline-mode servers only, Bedrock prefixes allowed), per-IP login rate, accounts per IP during attacks, rejoin cycling (8 completed joins/60 s per account)
`alt-link`	Links accounts that share IPs and alerts when a new account joins from an IP that a banned account used

Attack mode#

When connections/s, logins/s or blocked packets/s stay above attack-mode thresholds for trigger-seconds, OmniGuard:

multiplies connection and login limits by limit-multiplier;
asks unknown IPs to reconnect once (between reconnect-min-seconds and reconnect-max-seconds). Real players pass, bots usually do not. IPs that joined before are never asked;
groups refusal alerts into a single summary when the attack ends (Attack mode ended after 32s, refused N connections and M logins).

Force it with /og attackmode on|off|auto.

Lockdown#

/og lockdown on lets only already-verified IPs in. Use it while dealing with a raid or a grief wave. The setting is saved in state.yml and survives restarts.

Ban evasion#

/og alts <player> shows every linked account; punished ones are red. Only new accounts (never seen before) on an IP that a currently banned account used are flagged. Siblings who have played for months, and accounts that were only kicked, are not evaders. alt-link.block-evasion: true also refuses such logins. It is off by default because families and schools share IPs.