AiFw

Geo-IP

AiFw maps countries to pf tables and emits one block drop or pass quick rule per country. The country list is sourced from MaxMind’s free GeoLite2 CSV release; AiFw aggregates adjacent CIDRs to keep the pf tables compact. Each rule takes a 2-letter ISO 3166-1 alpha-2 code and an action (allow or block). Rules live in the dedicated aifw-geoip anchor.

Quickstart

In the Web UI go to Firewall → Geo-IP and click Add rule. Pick a country, an action (block or allow), and an optional label.

Block all inbound traffic from a country:

curl -X POST https://aifw.local/api/v1/geoip \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "country": "CN", "action": "block", "label": "block-cn" }'

Look up which country an IP belongs to:

curl https://aifw.local/api/v1/geoip/lookup/1.2.3.4 \
  -H "Authorization: Bearer $TOKEN"

Response:

{ "ip": "1.2.3.4", "country": "AU", "network": "1.0.0.0/8" }

CLI

aifw geoip add --country CN --action block
aifw geoip add --country US --action allow
aifw geoip lookup 1.2.3.4
aifw geoip list
aifw geoip remove <uuid>

API endpoints

Method Endpoint Description
GET /api/v1/geoip List geo-IP rules
POST /api/v1/geoip Create a rule
PUT /api/v1/geoip/{id} Update a rule
DELETE /api/v1/geoip/{id} Delete a rule
GET /api/v1/geoip/lookup/{ip} Resolve an IP to its country code

How it works

Each rule generates a pf table named geoip_<cc> (e.g. geoip_cn, geoip_ru) populated with the country’s networks from the GeoLite2 database. The compiled pf rule is:

block drop in quick from <geoip_cn> label "geoip-block-CN"

pass-action rules use pass in quick. Adjacent and overlapping CIDRs are merged before being loaded into the table so a country’s table stays small enough to evaluate cheaply.

Configuration

Field Default Notes
Anchor name aifw-geoip Dedicated anchor, separate from the main rule list
db_path /var/db/aifw/geoip GeoLite2 CSV directory
update_interval_hours 168 (weekly) Set to 0 to disable auto-update
license_key unset Optional MaxMind license key for direct downloads
country (rule) required Two-letter ISO 3166-1 alpha-2 code; case-insensitive on input

See also

Last updated: