letstool/http2mac repository overview

⁠http2mac

Lightweight HTTP gateway that looks up MAC addresses against the IEEE OUI database through a JSON REST API.

Send a POST /api/v1/mac request with one or more MAC addresses, get back structured JSON telling you whether each address is registered — and if so, the organisation name, address, country, assignment type (MA-L, MA-M, MA-S, CID, IAB), block range, virtualisation hint, and whether the address is UAA (Universally Administered) or LAA (Locally Administered).

The database is built automatically from a gzipped CSV served by the letstool CDN and refreshed every 4 hours. No MaxMind license, no IEEE account, no manual setup.

The binary embeds a web UI (dark/light mode, 15 languages, RTL support) and an OpenAPI 3.1 spec — no external files, no runtime dependencies.

⁠Quick start

docker run -p 8080:8080 letstool/http2mac:latest

Open http://localhost:8080⁠ to use the web UI, or query the API directly:

# Check a single MAC address
curl -s -X POST http://localhost:8080/api/v1/mac \
  -H "Content-Type: application/json" \
  -d '{"mac":"00:11:22:33:44:55"}' | jq

# Check multiple MAC addresses at once
curl -s -X POST http://localhost:8080/api/v1/mac \
  -H "Content-Type: application/json" \
  -d '{"macs":["00:11:22:33:44:55","AA-BB-CC-DD-EE-FF","0011.2233.4455"]}' | jq

Example response:

{
  "status": "SUCCESS",
  "answers": [
    {
      "mac": "00:11:22:33:44:55",
      "valid": true,
      "type": "Unicast",
      "admin_type": "UAA",
      "registered": true,
      "oui": "00:11:22",
      "organisation_name": "Cimsys Inc",
      "organization_address": "Daejeon, Daejeon, 305-350",
      "country_code": "KR",
      "address_min": "00:11:22:00:00:00",
      "address_max": "00:11:22:ff:ff:ff",
      "block_size": 16777216,
      "assignment": "MA-L",
      "virtual": "False"
    },
    {
      "mac": "aa:bb:cc:dd:ee:ff",
      "valid": true,
      "type": "Unicast",
      "admin_type": "LAA",
      "registered": false
    }
  ]
}

Accepted MAC formats:

• xx:xx:xx:xx:xx:xx — Linux colon-separated
• xx-xx-xx-xx-xx-xx — Windows hyphen-separated
• xx.xx.xx.xx.xx.xx — dot-separated per-byte
• xxxx.xxxx.xxxx — Cisco three-group
• xxxxxxxxxxxx — no separator (12 hex digits)

All formats are normalised to lowercase xx:xx:xx:xx:xx:xx in the response.

⁠Configuration

CLI flags take priority over environment variables.

Proxy is supported via the standard HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables (same behaviour as curl).

docker run -p 8080:8080 \
  -v ./db:/data:rw \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  letstool/http2mac:latest

⁠Peer sync mode

Set MAC_DB_URL to another running http2mac instance to download the database directly from its /db/mac endpoint instead of fetching from the CDN. Useful for air-gapped environments or clusters where only one node hits the CDN.

docker run -p 8080:8080 \
  -e MAC_DB_URL=http://upstream-host:8080 \
  -v ./db:/data:rw \
  letstool/http2mac:latest

⁠Persistent storage

Mount a volume to /data to cache the database across container restarts:

docker run -p 8080:8080 \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  -v ./db:/data:rw \
  letstool/http2mac:latest

On restart, if the cached mac.mmdb is recent enough, it is reloaded immediately without refetching.

⁠Repo

https://github.com/letstool/http2mac⁠

⁠License

This project is licensed under the Apache License, Version 2.0⁠.

Copyright (c) 2026 letstool.net

⁠See also

Data sourced from the IEEE Registration Authority⁠. This project is not affiliated with or endorsed by IEEE.