FAQ

Sources

ELI5:

A bad/evil player can easily change their location so your server can't see who they really are. When those players do this, it won't matter if you ban or punish them because they can just change their location again and join back in. When a bad/evil player does this, your server will (quite reasonably) assume they are an entirely new player and happily let them join.

Anti-VPN attempts to fix this by ensuring that when a player logs in, it is from their real location. It does this through what it calls "sources". Changing locations is an art of black magic, and detecting someone who's changed their location is even blacker magic. Sources sometimes make mistakes. Anti-VPN attempts to correct those mistakes and only provides sources that work well, but it's not perfect. See this for more information on how it makes these mistakes and how to fix them.

Be aware that not every player that changes their location in this way is bad or evil. Some do it for legitimate reasons, and Anti-VPN provides several ways to "whitelist" them so it doesn't force them to use their real location. More information on "whitelisting" here.

When a player joins your server, Anti-VPN takes the location that they've given and asks these "sources" about it. The sources then do some magic with the player's location and tell Anti-VPN the location is either "good", or "bad". Anti-VPN takes this and does some more magic with it before ultimately deciding itself that "this location is good" or "this location is bad".

Sometimes, if you have lots of players join your server, the sources get a little upset and start saying "you can't ask about any more locations from us today. You'll have to come back tomorrow." In these cases, Anti-VPN either asks another source, or if it has run out of sources to ask, will throw an error in the console. More about that here.

To prevent sources form getting upset quite as often, Anti-VPN performs some more magic. Sometimes a player joins frequently from the same location, or multiple players join from the same location. In these cases, Anti-VPN remembers that it's recently asked about their location and simply comes back with the same "good" or "bad" result it got before, without even asking the source. This makes sources very happy and they, in turn, let Anti-VPN ask about more locations before they start saying "you can't ask about any more locations today." This process is called "caching".

---

In-depth

Anti-VPN calls its API services "sources". When it checks an IP, it goes out to one of many (or several) websites/services to check the validity of the IP. The website/service processes the request and returns a result. Anti-VPN takes this result, does some calculations (depending on config), and returns it. It then caches this result for some time so a similar request won't need to use up your credits with said service(s). The flow looks like this:

IP request --> Anti-VPN --> Check cache
                                 |
                                 v
                             Is cached?
                             |        |
                             v        v
                           Yes        No
                           |           |
                           v           v
             Get cached result       Fetch from source(s)
                   |                         |
                   v                         v
Return result <-----             Calculate result (if needed)
                   ^                         |
                   |                         v
                   |                    Cache result
                   |                         |
                   |                         v
                   ---------------------------

The "sources" are defined in the config, and so is the method of calculation. You can find more information on the config here.

---

Anti-VPN is kicking players wrongly / API gives bad results

If you find that Anti-VPN is providing invalid results, then you can check what is going on and why by using /avpn test <ip> and /avpn check <ip>

Running /avpn test <ip> on a "bad" IP will tell you a lot about how the plugin is getting the result. /avpn check <ip> will tell you what the final result actually is.

Remember that in cascade mode (the default mode), the plugin will go through each enabled source one-by-one and select the first valid result it gets. In consensus mode, the plugin will query every source it has available at once and return a final result based on the given responses from each source.

The scenarios are as follows:

• You are using cascade mode and the first result being given to Anti-VPN is "bad" (most likely)
• You are using consensus mode and most sources agree that a particular IP is "bad"

In any case, you can fix the issue by disabling the source or switching to consensus mode in the configuration file. You may also whitelist the player by giving them the permission node avpn.bypass (recommended) or whitelist the IP by adding it to the ignore section of the configuration file (NOT recommended)

tl;dr

Most likely you are using cascade mode and your primary source is returning bad results. Modify the configuration file and either switch to consensus mode or disable any sources giving "bad" results.

You may also whitelist the player by giving them the permission node avpn.bypass (recommended) or whitelist the IP by adding it to the ignore section of the configuration file (NOT recommended)

Errors

No sources were available to query. or frequent Source X returned an error.

This means one of several things:

• You've run out of "credits" with the sources you have enabled (most likely)
• You don't have a valid outbound internet connection (DNS/firewall issues, somewhat-likely)
• All of the sources you've enabled in the config have returned errors (unlikely)

Normally, simply reading the error message thrown in the console is enough to get an idea of what happened.

Test your sources with /avpn test <ip> - you will likely see most or all of them return with the message "Error"

In order to fix this, check each source you have enabled in the configuration file and see if you've run out of "credits" with each source. In the most likely scenario, you have too many players logging in (your network is too large for the sources you currently have). You will either require more sources to be enabled or API keys with larger limits with sources you currently have enabled. It is recommended that you do both. Then double-check your outbound internet if you can, and reload the plugin.

tl;dr

Modify the config.yml file to enable more sources and/or add API keys with larger limits. Also check your outbound firewall/DNS if you can.