docs: Add GeoIP ASN support (T5746)

[Firefishy]

Change Summary

Add documentation for GeoIP ASN firewall support

Related Task(s)

• https://vyos.dev/T5746

Related PR(s)

vyos/vyos-1x#5155

Backport

Checklist:

• I have read the CONTRIBUTING document

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 7e0c41b7-5572-4034-a7f5-bd9e8c5c6ddc

📥 Commits

Reviewing files that changed from the base of the PR and between b4a7df3 and d5bc39b.

📒 Files selected for processing (2)

• docs/configuration/firewall/ipv4.md
• docs/configuration/firewall/ipv6.md

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Expanded firewall GeoIP guidance for IPv4 and IPv6 with new ASN-based match examples for source and destination rules.
  • Updated matching criteria examples across common rule chains, including custom-named rules.
  • Clarified that GeoIP matching can use either country codes or ASNs, and that inverse matching excludes both.

Walkthrough

IPv4 and IPv6 firewall GeoIP documentation now includes geoip asn examples for source and destination matching across forward, input, output, and named rules. The inverse-match text was updated in both guides to cover country codes and ASNs.

Changes

GeoIP ASN documentation update

Layer / File(s)	Summary
IPv4 GeoIP ASN matching docs docs/configuration/firewall/ipv4.md	Adds source geoip asn and destination geoip asn examples at lines 533-544 and 557-568, and updates GeoIP prose at lines 593-594 to include ASN matching and ASN-aware inverse-match.
IPv6 GeoIP ASN matching docs docs/configuration/firewall/ipv6.md	Adds source geoip asn and destination geoip asn examples at lines 534-545 and 558-569, and updates inverse-match prose at lines 595-596 to exclude both country codes and ASNs.

Sequence Diagram(s)

Not applicable.

Estimated code review effort: Low

Related issues: None specified

Related PRs: None specified

Suggested labels: documentation

Suggested reviewers: None specified

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Matches the change: docs/configuration/firewall/ipv4.md and ipv6.md add GeoIP ASN matching syntax and wording updates.
Description check	✅ Passed	The description is on-topic and accurately states the documentation update for GeoIP ASN firewall support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[github-actions]

Claude finished @Firefishy's task in 3m 1s —— View job

---

PR Review: Add GeoIP ASN support (T5746)

• Read PR diff and pass1-findings.json (findings empty)
• Cross-reference geoip asn against .vyos-1x sources (XML + Python)
• Verify ASN range constraint 1-4294967294
• Post summary

---

Issues

None — all documented CLI paths, ranges, and behavior match the vyos-1x source.

Verification against vyos/vyos-1x#5155 (merged 2026-06-25, targets current):

• interface-definitions/include/firewall/geoip.xml.i adds <leafNode name="asn"> with <constraint><validator name="numeric" argument="--range 1-4294967294"/></constraint> and <multi/> → documented range \<1-4294967294\> is correct.
• geoip.xml.i is included in common-rule-ipv4.xml.i / common-rule-ipv6.xml.i under both source and destination blocks, and applies to forward, input, output filters plus name chains → all 16 new cfgcmd paths (2 files × 2 directions × 4 rule types) resolve correctly.
• python/vyos/firewall.py parse_rule now branches on country_code or asn and emits @GEOIP_CC… or @GEOIP_ASN… nft sets → behavior matches doc claim that ASN is matched on the packet's IP address origin.

Note: the workspace's .vyos-1x/ checkout is stale relative to current (still lacks the merged ASN commit), but confirmation was obtained from gh pr diff 5155 --repo vyos/vyos-1x.

Suggestions (INFO — non-blocking)

1. Leading description line still says "geolocation" for both country-code and asn (docs/configuration/firewall/ipv4.md:592, docs/configuration/firewall/ipv6.md:593)

The existing sentence Match IP addresses based on its geolocation. reads oddly now that ASN matching is included — ASN matching keys off the network's routing origin, not geography. The follow-up line you added does clarify this, so this is minor. A tighter phrasing (optional):

Match IP addresses by geolocation (country-code) or origin network (asn).
Use inverse-match to match anything except the specified country-codes or ASNs.

2. Nit in ipv4.md:592 — pre-existing "based on its geolocation" (should be "their" since "IP addresses" is plural). Not touched by this PR; feel free to ignore.

