forked from g-andrade/locus
-
Notifications
You must be signed in to change notification settings - Fork 0
/
overview.edoc
159 lines (123 loc) · 7.35 KB
/
overview.edoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@title locus
@doc
<!--[](https://travis-ci.org/g-andrade/locus)-->
[](https://hex.pm/packages/locus)
== locus - Geolocation and ASN lookup of IP addresses using MaxMind GeoIP2 ==
`locus' is library for Erlang/OTP and Elixir that allows you to pinpoint the country,
city or ASN of IPv4 and IPv6 addresses.
The free <a href="https://dev.maxmind.com/geoip/geoip2/geolite2/">MaxMind databases</a> you choose
are downloaded on-demand, cached on the filesystem and updated automatically.
You're encouraged to host your own private copies of the databases when using this library in production,
both for reliability and netiquette towards MaxMind.
=== Usage ===
Run `make console' to bring up a shell.
==== 1. Start the database loader ====
<pre lang="erlang">
URL = "https://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.tar.gz",
ok = locus:start_loader(country, URL).
</pre>
==== 2. Wait for the database to load (optional) ====
<pre lang="erlang">
% Either block indefinitely
{ok, _DatabaseVersion} = locus:wait_for_loader(country).
</pre>
<pre lang="erlang">
% ... or give-up after 30 seconds
{ok, _DatabaseVersion} = locus:wait_for_loader(country, 30000). % {error,timeout}
</pre>
==== 3. Lookup IP addresses ====
<pre lang="erlang">
<![CDATA[
% > locus:lookup(country, "93.184.216.34").
% > locus:lookup(country, "2606:2800:220:1:248:1893:25c8:1946").
{ok,#{<<"continent">> =>
#{<<"code">> => <<"NA">>,
<<"geoname_id">> => 6255149,
<<"names">> =>
#{<<"de">> => <<"Nordamerika">>,
<<"en">> => <<"North America">>,
<<"es">> => <<"Norteamérica"/utf8>>,
<<"fr">> => <<"Amérique du Nord"/utf8>>,
<<"ja">> => <<"北アメリカ"/utf8>>,
<<"pt-BR">> => <<"América do Norte"/utf8>>,
<<"ru">> => <<"Северная Америка"/utf8>>,
<<"zh-CN">> => <<"北美洲"/utf8>>}},
<<"country">> =>
#{<<"geoname_id">> => 6252001,
<<"iso_code">> => <<"US">>,
<<"names">> =>
#{<<"de">> => <<"USA">>,
<<"en">> => <<"United States">>,
<<"es">> => <<"Estados Unidos">>,
<<"fr">> => <<"États-Unis"/utf8>>,
<<"ja">> => <<"アメリカ合衆国"/utf8>>,
<<"pt-BR">> => <<"Estados Unidos">>,
<<"ru">> => <<"США"/utf8>>,
<<"zh-CN">> => <<"美国"/utf8>>}},
<<"registered_country">> =>
#{<<"geoname_id">> => 6252001,
<<"iso_code">> => <<"US">>,
<<"names">> =>
#{<<"de">> => <<"USA">>,
<<"en">> => <<"United States">>,
<<"es">> => <<"Estados Unidos">>,
<<"fr">> => <<"États-Unis"/utf8>>,
<<"ja">> => <<"アメリカ合衆国"/utf8>>,
<<"pt-BR">> => <<"Estados Unidos">>,
<<"ru">> => <<"США"/utf8>>,
<<"zh-CN">> => <<"美国"/utf8>>}}}}
]]>
</pre>
Check the <a href="#modules">function reference</a> for an overview on everything you can do.
=== Details ===
==== Requirements ====
* Erlang/OTP 19.3 or higher
* rebar3
==== On databases ====
* The free GeoLite2 <a href="https://dev.maxmind.com/geoip/geoip2/geolite2/">Country, City and ASN databases</a>
were all successfully tested; presumably `locus' can deal with any MaxMind DB -formatted database that maps
IP address prefixes to arbitrary data, but no <a href="https://dev.maxmind.com/geoip/geoip2/downloadable/">
commercial databases</a> have yet been tested
* The databases are loaded into memory (mostly) as-is; reference counted binaries are shared with the
application callers using ETS tables, and the original binary search tree is used to lookup addresses.
The data for each entry is decoded on the fly upon successful lookups.
==== On formats ====
* Only gzip-compressed tarballs are supported at this moment
* The first file to be found, within the tarball, with an .mmdb extension, is the one that's chosen for loading
* The implementation of <a href="https://maxmind.github.io/MaxMind-DB/">MaxMind DB format</a> is mostly complete
==== On downloading and updating ====
* The downloaded tarballs are uncompressed in memory
* The 'last-modified' response header, if present, is used to condition subsequent download
attempts (using 'if-modified-since' request headers) in order to save bandwidth
* The downloaded tarballs are cached on the filesystem in order to more quickly achieve readiness
on future launches of the database loader
* Until the database loader achieves readiness, download attempts are made every minute;
once readiness is achieved (either from cache or network), this interval increases to every 6 hours
==== On caching ====
* Caching is a best-effort; the system falls back to relying exclusively on the network if needed
* A caching directory named 'locus_erlang' is created under the <a href="http://erlang.org/doc/man/filename#basedir-3">'user_cache' basedir</a>
* Cached tarballs are named after the SHA256 hash of their source URL
* Modification time of the tarballs is extracted from 'last-modified' response header (when present)
and used to condition downloads on subsequent boots and save bandwidth
==== On logging ====
* Four logging levels are supported: `info', `warning', `error' and `none'
* The backend is <a href="http://erlang.org/doc/man/error_logger">error_logger</a>; this usually plays nicely with `lager'
* The default log level is `error'; it can be changed in the application's `env' config
* To tweak the log level in runtime, use `locus_logger:set_loglevel/1'
=== Alternatives (Erlang) ===
* <a href="https://github.com/mochi/egeoip">egeoip</a>: IP Geolocation module, currently supporting the MaxMind GeoLite City Database
* <a href="https://github.com/brigadier/geodata2">geodata2</a>: Application for working with MaxMind geoip2 (.mmdb) databases
* <a href="https://github.com/manifest/geoip">geoip</a>: Returns the location of an IP address; based on the ipinfodb.com web service
* <a href="https://hex.pm/packages/geolite2data">geolite2data</a>: Periodically fetches the free MaxMind GeoLite2 databases
* <a href="https://github.com/ip2location/ip2location-erlang">ip2location-erlang</a>: Uses IP2Location geolocation database
=== Alternatives (Elixir) ===
* <a href="https://hex.pm/packages/asn">asn</a>: IP-to-AS-to-ASname lookup
* <a href="https://hex.pm/packages/freegeoip">freegeoip</a>: Simple wrapper for freegeoip.net HTTP API
* <a href="https://hex.pm/packages/freegeoipx">freegeoipx</a>: API Client for freegeoip.net
* <a href="https://hex.pm/packages/geoip">geoip</a>: Lookup the geo location for a given IP address, hostname or Plug.Conn instance
* <a href="https://hex.pm/packages/geolix">geolix</a>: MaxMind GeoIP2 database reader/decoder
* <a href="https://hex.pm/packages/plug_geoip2">plug_geoip2</a>: Adds geo location to a Plug connection based upon the client IP address by using MaxMind's GeoIP2 database
* <a href="https://hex.pm/packages/tz_world">tz_world</a>: Resolve timezones from a location efficiently using PostGIS and Ecto
=== Disclosure ===
`locus' is an independent project and has not been authorized, sponsored, or otherwise approved by MaxMind.
@end