README.md

g3iploc

g3iploc is an IP address location lookup service to be used with g3proxy to enable GeoIP support. The protocol is defined here.

g3iploc is designed to run with g3proxy on the same host. It is recommended to write you own implementation if you need to serve a cluster of g3proxy instances.

How to build

To build debug binaries:

cargo build -p g3iploc -p g3iploc-db

To build release binaries:

cargo build --profile release-lto -p g3iploc -p g3iploc-db

How to run

Example

See this simple basic.

You can run cargo run --bin g3iploc -- -c g3iploc/examples/basic/ -G port2888 -vv to start it.

Set UDP listen address

The default UDP listen address is 127.0.0.1:2888, which is also the same default connect address in g3proxy.

There are two ways to change the UDP listen port:

• Via command line options

  You can set -G port or --group-name port to change the UDP listen port, the final listen address will be [::]:.

  You can set the systemd instance name to port, so when you run systemctl start g3iploc@port<port>, it will listen to the correct port automatically.

• Via environment variables

  You can use the environment variable UDP_LISTEN_ADDR to change the UDP listen address. You can add this environment variable to /etc/g3iploc/<instance name>/env file to use this with systemd managed g3iploc service.

Hot Restart

It is not possible to do hot restart gracefully without using two ports.

If g3iploc is running at port 3000, and g3proxy is also using port 3000, the steps are:

1. start a new g3iploc service at port 3001 with the new config
2. reload g3proxy to use g3iploc port 3001
3. stop g3iploc running at port 3000

GeoIP Database

g3iploc can only load databases in G3 native CSV format, which can be generated by using geoip-dump scripts.

The following vendors are supported:

• Maxmind

  1. Download the GeoLite2 database mmdb file. See https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/.

  2. Install MaxMind DB Python Module.

  3. Convert by using geoip-dump scripts

     python3 geoip_dump_country.py --maxmind -i GeoLite2-Country.mmdb -o g3-country.csv.gz
     python3 geoip_dump_asn.py --maxmond -i GeoLite2-ASN.mmdb -o g3-asn.csv.gz

• IPinfo

  1. Download the database mmdb file. See https://ipinfo.io/developers/database-download#getting-started.

  2. Install MaxMind DB Python Module.

  3. Convert by using geoip-dump scripts

     python3 geoip_dump_country.py --ipinfo -i ipinfo_lite.mmdb -o g3-country.csv.gz
     python3 geoip_dump_asn.py --ipinfo -i ipinfo_lite.mmdb -o g3-asn.csv.gz

• IPFire

  1. Download the database file location.db.xz from https://www.ipfire.org/location/install.

  2. Extract location.db

  3. Install libloc Python binding module.

  4. Convert by using geoip-dump scripts

     python3 geoip_dump_country.py --ipfire -i location.db -o g3-country.csv.gz
     python3 geoip_dump_asn.py --ipfire -i location.db -o g3-asn.csv.gz

Command line options

Just run g3iploc -h to see all supported command line options.