DOCSEARCHbyAlgolia
Submit Docs

MMDB CLI

website·Indexed 31 days ago

https://docs.infraz.io

A command-line tool developed by InfraZ to simplify working with MaxMind DB (MMDB) files. It provides capabilities to generate MMDB files from JSON datasets, update existing databases, inspect IP addresses or CIDR prefixes, dump databases to files, and verify file integrity.

Tokens
7.9K
Snippets
58
Records
69
Agent score
50%

What's inside MMDB CLI

  1. Overview of MMDB CLI

    MMDB CLI (mmdb-cli) is an open-source command-line tool designed to simplify the management of MMDB (MaxMind Database) files. MMDB is a binary search tree format used to map IPv4 and IPv6 addresses to specific data records. The CLI allows users to perform database operations without writing custom code.

  2. Overview of MMDB CLI Core Commands

    The MMDB CLI provides a suite of commands to manage and inspect MaxMind DB (MMDB) files. Core capabilities include viewing metadata, looking up IP/CIDR data, exporting databases, generating new MMDB files from JSON, updating existing files, verifying file validity, and comparing two files (experimental).
    # Get general help and a list of available commands
mmdb-cli --help

  3. Supported Platforms for MMDB CLI

    MMDB CLI provides pre-built binaries for the following OS and architecture combinations: Linux (amd64, arm64), macOS (amd64, arm64), FreeBSD (amd64, arm64), and Windows (amd64, arm64). If a platform is not listed, the tool can be built from source.

  4. General MMDB CLI usage and help

    The mmdb-cli tool provides a suite of commands for MMDB manipulation. Use the --help flag or the help command to get more information about specific commands.
    mmdb-cli --help
mmdb-cli [command] --help
mmdb-cli version
mmdb-cli completion [shell]

  5. Install MMDB CLI on Debian or Ubuntu

    Download and install the .deb package for the appropriate architecture (amd64 or arm64) from GitHub Releases.
    export MMDB_CLI_VERSION=$(curl -s https://api.github.com/repos/InfraZ/mmdb-cli/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
export ARCH=$(dpkg --print-architecture)

curl -LO "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.deb"
apt install ./mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.deb

mmdb-cli version

  6. Use JSONPath templates for custom mmdb-cli output

    The mmdb-cli tool allows custom output formatting using the -f or --format flag with the value jsonpath={TEMPLATE}. This feature is supported only for the inspect and dump commands. Templates use the Kubernetes JSONPath engine (Go templates wrapped in {...} braces), not the Goessner syntax. To prevent the shell from expanding special characters like $, `, or ?, always wrap the -f value in single quotes.
    # Example: Extract networks from an inspection
mmdb-cli inspect -i db.mmdb -f 'jsonpath={range .items[*]}{.network}{"\n"}{end}' 1.1.1.1

# Example: Extract networks to a file via dump
mmdb-cli dump -i db.mmdb -o networks.txt -f 'jsonpath={range .items[*]}{.network}{"\n"}{end}'

  7. Install MMDB CLI on RHEL, Fedora, CentOS, Rocky, or AlmaLinux

    Install the .rpm package using dnf or yum by pointing to the GitHub Releases URL.
    export MMDB_CLI_VERSION=$(curl -s https://api.github.com/repos/InfraZ/mmdb-cli/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH=amd64; [ "$ARCH" = "aarch64" ] && ARCH=arm64

dnf install "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.rpm"

mmdb-cli version

  8. Filter mmdb-cli diff results by IP or CIDR scope

    You can limit the comparison to specific networks by providing one or more IP addresses or CIDR prefixes as optional arguments. When scopes are provided, only networks within those ranges are compared; all others are ignored. Multiple scopes are unioned and deduplicated. A bare IP address is treated as a host route (/32 for IPv4, /128 for IPv6).
    # Scope to a CIDR
mmdb-cli diff file-a.mmdb file-b.mmdb 1.0.0.0/8

# Scope to a specific IP
mmdb-cli diff file-a.mmdb file-b.mmdb 1.1.1.1

# Scope to multiple ranges
mmdb-cli diff file-a.mmdb file-b.mmdb 1.1.1.1 8.8.8.0/24

  9. Example: Update GeoLite2-ASN.mmdb with custom data

    This example demonstrates how to use deep_merge to add attributes to a specific IP and top_level_merge to add a flag to another IP in an existing MMDB file.
    // update-data.json
{
  "version": "v1",
  "dataset": [
    {
      "network": "1.1.1.1/32",
      "method": "deep_merge",
      "data": {
        "is_cloudflare": true,
        "attributes": {
          "country": "US",
          "city": "San Francisco"
        }
      }
    },
    {
      "network": "8.8.8.8/32",
      "method": "top_level_merge",
      "data": {
        "is_google": true
      }
    }
  ]
}
    mmdb-cli update -i GeoLite2-ASN.mmdb -o GeoLite2-ASN-Updated.mmdb -d update-data.json

  10. Install MMDB CLI on macOS using Homebrew

    Install the MMDB CLI on macOS by tapping the InfraZ Homebrew repository. If macOS Gatekeeper blocks the binary because it is not Apple-notarized, you must manually remove the quarantine attribute using xattr.
    # Install via Homebrew
brew tap infraz/tap
brew install infraz/tap/mmdb-cli

# Verify installation
mmdb-cli version

# Fix macOS Gatekeeper block if necessary
xattr -dr com.apple.quarantine "$(which mmdb-cli)"

  11. Build MMDB CLI from source

    To build the MMDB CLI from source, you must have Git and Go (version 1.26 or higher) installed on your local machine. The process involves cloning the repository, downloading Go module dependencies, and compiling the binary using the Go toolchain.
    # 1. Clone the repository
git clone https://github.com/InfraZ/mmdb-cli.git
cd mmdb-cli

# 2. Download dependencies
go mod download -x

# 3. Build the binary
go build -o mmdb-cli .

# 4. Verify the installation
./mmdb-cli version

  12. Compare two MMDB files using mmdb-cli diff

    The diff command compares network records between two MMDB files and reports added, removed, and modified networks. It ignores database metadata (like BuildEpoch or NodeCount) and focuses solely on the network records. The output uses a unified-diff-inspired format on stdout. Note that this command is experimental and its flags or output format may change without following semantic versioning.
    mmdb-cli diff <FILE_A.mmdb> <FILE_B.mmdb> [IP_OR_CIDR ...]