Geo IP#

Using “Geo IP” information, you can configure your VPN server to expose some information of the IP address(es) your VPN clients use to connect to the service.

This can be useful to figure out where your VPN clients are connecting from, without needing to log the exact “Originating IP” address the VPN client uses to connect to the VPN server.

You can use this information both for Logging and with the Script Connect Hook.

NOTE: in the example below, we use the DB-IP database. It is released under the (CC BY 4.0) license and requires you to also mention in your service that you are using their GeoIP DB! Please make sure you adhere to the license requirements! See Attribution.

NOTE: available in vpn-user-portal >= 3.6.1.

NOTE: currently only available for OpenVPN connections, not WireGuard, see #7.

Geo IP Database#

In order to make this work, you need to obtain a “Geo IP” database. We are aware of two providers:

MaxMind used to offer a database you could at one point (freely) download, but nowadays requires an account and accepting a specific license. DB-IP still offers a free download without requiring an account. Their database is licensed under the “Creative Commons” license.

If you’d like, you can of course also use the commercial database to (supposedly) get more accurate results. We did NOT perform any tests with this.

In the instructions below, we assume that you are using the “IP to City Lite” DB-IP database, obtained here. As of this moment, the most recent database is dbip-city-lite-2024-04.mmdb.gz. You can extract the database using gunzip.

Installation#

We recommend that you install the database you obtained, as described in the previous section, under /usr/local/share. For example, if you use the DB-IP “IP to City Lite” file, we recommend placing it in /usr/local/share/DB-IP/dbip-city-lite.mmdb after extracting it using gunzip.

In order to read the database from PHP, you need to install the php-maxminddb module and restart PHP:

On Debian / Ubuntu:

$ sudo apt -y install php-maxminddb
$ sudo systemctl restart php$(/usr/sbin/phpquery -V)-fpm

On Fedora / EL:

$ sudo dnf -y install php-maxminddb
$ sudo systemctl restart php-fpm

Configuration#

After installing the PHP module and copying the database to /usr/local/share, we need to configure PHP to make use of it.

Modify /etc/vpn-user-portal/config.php and find the Log section. Modify it for example like shown below:

'Log' => [
    'syslogConnectionEvents' => true,
    'geoIpDb' => '/usr/local/share/DB-IP/dbip-city-lite.mmdb',
    'connectLogTemplate' => 'CONNECT {{USER_ID}} ({{PROFILE_ID}}:{{CONNECTION_ID}}) [{{IP_FOUR}},{{IP_SIX}}] [CC:{{GEO_IP_CC}}]'
],

Using the geoIpDb option adds the variables GEO_IP_CC and GEO_IP_URI variables. See Logging for more information. If you are using the Script Connection Hook, you can use the VPN_GEO_IP_CC and VPN_GEO_URI variables.

Testing#

If you are writing to syslog you can test using:

$ journalctl -f -t vpn-user-portal

If you use the example above, you’ll see something like this when you connect using a VPN client:

Apr 26 12:49:37 vpn.example.org vpn-user-portal[19915]: CONNECT fkooman (default-o:/mlU99+TkOUqUvvqg5LdqoY/sKwQY0NvFxDie6fwVRY=) [10.114.241.4,fd52:e2d1:97a:d5ad::4] [CC:DK]

If you see CC:*, i.e. a * instead of the country code, you MAY not have configured things correctly, OR you are connecting over WireGuard.

Geo DB Attribution#

In order to indicate (to your users) you are using DB-IP for “Geolocation”, they suggest you indicate on your service that you use their DB:

<a href="https://db-ip.com">IP Geolocation by DB-IP</a>

You can add this to the VPN portal, by creating the file /etc/vpn-user-portal/views/customFooter.php with this content:

<p>
<a href="https://db-ip.com">IP Geolocation by DB-IP</a>
</p>