3. Database size / attribution paragraph (ipv4.md:597-600, ipv6.md:599-603)

The PR adds a second dataset (dbip-asn-lite) to the download flow (see python/vyos/geoip.py changes in vyos-1x#5155). The "~3 MB compressed" figure predates ASN and may now understate the image footprint. Worth verifying, but not a blocker for merge.

Needs Verification

None.

Stats

• Validated 2 MyST files (docs/configuration/firewall/ipv4.md, docs/configuration/firewall/ipv6.md).
• Skipped 0 RST files awaiting MyST migration.
• Commands checked: 16 new cfgcmd paths across ipv4/ipv6, source/destination, 4 rule types (forward/input/output/name).
• Branch reviewed: rolling (vyos-1x: current, verified against merged PR geoip: T5746: Add GeoIP ASN support vyos-1x#5155).
  · Branch: geoip-t5746

[Copilot]

Pull request overview

Adds documentation updates to reflect new GeoIP ASN matching support in the VyOS firewall rules syntax (IPv4 and IPv6), aligning the docs with the new CLI capabilities.

Changes:

• Documented source geoip asn and destination geoip asn for IPv4 firewall rules across forward/input/output/name rule contexts.
• Documented source geoip asn and destination geoip asn for IPv6 firewall rules across forward/input/output/name rule contexts.
• Updated the GeoIP explanatory text to mention ASN matching and the effect of inverse-match.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/configuration/firewall/ipv4.md	Adds GeoIP ASN cfgcmd entries and updates the GeoIP/inverse-match explanatory text for IPv4.
docs/configuration/firewall/ipv6.md	Adds GeoIP ASN cfgcmd entries and updates the GeoIP/inverse-match explanatory text for IPv6.

[dmbaturin]

Looks good to me, I've just added small styling suggestions.

[github-actions]

Claude finished @dmbaturin's task in 1m 46s —— View job

---

PR Review: Add GeoIP ASN support (T5746) — post styling commits

• Read updated PR diff (post 4ec9071 + d5bc39b)
• Confirm dmbaturin's suggestions applied verbatim
• Cross-check the 16 new cfgcmd paths + ASN range against upstream vyos-1x current (via gh pr diff vyos/vyos-1x#5155)
• Post summary

---

Issues

None blocking.

Verification (unchanged from prior review) — the 16 new cfgcmd paths (2 files × 2 directions × 4 rule types) all resolve against interface-definitions/include/firewall/geoip.xml.i in vyos-1x current:

• <leafNode name="asn"> with <validator name="numeric" argument="--range 1-4294967294"/> + <multi/> → documented range \<1-4294967294\> is correct.
• geoip.xml.i is pulled into common-rule-ipv4.xml.i / common-rule-ipv6.xml.i under both source and destination, applied to forward, input, output, and name chains.
• python/vyos/firewall.py parse_rule now branches on country_code or asn and emits @GEOIP_CC… or @GEOIP_ASN… nft sets — behavior matches the doc claim.

Styling suggestions from @dmbaturin have been applied (d5bc39b):

• ipv4.md:594 → "Use inverse-match to match anything except the given country code or ASN." ✓
• ipv6.md:596 → "Use inverse-match to match anything except the specified country code or ASN." ✓

Suggestions (INFO — non-blocking, pre-existing)

1. ipv4.md:592 still reads "Match IP addresses based on its geolocation." The pronoun is grammatically off ("its" → "their", as ipv6.md:593 already has). Not introduced by this PR; Copilot also flagged this. Fine to leave for a follow-up.

2. ipv4.md:597-600 / ipv6.md:599-603 — the "~3 MB compressed" figure predates ASN. vyos-1x PR #5155 adds a second dataset (dbip-asn-lite.csv.gz), so the on-image footprint will grow. Worth updating in a follow-up but not a blocker.

Needs Verification

None.

Stats

• Validated 2 MyST files (docs/configuration/firewall/ipv4.md, docs/configuration/firewall/ipv6.md).
• Skipped 0 RST files awaiting MyST migration.
• Commands checked: 16 new cfgcmd paths (8 per file, matches grep -c "geoip asn").
• Branch reviewed: rolling (vyos-1x: current, verified against merged PR geoip: T5746: Add GeoIP ASN support vyos-1x#5155).
  · Branch: geoip-t5746