freegeoip

README

freegeoip

This is the source code of the freegeoip software. It contains both the web server that empowers freegeoip.net, and a package for the Go programming language that enables any web server to support IP geolocation with a simple and clean API.

See http://en.wikipedia.org/wiki/Geolocation for details about geolocation.

Developers looking for the Go API can skip to the Package freegeiop section below.

Running

This section is for people who desire to run the freegeoip web server on their own infrastructure. The easiest and most generic way of doing this is by using Docker.

See the Server Options below for more information on configuring the server.

Docker

Install Docker on Ubuntu 14.04 LTS:

sudo apt-get install docker.io

Install Docker on CentOS 7:

yum install docker

Run the freegeoip web server:

docker run --net=host --restart=always -d fiorix/freegeoip

Test:

curl localhost:8080/json/1.2.3.4

See the API section below for details.

Other Linux, OS X, or FreeBSD

There are pre-compiled binaries available for you:

https://github.com/fiorix/freegeoip/releases

You'll have to set up your own init scripts for your system.

Server Options

You can configure the freegeoip web server to listen on a port other than the default 8080, and also listen on HTTPS by passing an ip:port and X.509 certificate and key files.

These and many other options are described in the help. If you're using Docker, you can see them like this:

docker run --rm -it fiorix/freegeoip --help

By default, the Docker image of freegeoip does not provide the web page from freegeiop.net, it only provides the API.

If you want to serve that page, you can pass the -public=/var/www parameter in the command line. You can also tell Docker to mount that directory as a volume on the host machine and have it serve your own page, using Docker's -v parameter.

If the freegeoip web server is running behind a proxy or load balancer, you have to run it passing the -use-x-forwarded-for parameter and provide the X-Forwarded-For HTTP header so the web server is capable of using the source IP address of the connection to perform geolocation lookups when an IP is not provided to the API, e.g. /json/ vs /json/1.2.3.4.

Database

The current implementation uses the free GeoLite2 database from MaxMind.

In the past we had databases from other providers, and at some point even our own database comprised of different sources. This means it might change in the future.

If you have purchased the commercial database from MaxMind, you can point the freegeoip web server or Go API to the URL of it, or local file, and the server will use it.

In case of files on disk, you can replace with a new version and the freegeoip software will load it automatically. URLs are frequently checked in background, and if a new version of the database is available it is loaded automatically also.

API

The freegeoip API is served by endpoints that encode the response in different formats.

Example:

curl freegeoip.net/json/

Returns the geolocation information of your own IP address, the source IP address of the connection.

You can pass a different IP or hostname:

curl freegeoip.net/json/github.com

To lookup the geolocation of github.com after resolving its IP address, which might be IPv4 or IPv6.

Responses can also be encoded as JSONP, by adding the callback parameter:

curl freegeoip.net/json/?callback=foobar

Same semantics are available for the /xml/{ip} and /csv/{ip} endpoints except the callback parameter.

Metrics and profiling

The freegeoip web server can provide metrics about its usage, and also supports runtime profiling.

Both are disabled by default, but can be enabled by passing the -internal-server=:8081 parameter in the command line. Metrics are generated for Prometheus and can be queried at /metrics even with curl.

HTTP pprof is available at /debug/pprof and the examples from the pprof package work.

Package freegeoip

The freegeoip package for the Go programming language provides two APIs:

• A database API that requires zero maintenance of the IP database;
• A geolocation http.Handler that can be used/served by any http server.

tl;dr if all you want is code then see the example_test.go file.

Otherwise check out the godoc reference.

Features

• Zero maintenance

The DB object alone can download an IP database file from the internet and service lookups to your program right away. It will auto-update the file in background and always magically work.

• DevOps friendly

If you do care about the database and have the commercial version of the MaxMind database, you can update the database file with your program running and the DB object will load it in background. You can focus on your stuff.

• Extensible

Besides the database part, the package provides an http.Handler object that you can add to your HTTP server to service IP geolocation lookups with the same simplistic API of freegeoip.net. There's also an interface for crafting your own HTTP responses encoded in any format.

Install

Download the package:

go get -d github.com/fiorix/freegeoip

Install the web server:

go install github.com/fiorix/freegeoip/cmd/freegeoip

Test coverage is quite good and tests may help you find the stuff you need.

Documentation

Overview

Package freegeoip provides an API for searching the geolocation of IP addresses. It uses a database that can be either a local file or a remote resource from a URL.

Local databases are monitored by fsnotify and reloaded when the file is either updated or overwritten.

Remote databases are automatically downloaded and updated in background so you can focus on using the API and not managing the database.

Also, the freegeoip package provides http handlers that any Go http server (net/http) can use. These handlers can process IP geolocation lookup requests and return data in multiple formats like CSV, XML, JSON and JSONP. It has also an API for supporting custom formats.

Index

