# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a network documentation and discovery project that integrates with NetBox. ## NetBox Integration - **NetBox URL**: https://netbox.vntx.net/ - **API Key**: e50298f7fd20f7fd6f1931f635511b34f6e8cfde - **Purpose**: Network documentation and discovery ## Development Guidelines ### NetBox API Usage - Use the provided API key for authentication with NetBox - The NetBox instance is located at https://netbox.vntx.net/ - Follow NetBox API documentation for proper endpoint usage - The netbox api token is in env var NETBOX_KEY ### Security Notes - Never commit API keys directly in code files - Use environment variables or configuration files for sensitive data - The API key provided should be stored securely ## Common Tasks ### NetBox API Connection When connecting to NetBox, use: - Base URL: `https://netbox.vntx.net/api/` - Authentication header: `Authorization: Token e50298f7fd20f7fd6f1931f635511b34f6e8cfde` ### MikroTik Router Connection Connect to MikroTik routers using API-SSL: - **Protocol**: API-SSL (port 8729) - **Username**: `grahamro` (read-only) - **Password**: `cFKhz8q5gPLoucMbcT1Iy58r3IXgc3` - **Example - Verona Router**: `10.254.254.101` Use the `mikrotik_connect.py` script to connect and retrieve router information: ```bash python3 mikrotik_connect.py ``` The script handles SSL connection, authentication, and can retrieve: - IP addresses and subnets - Interface configurations - Routing tables - PPPoE connections ## Router Access Credentials ### MikroTik Routers - Read-only access via API-SSL: username `grahamro`, password `cFKhz8q5gPLoucMbcT1Iy58r3IXgc3` ### Verona Routers - Verona router is 10.254.254.101 ### Additional Router IP Addresses - Climax router: 10.254.254.102 - Culleoka router: 10.254.254.104 ## NetBox Site and Device Creation Process ### Creating a new site and router in NetBox: 1. **Create Site**: Use `create_verona_site_and_router.py` as template - Site name and slug (lowercase, hyphenated) - Status: 'active' - Comments describing the site 2. **Create Device**: - Manufacturer: MikroTik - Device Type: RouterBOARD - Device Role: Router - Primary IP: Router's loopback IP (e.g., 10.254.254.101/32) 3. **Add Network Data**: Use `update_netbox_verona.py` as template - Creates prefixes with proper roles (Infrastructure, Customer, Management, Loopback) - Creates interfaces on the device - Associates IP addresses with interfaces ### API Authentication - Always use environment variable `NETBOX_KEY` for API token - Fallback to hardcoded token only if env var not set ## Generic Scripts for Network Management ### 1. Create Site Only in NetBox ```bash # Basic usage python3 create_site_only.py # With options python3 create_site_only.py 380 --comments "Central site with multiple routers" --address "380 Main St" ``` ### 2. Create Site and Router in NetBox ```bash # Basic usage python3 create_site_and_router.py # With options python3 create_site_and_router.py Climax 10.254.254.102 --router-name climax-core --physical-address "123 Tower Rd" # For sites with multiple routers, create site first, then add each router python3 create_site_only.py 380 --comments "Multi-router site" python3 create_site_and_router.py 380 10.254.254.105 --router-name 380-core-router python3 create_site_and_router.py 380 10.254.254.106 --router-name 380-edge-router ``` ### 3. Get MikroTik Router Configuration ```bash # Basic usage (uses default read-only credentials) python3 get_mikrotik_router_data.py # Save to specific file python3 get_mikrotik_router_data.py 10.254.254.102 -o climax_config.json # Output JSON to stdout python3 get_mikrotik_router_data.py 10.254.254.102 --json # Custom credentials python3 get_mikrotik_router_data.py 10.254.254.102 -u admin -p secretpass ``` The script retrieves: - Router identity - IP addresses and subnets - Active interfaces - VLANs - PPPoE servers - Static routes ### 4. Get MikroTik Router Data (Basic/Older RouterOS) For older RouterOS versions or routers with many IPs (like CGNAT): ```bash python3 get_mikrotik_basic_data.py -o router_data.json ``` This simplified script: - Groups CGNAT addresses into a single subnet entry - Focuses on key interfaces only - Works better with older RouterOS versions - Handles large configurations without timing out ### 5. Get All Network Devices ```bash # Get all devices categorized by type python3 get_all_network_devices.py # Show all devices including "Other" category python3 get_all_network_devices.py --show-all # Save to JSON file python3 get_all_network_devices.py -o devices.json ``` This script retrieves DHCP leases and ARP table to identify: - Ubiquiti access points and devices - MikroTik devices - Other network devices ## Network Topology Patterns ### Access Point Placement - Access points are always placed in the top /24 of the management subnet for each tower - Example: For management subnet 10.10.16.0/20, APs are in 10.10.31.0/24 (the last /24 in that range) - Formula: For subnet X.Y.Z.0/20, APs are in X.Y.(Z+15).0/24 ### Ubiquiti MAC Prefixes Common MAC address prefixes for Ubiquiti devices: - 00:04:56 (legacy) - 00:27:22 (legacy) - 04:18:D6 - 24:A4:3C - 68:72:51 - 80:2A:A8 - F0:9F:C2 - FC:EC:DA ## MPLS / LDP ### FastTrack is incompatible with MPLS on RouterOS 7 FastTrack bypasses the IP forwarding path that MPLS push/pop runs on, so any flow that gets fasttracked on a router whose path uses an MPLS-enabled interface can break — packets either hit the wrong interface or never get labeled, which presents as black-holing for specific source subnets that weren't fasttracked before. Symptoms: pings/SSH/TCP from one source IP work but the same destination is unreachable from another source on the same router; loopback-sourced traffic works but vlan-interface-sourced doesn't. **Fix:** before each `action=fasttrack-connection` rule in `chain=forward`, add `accept` rules that match the MPLS-bound interface(s) so those flows never enter the fasttrack path: ``` /ip firewall filter add chain=forward action=accept in-interface= comment="bypass fasttrack for MPLS spine (in)" place-before= add chain=forward action=accept out-interface= comment="bypass fasttrack for MPLS spine (out)" place-before= ``` Customer→internet flows continue to fasttrack normally; only flows traversing the MPLS spine bypass it. ### LDP doesn't label OSPF Type-5 externals by default Prefixes redistributed via `redistribute=connected` (e.g., a /27 customer WAN handoff like 204.110.191.0/27) appear as Type-5 external LSAs and don't get LDP label bindings. Forward path to a labeled destination still works, but the return path is plain IP. If you need labeled bidirectional reach for a redistributed prefix, configure an LDP advertise-filter that explicitly includes it. ### MPLS-MTU is the labeled-frame cap, not the IP-payload cap `mpls-mtu=1500` caps the *labeled* frame at 1500 bytes, which means an inner IP payload is limited to 1496 bytes — so 1500-byte DF customer traffic gets icmp-frag-needed. Use `mpls-mtu=1508` for a 1500-byte IP payload + 4-byte label, with 4 bytes of headroom for one more stacked label. The AF11/AF24 radio l2mtu is 2024, so 1508 fits comfortably. ### Fleet-wide MPLS topology LDP runs IPv4-only across every backbone link in the network. Every backbone port has `mpls-mtu=1508` set explicitly and a fasttrack-bypass pair (in/out) above the `fasttrack-connection` rule on both endpoints. Documented in `mikrotik-tool/mpls.md`. ``` verona ──AF11── climax ──AF24── core ──AF11── culleoka │ │ │ │ AF11 │ AF11 │ AF11 (DOWN: power injector unplugged) │ │ │ 494 newhope ──AF24── lowry │ │ 60 GHz │ 982 ``` Wait — that diagram's links are: climax↔494 (AF11), core↔newhope (AF11), core↔982 (60 GHz), newhope↔lowry (AF24). The climax↔culleoka direct AF11 is currently down at the radio (physical issue), so culleoka traffic transits via core. ## Fleet Topology ### Routers and loopbacks All ROS7 routers run RouterOS 7.21.4 long-term (post-2026-05-08 fleet upgrade). Edge runs ROS 6.49.18 (legacy, no MPLS, ignore for the spine). | Router | Loopback (10.254.254.x) | Hardware | Site name | |--|--|--|--| | verona | .101 | CCR2004-16G-2S+ (arm64) | verona | | climax | .102 | CCR2004-16G-2S+ (arm64) | climax | | culleoka | .104 | CCR1009-7G-1C-1S+ (tile) | culleoka | | newhope | .108 | CCR1009-7G-1C-1S+ (tile) | newhope | | lowry | .109 | (tile) | lowrycrossing | | 982 | .110 | (CCR, tile) | 982 | | 494 | .111 | (CCR, tile) | 494 | | core | .253 | (CCR, arm64) at 380 | core/380 | | edge | .254 | (legacy, ROS 6.49.18) | edge | Tile-arch boxes can run MPLS but **not** ZeroTier (no .npk for tile). ### Backbone links Every link below has IPv4 LDP enabled at both ends, `mpls-mtu=1508`, and fasttrack-bypass rules in both directions on both routers. | Link | Type | A-side iface | B-side iface | /29 subnet | l2mtu | |--|--|--|--|--|--| | verona↔climax | AF11 | verona `ether3-climax-11ghz` | climax `ether6-verona-11ghz` | 10.250.1.24/29 | 2024 | | climax↔core | AF24 | climax `ether4-380-airfiber24` | core `ether5-climax` | 10.250.1.88/29 | 2024 | | climax↔494 | AF11 | climax `ether5-494` | 494 `ether2-climax` | 10.250.1.64/29 | 1580 | | climax↔culleoka | AF11 | climax `ether3-culleoka-11ghz` | culleoka `ether1-climax-11ghz` | 10.250.1.8/29 | 2024 (link DOWN) | | core↔culleoka | AF11 | core `ether6-culleoka-11ghz` | culleoka `ether6-380-11ghz` | 10.250.1.48/29 | 2024 | | core↔newhope | AF11 | core `ether4-newhope` | newhope `ether2-380` | 10.250.1.56/29 | 9000 | | core↔982 | 60 GHz | core `ether1-982-60ghz` | 982 `ether7-380` | 10.250.1.32/29 | 9000 | | newhope↔lowry | AF24 | newhope `ether6-lowrycrossing` | lowry `ether1-newhope` | 10.250.1.104/29 | 9000 | | core↔edge | wired | core `sfp-sfpplus1-edge-preseem` + `ether3-edge-direct` | edge ports | 204.110.191.x | n/a | l2mtu mismatches across the fleet are intentional per platform: AF11 base ports default to 2024 on CCR2004 / 1580 on smaller CCRs; jumbo-capable links (60 GHz, AF24-with-jumbo, fiber) go to 9000. **Always raise both sides symmetrically when changing l2mtu** — single-side raises usually work because Ethernet receivers accept anything ≤ their cap, but symmetric is the rule. ### IGP / routing - OSPFv2 area `backbone-v2` (id 0.0.0.0) on all spine links, SHA-512 auth with `auth-id=1` and a shared key. PTP type, BFD enabled where supported. - OSPFv3 area `backbone-v3` for IPv6 (some interfaces only). - All instances `redistribute=connected` with passthrough filters (`/routing filter rule chain=ospf-out rule="accept;"`). - Verona has a static default to `10.250.1.30` (climax) backing up the OSPF default — keep this; bouncing OSPF on verona doesn't blackhole it. - Distance-1 static routes also exist on climax for `204.110.191.0/27` so the home /27 has guaranteed return path even if OSPF redistribution hiccups. ### Management subnets per tower `10.10.x.0/20` per site, top /24 reserved for APs (see Access Point Placement section). Authoritative mapping is in `mikrotik-tool/inventory.yaml`. Quick reference: - verona: 10.10.0.0/20 - altoga (behind verona, no router): 10.10.16.0/20 - climax: 10.10.48.0/20 - core/380: 10.10.64.0/20 - culleoka: 10.10.96.0/20 - 982: 10.10.128.0/20 - newhope: 10.10.144.0/20 - 494: 10.10.160.0/20 - lowry: 10.10.80.0/20 CGNAT pools: `100.64.x.x/22` per tower (see `inventory.yaml` / `subnets.yaml`). ### graham's home network gotcha graham's home connects to verona via `vlan9_sfpplus1` carrying `204.110.191.0/27` (home router at `.1`, verona at `.30`). This /27 is a subnet of the verona hotspot's covered range (`204.110.188.0/22`). After any verona reboot, ensure `/ip hotspot ip-binding` has an entry: `address=204.110.191.0/27 type=bypassed comment="graham home /27"` — without it, hotspot drops all `204.110.191.x` traffic in `hs-unauth-to` chain with `icmp-host-prohibited`. Symptom is "I can reach verona but nothing past it" from the home network. ### IPv6 plan Per-tower /44s + central server LAN at `2606:1c80::/64` on edge. Full allocation plan in `mikrotik-tool/ipv6.md`. NetBox has these as IPAM prefixes. ## Claude Assistant Guidelines - Any time Claude learns something new, automatically add it to CLAUDE.md ## Development Best Practices - When making scripts, keep them as generic and reusable as possible