Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/leev/ngx_http_geoip2_module

Nginx GeoIP2 module
https://github.com/leev/ngx_http_geoip2_module

Last synced: 3 months ago
JSON representation

Nginx GeoIP2 module

Lists

README 

        
Description

===========



**ngx_http_geoip2_module** - creates variables with values from the maxmind geoip2 databases based on the client IP (default) or from a specific variable (supports both IPv4 and IPv6)



The module now supports nginx streams and can be used in the same way the http module can be used.



## Installing

First install [libmaxminddb](https://github.com/maxmind/libmaxminddb) as described in its [README.md

file](https://github.com/maxmind/libmaxminddb/blob/main/README.md#installing-from-a-tarball).



#### Download nginx source

```

wget http://nginx.org/download/nginx-VERSION.tar.gz

tar zxvf nginx-VERSION.tar.gz

cd nginx-VERSION

```



##### To build as a dynamic module (nginx 1.9.11+):

```

./configure --add-dynamic-module=/path/to/ngx_http_geoip2_module

make

make install

```



This will produce ```objs/ngx_http_geoip2_module.so```. It can be copied to your nginx module path manually if you wish.



Add the following line to your nginx.conf:

```

load_module modules/ngx_http_geoip2_module.so;

```



##### To build as a static module:

```

./configure --add-module=/path/to/ngx_http_geoip2_module

make

make install

```



##### If you need stream support, make sure to compile with stream:

```

./configure --add-dynamic-module=/path/to/ngx_http_geoip2_module --with-stream

OR

./configure --add-module=/path/to/ngx_http_geoip2_module --with-stream

```



## Download Maxmind GeoLite2 Database (optional)

The free GeoLite2 databases are available from [Maxminds website](http://dev.maxmind.com/geoip/geoip2/geolite2/) (requires signing up)



## Example Usage:

```

http {

    ...

    geoip2 /etc/maxmind-country.mmdb {

        auto_reload 5m;

        $geoip2_metadata_country_build metadata build_epoch;

        $geoip2_data_country_code default=US source=$variable_with_ip country iso_code;

        $geoip2_data_country_name country names en;

    }



    geoip2 /etc/maxmind-city.mmdb {

        $geoip2_data_city_name default=London city names en;

    }

    ....



    fastcgi_param COUNTRY_CODE $geoip2_data_country_code;

    fastcgi_param COUNTRY_NAME $geoip2_data_country_name;

    fastcgi_param CITY_NAME    $geoip2_data_city_name;

    ....

}



stream {

    ...

    geoip2 /etc/maxmind-country.mmdb {

        $geoip2_data_country_code default=US source=$remote_addr country iso_code;

    }

    ...

}

```



##### Metadata:

Retrieve metadata regarding the geoip database.

```

$variable_name metadata 

```

Available fields:

  - build_epoch: the build timestamp of the maxmind database.

  - last_check: the last time the database was checked for changes (when using auto_reload)

  - last_change: the last time the database was reloaded (when using auto_reload)



##### Autoreload (default: disabled):

Enabling auto reload will have nginx check the modification time of the database at the specified

interval and reload it if it has changed.

```

auto_reload 

```



##### GeoIP:

```

$variable_name [default=

        "iso_code":

          "US" 

        "names":

          {

            "de":

              "USA" 

            "en":

              "United States" 

          }

      }

  }



$ mmdblookup --file /usr/share/GeoIP/GeoIP2-Country.mmdb --ip 8.8.8.8 country names en



  "United States" 

```



This translates to:



```

$country_name "default=United States" source=$remote_addr country names en

```



##### Additional Commands:

These commands works the same as the original ngx_http_geoip_module documented here: http://nginx.org/en/docs/http/ngx_http_geoip_module.html#geoip_proxy.



However, if you provide the `source=$variable_with_ip` option on a variable, these settings will be ignored for that particular variable.



```

geoip2_proxy < cidr >

```

Defines trusted addresses.  When a request comes from a trusted address, an address from the "X-Forwarded-For" request header field will be used instead.



```

geoip2_proxy_recursive < on | off >

```

If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in "X-Forwarded-For" will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in "X-Forwarded-For" will be used.