README.rst

   1 A simple python replacement for the MaxMind geoipupdate program
   2
   3 Introduction
   4 ============
   5
   6 MaxMind publishes several `GeoIP databases
   7 <https://dev.maxmind.com/geoip>`_ that associate geographical
   8 locations with IP addresses. To keep those databases updated, they
   9 provide a utility called `geoipupdate
  10 <https://github.com/maxmind/geoipupdate>`_.
  11
  12 The geoipupdate client was originally in C but has now been rewritten
  13 in Go. That has several downsides from system administration and
  14 security standpoints that we need not repeat here. As a result, it's
  15 nice to have a simple python client that can update the databases,
  16 perhaps at the expense of a few bells and whistles. That's what
  17 geoipyupdate is.
  18
  19 To use it, you will still need a MaxMind account because your account
  20 id and license key are required to access the files. A `free option
  21 <https://dev.maxmind.com/geoip/geolite2-free-geolocation-data>`_ is
  22 available. For more details... go bother MaxMind. The intended
  23 audience for geoipyupdate is system administrators who already know
  24 what these databases are and how to use them.
  25
  26
  27 Configuration
  28 =============
  29
  30 geoipyupdate has a configuration file just like the official client,
  31 except ours is in `TOML <https://en.wikipedia.org/wiki/TOML>`_ format.
  32 The default location for the file is
  33 ``$XDG_CONFIG_HOME/geoipyupdate/geoipyupdate.conf`` but you can change
  34 that with the ``--config-file`` flag. A sample configuration is
  35 included in the source tarballs.
  36
  37 Because geoipyupdate is supposed to be *simple*, there are several
  38 things you cannot configure it to do:
  39
  40 - Download from anywhere but updates.maxmind.com
  41 - Use a proxy
  42 - Mess with the modification times of the databases
  43 - Retry failed downloads
  44 - Use a lock file (use `lockrun
  45   <http://www.unixwiz.net/tools/lockrun.html>`_ to prevent
  46   simultaneous runs)
  47 - Download in parallel
  48
  49 Sorry :)