Documentation
APP - IPAM

APP - IPAM

IPAM - IPv4-only IP Address Management: subnets, VLANs, individual IPs, and cross-links from any object in the app that carries an IP address or a subnet reference.

IPv6 is not supported.

IPAM Concepts

Three builtin schemas back the IPAM service:

  • ipam_subnet - a CIDR range (subnet field, format A.B.C.D/E). The subnet’s keyname is the CIDR itself.
  • ipam_vlan - a VLAN definition (vlan_id, vlan_family, and 0..N linked ipam_subnet objects).
  • ipam_ip - a curated record for one specific address you want to document (a gateway, a reservation, …). Its keyname is the IP address itself; it doesn’t need an ipv4 field of its own since the keyname is the address.

Any other schema with a field of dataformat ipv4 (a VM’s IP, a printer’s IP, …) is picked up automatically by IPAM’s lookups - you don’t need to register it anywhere.

IPAM Home Page

Go to the IPAM Service from the sidebar. The landing page has a search box and three “list of…” entries: IPAM IPs (curated ipam_ip records only), IP Subnets, and VLANs.

Search box

The search box classifies what you type and takes you straight to the matching view:

  • a full IPv4 address (10.1.2.3) -> the Single IP view
  • a CIDR range, aligned or not (10.1.2.0/24 or 10.1.2.34/24) -> the Single Subnet view, aligned to the subnet boundary automatically
  • a partial dotted prefix (10, 10.1, 10.1.2) -> zero-padded and given a /8, /16 or /24 mask respectively, then treated as a subnet (10.1 -> 10.1.0.0/16)
  • anything else -> a free-text search across VLANs (keyname, name, description)
  • an IPv6 address or range is rejected with a message - this app is IPv4 only

Single IP view

Shows, for one address:

  • the curated ipam_ip record if one exists (with an Edit link), or a Create link pre-filled with that IP - shown only if you have create permission on ipam_ip
  • basic technical flags (private/global/multicast/loopback/reserved)
  • every object in the app that references this exact IP (any schema with an ipv4 field, plus a curated ipam_ip record), each linking to its own detail page
  • the smallest containing subnet, and that subnet’s VLAN(s), if any

Single Subnet view

Shows, for one CIDR range:

  • description, first/last IP, netmask, CIDR mask, size, and occupancy (see below)
  • an Edit link (or a permission-gated Create link, pre-filled with the CIDR, if the subnet doesn’t exist as an ipam_subnet record yet)
  • its direct parent subnet, direct child subnets, and linked VLAN(s)
  • the list of IPs found directly inside it (excluding IPs that belong to one of its child subnets), paginated

Occupancy (how many IPs are in use, and what percent of the range) is skipped for very wide subnets - see CAVALIBA_IPAM_OCCUPANCY_MINPREFIX below - to avoid scanning a large fraction of every ipv4 field in the database for a country-wide supernet.

Subnet list

Every ipam_subnet instance, filterable by CIDR prefix or description, with occupancy (count, percent, and a small progress bar) per row. The CIDR itself is visually distinguished by size - large (/0-/16), medium (/17-/24), small (/25-/32) - so country-level supernets stand out from individual VLAN subnets at a glance.

VLAN view / VLAN list

The single VLAN view shows all its fields plus its linked subnet(s); the list is filterable by keyname, name or description.

Click-through from anywhere else in the app

Any ipv4 field, and any schema field pointing at ipam_subnet or ipam_vlan, is a live link wherever it’s rendered - in a generic instance detail page, in a generic instance list, or inside IPAM’s own tables. Clicking a VM’s IP, a printer’s IP, or a VLAN’s subnet reference takes you to the matching IPAM view instead of the generic instance detail page.

Configuration

Setting Default Purpose
CAVALIBA_IPAM_OCCUPANCY_MINPREFIX 20 Subnets with a prefix length narrower than this (a bigger range, e.g. /16) skip occupancy computation entirely, in both the Subnet view and Subnet list.
CAVALIBA_CACHE_IPAM_SUBNET_TIMEOUT 60 Cache TTL (seconds) for the in-memory index of all ipam_subnet instances (parent/child hierarchy). Also invalidated immediately on any ipam_subnet create/update/delete.
CAVALIBA_CACHE_IPAM_OCCUPANCY_TIMEOUT 60 Cache TTL (seconds) for a subnet’s computed occupancy. TTL-only - not invalidated on writes, since a single edit can affect a whole ancestor chain’s occupancy.

Permissions

Cascade: instance -> schema -> global, like every other schema (see IAM).

  • p_ipam_access - can open the IPAM service at all
  • p_ipam_read - can read subnets/VLANs/IPs
  • p_ipam_write - can create/update
  • p_ipam_admin - full control

Internals

  • app_ipam/common.py - all IPAM-specific logic: classify_query (search box), IpamIP / IpamSubnet / IpamVLAN (lookup + field access), get_subnet_index (all ipam_subnet instances loaded in memory once, cached - subnets are administratively created and bounded, unlike end-host IPs, so this is cheap and removes the need for per-level DB queries), find_containing_subnets / find_child_subnets (parent/child hierarchy from that index), compute_subnet_occupancy (prefix-narrowed EAV scan, gated by CAVALIBA_IPAM_OCCUPANCY_MINPREFIX, cached per subnet).
  • app_ipam/views.py / app_ipam/urls.py - private (landing page + search dispatcher), ip_view / ip_list, subnet_view / subnet_list, vlan_view / vlan_list, calculator.
  • Reused, not duplicated: app_data/related.py:get_related() for reverse schema-field lookups (e.g. “which VLAN points at this subnet”), app_data/paginator.py for pagination, app_home/cache.py:DataCache for the two caches above.
  • IPv4 only by design - is_ipv4/is_ipv4_subnet in common.py explicitly reject IPv6.