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, format A.B.C.D/E. Its keyname is the CIDR itself; it doesn’t need a separate field for it, same as ipam_ip below.
• 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 five entries: IPAM IPs (curated ipam_ip records only), IP Subnets, VLANs, Subnet Calculator, and Bandwidth Calculator. The two calculators are small interactive tools - all computation runs client-side, no data is read from or written to the database:

• Subnet Calculator - enter an IP/CIDR to view its network/broadcast/host range/ binary breakdown, and split it into sub-subnets of a smaller size.
• Bandwidth Calculator - enter a bandwidth (bps/Kbps/Mbps/Gbps) and a data size (Bytes/KB/MB/GB/TB, decimal SI units) to estimate the transfer duration.

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 IPs found inside it, each with whatever else in the app references that address

Occupancy (how many IPs are in use, and what percent of the range) is always computed, whatever the prefix length.

IP list and CSV download

The IP list on a subnet (and on each subnet of a VLAN) shows the first CAVALIBA_IPAM_IP_LIST_MAX addresses - 256 by default. Past that it is headed showing first N of T, and the rest is not dropped: the Download full list (CSV) link next to the table title builds the complete list as a file.

The list is limited by how many IPs a subnet actually holds, not by how wide it is - a /8 documenting a handful of addresses lists them all.

The CSV holds one row per IP - ip, collected, description, referrers - with the referrers joined as space-separated classname:keyname (the table on screen repeats an IP once per referrer; the file does not). Its separator is the CSV_DELIMITER configuration, same as every other export. A list longer than CAVALIBA_IPAM_IP_LIST_FILE_MAX rows ends with a # truncated at N rows line rather than looking complete.

The file is built when you click the link, and expires after CAVALIBA_IPAM_IP_LIST_FILE_TTL_HOURS. Downloading it needs read access to the subnet, nothing more - it holds exactly what the page would show you.

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), each with its own hierarchy and its own IP list and CSV download link; 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_IP_LIST_MAX	256	IPs listed on screen for one subnet. Past this the table is headed showing first N of T and the full list is offered as a CSV.
CAVALIBA_IPAM_IP_LIST_FILE_MAX	100000	Hard cap on rows written to that CSV. A longer list ends with a # truncated at N rows line.
CAVALIBA_IPAM_IP_LIST_FILE_TTL_HOURS	1	How long that CSV stays downloadable before the housekeeping job removes it.
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.

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.