Skip to content

Home

Jump to bottom
Gero Lindner edited this page Dec 27, 2024 · 3 revisions

Connection Guard is an anti-vpn and geo-blocking plugin. It gives you full control over the way you are handling vpn or geo-blocking cases.

Installation

  1. Download the plugin from the release section.
  2. Place the connectionguard-X.X.X-all.jar file into the plugins directory of your Spigot, BungeeCord or Velocity server.
  3. Start or restart your Spigot, BungeeCord or Velocity server.

Change messages and language

Every message sent to the player or the console can be configured in the language file (located in plugins/ConnectionGuard/translations). The default language is english (en.yml, message-language: en). If you change the value in the config.yml (e.g. to de) the plugin will look for a file called <value>.yml (e.g. de.yml). To create a new language, copy the existing en.yml, rename it and edit the values.

Behavior

You can customize how the plugin will react to players using vpn or connecting from a geo-blocked region.

VPN

config.yml

behavior:
  vpn:
    # If set to true, players connected to a vpn cannot join the server.
    kick-player: true
    # If set to true, players with the permission connectionguard.notify.vpn will receive a notification message
    # when a player connected to a vpn tries to connect.
    notify-staff: true
    # If set to true, the specified command will be executed by the console when a user connected to a vpn tries to connect.
    # Available placeholders: %NAME%, %IP%
    execute-command:
      enabled: false
      command: 'ban-ip %IP%'
    # If set to true, a discord webhook message is sent.
    send-webhook:
      enabled: false
      url: ''

Geo-Blocking

config.yml

behavior:
  geo:
    # If set to true, geo-blocked players cannot join the server.
    kick-player: true
    # If set to true, players with the permission connectionguard.notify.geo will receive a notification message
    # when a geo-blocked player tries to connect.
    notify-staff: true
    # If set to true, the specified command will be executed by the console when a geo-blocked user tries to connect.
    # Available placeholders: %NAME%, %IP%
    execute-command:
      enabled: false
      command: 'ban-ip %IP%'
    # If set to true, a discord webhook message is sent.
    send-webhook:
      enabled: false
      url: ''

    # Define how restrictive you want to be with geo-blocking.
    # Available options:
    # - BLACKLIST (action specified by 'flag' below will be executed, if the country is on the list)
    # - WHITELIST (action specified by 'flag' below will be executed, if the country is not on the list)
    type: 'BLACKLIST'

    # Countries are specified by their Alpha 2 code.
    # A full list can be found here: https://www.iban.com/country-codes
    list:
      - CN
      - RU

Add a country to the white- or blacklist

Connection Guard uses Alpha-2 codes to identify countries. You can find a list here.

behavior:
  geo:
    # Define how restrictive you want to be with geo-blocking.
    # Available options:
    # - BLACKLIST (action specified by 'flag' below will be executed, if the country is on the list)
    # - WHITELIST (action specified by 'flag' below will be executed, if the country is not on the list)
    type: 'BLACKLIST'

    # Countries are specified by their Alpha 2 code.
    # A full list can be found here: https://www.iban.com/country-codes
    list:
      - CN
      - RU

Exclude a player from vpn and geo checks

There are 2 ways to exclude players from geo and vpn checks.

  1. Option: Add the name, uuid or ip to the vpn or geo exemption list in the config.yml 
behavior:
  vpn:
    # If you want some players or ip addresses to be exempted from the vpn check,
    # you can add them here.
    exemptions:
      - '069a79f4-44e9-4726-a5be-fca90e38aaf5'
      - '127.0.0.1'
  1. Enable use-permission-exemption in the config.yml and give the targeted player the connectionguard.exemption.vpn or connectionguard.exemption.geo permission. This requires LuckPerms, if you're using Connection Guard on a Spigot or BungeeCord server. On Velocity, you can just enable it in the config and use whatever permission system you like.
behavior:
  vpn:
    # If enabled, players with the permission connectionguard.exemption.vpn will not be flagged as vpn players.
    # Only available on Velocity or when having LuckPerms installed on Spigot or BungeeCord.
    use-permission-exemption: false

Detection

The default config of Connection Guard uses ProxyCheck to check for VPNs and IP-API to get the geo data. You don't have to change anything if the plugin works like you would expect, but if you have one of the following problems, you can tweak some settings here:

  • rate limit or query limit of the vpn service api reached (typically reached with over 100 daily unique players)
  • too many false flags

What do I do when the plugin says my query limit is reached?

Connection Guard uses 3rd-party services to check the vpn usage of players. They typically have query limits (daily, weekly or monthly). The default configuration uses ProxyCheck, which lets you check 100 unique players per day. The solution is to either switch to a different service provider or to set an api-key.

Service Limit without API-Key Limit with free API-Key Pricing for more requests
ProxyCheck (default) 100 daily requests 1.000 requests/day 2.99$/month for 10.000 requests/day
IPHub - 1.000 requests/day 19.99$/month for 10.000 requests/day
IP-API 45 requests/minute - Not Implemented for Connection Guard
VPNAPI - 1.000 requests/day 19$/month for 10.000 requests/day

What to do when the plugin flags non-vpn users?

To minimize the chance of a false-flag, you can enable multiple service provider (set enabled: true) and increase the required-positive-flags value (maximum is the amount of service provider you activated).

What to do when the plugin doesn't flag every vpn user?

To maximize vpn detection, you can enable multiple service provider (set enabled: true) and decrease the required-positive-flags value (minimum is 1! Never set it below 1!).

Clone this wiki locally