Firewall Rules

Firewall rules let you control who can connect to your server. Rules are evaluated at the edge — blocked traffic never reaches your backend.

How rules work

Each rule has three parts: a condition (what to match), an action (what to do), and a priority (evaluation order). Rules are checked in priority order, lowest number first. The first matching rule wins.

If no rule matches, the connection is allowed by default.

Condition types

IP Address

Match a single IP address. Use this for known attackers or to whitelist your staff.

Condition: ip_address
Value:     192.168.1.100

CIDR Range

Match an entire IP range. Useful when attacks come from the same subnet or hosting provider.

Condition: ip_range
Value:     10.0.0.0/8

Country

Match traffic from a specific country using ISO 3166-1 alpha-2 codes. Available for all game types.

Condition: country
Value:     CN

Common codes: US (United States), DE (Germany), CN (China), RU (Russia), BR (Brazil), KR (South Korea).

Protocol Version

Match clients using a specific Minecraft protocol version. Useful for blocking outdated clients that are commonly used by bot tools. Only available for Java and Geyser domains.

Condition: protocol_version
Value:     min: 765    (blocks clients below 1.20.3)

Some common version numbers: 47 (1.8), 340 (1.12.2), 760 (1.19.2), 765 (1.20.3), 769 (1.21.4).

Username Pattern

Match player usernames with a regex pattern. Great for catching bot naming patterns. Only available for Java and Geyser domains.

Condition: username
Value:     ^Bot_\d+$

Examples:

• ^Bot_\d+$ — matches "Bot_001", "Bot_999", etc.
• ^(Player|User)_[a-f0-9]+$ — matches generated names like "Player_a3f2b1"
• ^.{1,2}$ — matches usernames shorter than 3 characters

Actions

• Allow — Let the connection through. Allow rules override block rules when they have a higher priority (lower number).
• Block — Drop the connection immediately. The player sees a connection timeout.
• Rate Limit — Allow up to N connections per second from the matched source. Connections beyond the limit are dropped.

Priority

Rules are evaluated from lowest priority number to highest. The first rule that matches a connection determines the outcome.

A typical setup looks like this:

Managing rules

From the dashboard

Go to Domains and select your domain, then open the Firewall tab. You can create, edit, reorder, and delete rules from there.

From the API

List all rules:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.pixelshield.net/api/domains/DOMAIN_ID/firewall

Create a rule:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block attacker subnet",
    "action": "block",
    "condition": {"type": "ip_range", "cidr": "203.0.113.0/24"},
    "priority": 10
  }' \
  https://api.pixelshield.net/api/domains/DOMAIN_ID/firewall

You can also bulk-import rules:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rules": [...]}' \
  https://api.pixelshield.net/api/domains/DOMAIN_ID/firewall/bulk

See the API Reference for the full request/response format.

Availability by game type

Tips

• Whitelist before you blacklist. Put allow rules at a lower priority number than block rules so your staff and known-good IPs always get through.
• Use CIDR ranges instead of individual IPs when blocking subnets. One /24 rule replaces 256 individual IP rules.
• Rate limiting beats blocking for entire countries. Real players from those regions can still connect, just at a controlled rate. Full blocks should be a last resort.
• Clean up old rules. Remove temporary blocks once an attack subsides. Stale rules add evaluation overhead and make your rule list harder to manage.
• Block old protocol versions if your server runs a recent Minecraft version. Most bot tools connect with outdated clients.