DOCSEARCHbyAlgolia
Submit Docs

GeoIP Update

repository·main·Indexed 19 days ago

https://github.com/maxmind/geoipupdate

A utility for performing automatic updates of MaxMind's GeoIP and GeoLite binary databases. Compatible with Linux, macOS, and Windows, it supports configuration via GeoIP.conf, command-line flags, and environment variables. It can be deployed as a standalone binary, via package managers (apt, rpm, brew), or as a Docker container.

Tokens
4.6K
Snippets
16
Records
27
Agent score
75%

What's inside geoipupdate

  1. Handle proxy settings in geoipupdate

    main

    If you need to use a proxy server to reach the MaxMind update servers, you can configure it in one of three ways:

    1. Configuration File: Update your GeoIP.conf file (refer to the GeoIP.conf documentation for specific syntax).
    2. Environment Variable: Set the GEOIPUPDATE_PROXY environment variable.
    3. Standard Proxy Variable: Set the http_proxy environment variable.

  2. Default configuration and database paths

    main

    GeoIP Update uses specific default paths for its configuration file and database directory depending on the installation method. If these defaults are unsuitable, they can be overridden at build time using Go linker flags.

    Default Paths by Installation Type:

    • Linux Tarball: /usr/local/etc/GeoIP.conf
    • Ubuntu/Debian (.deb): /etc/GeoIP.conf
    • RedHat/CentOS (.rpm): /etc/GeoIP.conf
    • Windows: \ProgramData\MaxMind\GeoIPUpdate\GeoIP.conf

    Customizing defaults at build time: Use -ldflags to set main.defaultConfigFile and main.defaultDatabaseDirectory.

    go build -ldflags "-X main.defaultConfigFile=/etc/GeoIP.conf -X main.defaultDatabaseDirectory=/usr/share/GeoIP"

  3. Install GeoIP Update on macOS

    main

    Via Tarball

    1. Download and extract the tarball containing "darwin" in the filename.
    2. Copy the geoipupdate binary to your desired location.

    Via Homebrew

    If you have Homebrew installed, run:

    brew install geoipupdate
    brew install geoipupdate

  4. Install GeoIP Update on Linux

    main

    You can install GeoIP Update on Linux using several methods depending on your distribution and preference:

    Via Tarball

    1. Download and extract the appropriate tarball for your architecture.
    2. Copy the geoipupdate binary to your desired location (e.g., /usr/local/bin/).
    3. Default Config Path: /usr/local/etc/GeoIP.conf.

    Via Ubuntu PPA

    Add the MaxMind PPA and install via apt:

    sudo add-apt-repository ppa:maxmind/ppa
sudo apt update
sudo apt install geoipupdate

    Via .deb (Ubuntu/Debian)

    1. Download the appropriate .deb package.
    2. Install using dpkg (requires root/sudo): sudo dpkg -i path/to/geoipupdate_VERSION_ARCH.deb
    3. Default Config Path: /etc/GeoIP.conf.

    Via .rpm (RedHat/CentOS)

    1. Download the appropriate .rpm package.
    2. Install using rpm (requires root): sudo rpm -Uvhi path/to/geoipupdate_VERSION_ARCH.rpm
    3. Default Config Path: /etc/GeoIP.conf.
    sudo add-apt-repository ppa:maxmind/ppa
sudo apt update
sudo apt install geoipupdate

  5. Run geoipupdate using docker run

    main

    To run the latest geoipupdate image, use docker run. You must provide an environment file containing your configuration and mount a local directory to /usr/share/GeoIP to persist the downloaded databases.

    docker run --env-file <file> -v <database directory>:/usr/share/GeoIP ghcr.io/maxmind/geoipupdate
    • <file>: Path to your environment variable file.
    • <database directory>: The local directory where you want the databases to be stored.

  6. Install GeoIP Update via Docker or Proto

    main

    Via Proto

    Use the Proto toolchain manager to add the plugin and install:

    proto plugin add geoipupdate "https://raw.githubusercontent.com/maxmind/geoipupdate/refs/heads/main/proto.yaml"
proto install geoipupdate

    Via Docker

    Refer to the dedicated Docker documentation for instructions.

    proto plugin add geoipupdate "https://raw.githubusercontent.com/maxmind/geoipupdate/refs/heads/main/proto.yaml"
proto install geoipupdate

  9. Install GeoIP Update from source

    main

    To build from source, you need the Go compiler (version 1.25+). The easiest method is using go install:

    go install github.com/maxmind/geoipupdate/v8/cmd/geoipupdate@latest

    This installs the binary to $GOPATH/bin/geoipupdate.

    go install github.com/maxmind/geoipupdate/v8/cmd/geoipupdate@latest

  10. Run geoipupdate via CLI

    main
    The geoipupdate tool is a command-line utility designed to perform automatic updates of MaxMind GeoIP binary databases. It can be configured via a configuration file or through command-line arguments to specify the config file path, the database directory, parallelism levels, and output verbosity.
    geoipupdate

  11. Configure the GeoIP.conf file

    main

    The GeoIP.conf file is used to configure the geoipupdate program to download GeoIP and GeoLite databases.

    Format Rules:

    • One setting per line.
    • Lines starting with # are comments and are ignored.
    • All setting keywords are case sensitive.

    Most configuration settings in this file can be overridden at runtime using environment variables or command-line arguments.

    # Example GeoIP.conf
AccountID: YOUR_ACCOUNT_ID
LicenseKey: YOUR_LICENSE_KEY
EditionIDs: GeoIP2-City GeoIP2-Country
DatabaseDirectory: /var/lib/GeoIP

  12. Configure geoipupdate via Docker environment variables

    main

    When running geoipupdate in a container, you can provide configuration via environment variables. Environment variables override any settings found in a configuration file.

    Required Variables

    You must provide exactly one method for the Account ID, one for the License Key, and a list of Edition IDs:

    • Edition IDs: GEOIPUPDATE_EDITION_IDS (space-separated list, e.g., GeoLite2-ASN GeoLite2-City).
    • Account ID: Either GEOIPUPDATE_ACCOUNT_ID (the ID itself) or GEOIPUPDATE_ACCOUNT_ID_FILE (path to a file containing the ID).
    • License Key: Either GEOIPUPDATE_LICENSE_KEY (the case-sensitive key) or GEOIPUPDATE_LICENSE_KEY_FILE (path to a file containing the key).

    Optional Variables

    • GEOIPUPDATE_FREQUENCY: Hours between runs. If 0 or unset, the container runs once and exits.
    • GEOIPUPDATE_HOST: Server hostname (default: https://updates.maxmind.com).
    • GEOIPUPDATE_PROXY: Proxy host/IP (e.g., 127.0.0.1:8888). Defaults to port 1080 if not specified.
    • GEOIPUPDATE_PROXY_USER_PASSWORD: Proxy credentials in username:password format.
    • GEOIPUPDATE_PRESERVE_FILE_TIMES: Set to 1 to preserve modification times, 0 to disable (default: 0).
    • GEOIPUPDATE_VERBOSE: Set to 1 to enable verbose logging.
    • GEOIPUPDATE_DB_DIR: Directory for downloaded databases (default: /usr/share/GeoIP).