Bypass System

The bypass system allows specific players to connect even when using a VPN or proxy. This is useful for staff, content creators, or players with legitimate VPN needs.

How It Works

When a player connects:

1. Plugin checks if player is in bypass list
2. If bypassed → Allow connection immediately (no API call)
3. If not bypassed → Perform VPN check

The bypass check happens before the VPN check, saving API calls for bypassed players.

Managing Bypasses

Add a Player

/antivpn bypass add <player>

Example:

/antivpn bypass add Notch
> [CocoVPN] Notch added to bypass list.

Remove a Player

/antivpn bypass remove <player>

Example:

/antivpn bypass remove Notch
> [CocoVPN] Notch removed from bypass list.

List All Bypasses

/antivpn bypass list

Example:

/antivpn bypass list
> [CocoVPN] Bypasses: Notch, jeb_, Dinnerbone

---

Storage

Bypasses are stored in an SQLite database (data.db) in the plugin folder:

plugins/CocoAntiVPN/
├── config.yml
└── data.db

Database Structure

CREATE TABLE bypass (
    player TEXT PRIMARY KEY COLLATE NOCASE
);

Features:

• Persistent - Survives server restarts
• Case-insensitive - "Notch" = "notch" = "NOTCH"
• Automatic - No manual database management needed

---

Use Cases

Staff Members

Staff often need VPNs for security or testing:

/antivpn bypass add AdminPlayer
/antivpn bypass add ModeratorPlayer

Content Creators

YouTubers/streamers may use VPNs for privacy:

/antivpn bypass add StreamerName

Players with ISP Issues

Some ISPs route through proxy-like infrastructure:

/antivpn bypass add PlayerWithISPIssue

Tournament Players

Players in tournaments from other countries:

/antivpn bypass add TournamentPlayer1
/antivpn bypass add TournamentPlayer2

---

Bypass vs Unban

Understanding the difference:

Feature	Bypass	Unban
Target	Player name	IP address
Effect	Skip VPN check entirely	Remove from blacklist
Permanent	Yes (until removed)	No (can be re-blacklisted)
Use case	Trusted players	False positives

Example Scenario:

1. Player Steve uses VPN, gets blacklisted
2. /antivpn unban 1.2.3.4 - Removes current IP from blacklist
3. /antivpn bypass add Steve - Prevents future detections

---

Permissions

Permission	Description
antivpn.command.bypass.add	Add players to bypass
antivpn.command.bypass.remove	Remove players from bypass
antivpn.command.bypass.list	View bypass list

Permission Examples

Full bypass management:

/lp user Admin permission set antivpn.command.bypass.* true

View only:

/lp user Moderator permission set antivpn.command.bypass.list true

---

Proxy Networks

On BungeeCord/Velocity networks:

• Bypass list is stored on the proxy
• Single bypass list for entire network
• No per-server bypass configuration needed

---

Best Practices

Regular Cleanup

Periodically review and clean up bypasses:

/antivpn bypass list

Remove players who no longer need bypass:

/antivpn bypass remove InactivePlayer

Document Bypasses

Keep a record of why each player was bypassed:

• Staff role
• Content creator
• ISP issue
• Temporary (tournament, etc.)

Minimal Bypasses

Only bypass players who truly need it. More bypasses = more potential vulnerabilities.

---

Troubleshooting

Player Still Being Kicked

1. Check spelling: /antivpn bypass list
2. Verify player name matches exactly
3. Reload config: /antivpn reload
4. Check if their IP is blacklisted (use /antivpn unban <ip>)

Cannot Add Bypass

1. Check permission: antivpn.command.bypass.add
2. Check syntax: /antivpn bypass add <player>
3. Check for console errors

Bypass List Empty After Restart

1. Check data.db exists
2. Check file permissions
3. Look for database errors on startup