• Variables
• func ProxyHandler(f http.Handler) http.Handler
• type CSVEncoder
  • func (f *CSVEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error
  • func (f *CSVEncoder) NewQuery() Query
• type DB
  • func Open(dsn string) (db *DB, err error)
  • func OpenURL(url string, updateInterval, maxRetryInterval time.Duration) (db *DB, err error)
  • func (db *DB) Close()
  • func (db *DB) Date() time.Time
  • func (db *DB) Lookup(addr net.IP, result interface{}) error
  • func (db *DB) NotifyClose() <-chan struct{}
  • func (db *DB) NotifyError() (errChan <-chan error)
  • func (db *DB) NotifyOpen() (filename <-chan string)
• type Encoder
• type Handler
  • func NewHandler(db *DB, enc Encoder) *Handler
  • func (f *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type JSONEncoder
  • func (f *JSONEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error
  • func (f *JSONEncoder) NewQuery() Query
  • func (f *JSONEncoder) P(w http.ResponseWriter, r *http.Request, record *responseRecord, ...) error
• type Query
• type XMLEncoder
  • func (f *XMLEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error
  • func (f *XMLEncoder) NewQuery() Query

Variables

var (
	// ErrUnavailable may be returned by DB.Lookup when the database
	// points to a URL and is not yet available because it's being
	// downloaded in background.
	ErrUnavailable = errors.New("no database available")
)

Functions

func ProxyHandler

func ProxyHandler(f http.Handler) http.Handler

ProxyHandler is a wrapper for other http handlers that sets the client IP address in request.RemoteAddr to the first value of a comma separated list of IPs from the X-Forwarded-For request header. It resets the original RemoteAddr back after running the designated handler f.

Types

type CSVEncoder

type CSVEncoder struct {
	UseCRLF bool
}

CSVEncoder encodes the results of an IP lookup as CSV.

func (*CSVEncoder) Encode

func (f *CSVEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error

Encode implements the Encoder interface.

func (*CSVEncoder) NewQuery

func (f *CSVEncoder) NewQuery() Query

NewQuery implements the Encoder interface.

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB is the IP geolocation database.

func Open

func Open(dsn string) (db *DB, err error)

Open creates and initializes a DB from a local file.

The database file is monitored by fsnotify and automatically reloads when the file is updated or overwritten.

func OpenURL

func OpenURL(url string, updateInterval, maxRetryInterval time.Duration) (db *DB, err error)

OpenURL creates and initializes a DB from a remote file. It automatically downloads and updates the file in background, and keeps a local copy on $TMPDIR.

func (*DB) Close

func (db *DB) Close()

Close the database.

func (*DB) Date

func (db *DB) Date() time.Time

Date returns the UTC date the database file was last modified. If no database file has been opened the behaviour of Date is undefined.

func (*DB) Lookup

func (db *DB) Lookup(addr net.IP, result interface{}) error

Lookup takes an IP address and a pointer to the result value to decode into. The result value pointed to must be a data value that corresponds to a record in the database. This may include a struct representation of the data, a map capable of holding the data or an empty interface{} value.

If result is a pointer to a struct, the struct need not include a field for every value that may be in the database. If a field is not present in the structure, the decoder will not decode that field, reducing the time required to decode the record.

See https://godoc.org/github.com/oschwald/maxminddb-golang#Reader.Lookup for details.

func (*DB) NotifyClose

func (db *DB) NotifyClose() <-chan struct{}

NotifyClose returns a channel that is closed when the database is closed.

func (*DB) NotifyError

func (db *DB) NotifyError() (errChan <-chan error)

NotifyError returns a channel that notifies when an error occurs while downloading or reloading a DB that points to a URL.

func (*DB) NotifyOpen

func (db *DB) NotifyOpen() (filename <-chan string)

NotifyOpen returns a channel that notifies when a new database is loaded or reloaded. This can be used to monitor background updates when the DB points to a URL.

type Encoder

type Encoder interface {
	// NewQuery returns a query specification that is used to query
	// the IP database. It should be a data structure with tags
	// associated to its fields describing what fields to query in
	// the IP database, such as country and city.
	//
	// See the maxminddb package documentation for details on
	// fields available for the MaxMind database.
	NewQuery() Query

	// Encode writes data to the response of an http request
	// using the results of a query to the IP database.
	//
	// It encodes the query object into a specific format such
	// as XML or JSON and writes to the response.
	//
	// The IP passed to the encoder may be the result of a DNS
	// lookup, and if there are multiple IPs associated to the
	// hostname this will be a random one from the list.
	Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error
}

An Encoder that can provide a query specification to be used for querying the IP database, and later encode the results of that query in a specific format.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

A Handler provides http handlers that can process requests and return data in multiple formats.

Usage:

handle := NewHandler(db)
http.Handle("/json/", handle.JSON())

Note that the url pattern must end with a trailing slash since the handler looks for IP addresses or hostnames as parameters, for example /json/8.8.8.8 or /json/domain.com.

If no IP or hostname is provided, then the handler will query the IP address of the caller. See the ProxyHandler for more.

func NewHandler

func NewHandler(db *DB, enc Encoder) *Handler

NewHandler creates and initializes a new Handler.

func (*Handler) ServeHTTP

func (f *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

type JSONEncoder

type JSONEncoder struct {
	Indent bool
}

JSONEncoder encodes the results of an IP lookup as JSON.

func (*JSONEncoder) Encode

func (f *JSONEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error

Encode implements the Encoder interface.

func (*JSONEncoder) NewQuery

func (f *JSONEncoder) NewQuery() Query

NewQuery implements the Encoder interface.

func (*JSONEncoder) P

func (f *JSONEncoder) P(w http.ResponseWriter, r *http.Request, record *responseRecord, callback string) error

P writes JSONP to an http response.

type Query

type Query interface{}

A Query object is used to query the IP database.

Currently the only database supported is MaxMind, and the query is a data structure with tags that are used by the maxminddb.Lookup function.

type XMLEncoder

type XMLEncoder struct {
	Indent bool
}

XMLEncoder encodes the results of an IP lookup as XML.

func (*XMLEncoder) Encode

func (f *XMLEncoder) Encode(w http.ResponseWriter, r *http.Request, q Query, ip net.IP) error

Encode implements the Encoder interface.

func (*XMLEncoder) NewQuery

func (f *XMLEncoder) NewQuery() Query

NewQuery implements the Encoder interface.