Skip to content

Prefix

An IP prefix (CIDR), scoped to a (tenant, VRF) pair.

Fields

Field Type Default Notes
id UUID uuid4() PK
tenant FK → Tenant required
vrf FK → VRF NULL (= Global)
cidr char(43) required e.g. 10.0.10.0/24, 2001:db8:1::/64
status choice active container · active · reserved · deprecated
gateway inet NULL The gateway IP; auto-populated when a child IP is set as gateway
vlan FK → VLAN NULL Optional
site FK → Site NULL Optional
description text ""
auto_gateway bool true The site's gateway policy may create a gateway in this prefix when it is created. Off: nothing is created. Turning it off later keeps an existing gateway (see Gateway autospawn)
allocate_from_ranges bool false Only the IP ranges inside the prefix are allocatable: next available, free rows, pools and utilisation come from them; a new address outside every range is refused (see IPAM objects)
custom_fields JSONB {} User-defined attributes
tags M2M Tag empty Via TaggedItem

Uniqueness

class Meta:
    constraints = [
        UniqueConstraint(
            fields=["tenant", "vrf", "cidr"],
            nulls_distinct=False,
            name="uniq_prefix_tenant_vrf_cidr",
        )
    ]

The nulls_distinct=False (Postgres 15+) is what makes vrf=NULL (Global) act like a real VRF for uniqueness - without it, two (tenant, NULL, '10.0.10.0/24') rows would both be allowed.

Moving a prefix between VRFs

The prefix owns the routing context; its IPAddress and IPRange children denormalise it. Changing vrf therefore updates every child in one go, so the prefix and its contents can never disagree about which VRF they are in.

Computed properties

Property Returns Notes
.network ipaddress.IPv4Network \| IPv6Network \| None Parsed CIDR
.family 4, 6, or None Convenience
.utilisation_pct int 0-100 \| None Addresses over usable hosts (see below). None for containers, malformed CIDRs and IPv6 prefixes too large to enumerate. With allocate_from_ranges on, in either family: used-in-range over the ranges' total size (None until a range exists)
.allocation_summary() {size, used, free, ranges} \| None The allocation ranges' accounting (serialised as allocation); None when the prefix allocates from its whole network
.allocation_spans() / .in_allocation(addr) [(start, end)] / bool The ranges as integer spans, clipped to the prefix and merged where they overlap, and whether an address falls inside one

Usable hosts

One rule decides which addresses of a prefix are hosts. Utilisation, next available, the Subnet details card (First usable, Last usable, Usable hosts), Add pool and discovery all use it (api.models.usable_host_count), and it is what Python's ip_network(...).hosts() yields:

Prefix Not hosts Usable hosts
IPv4 /30 and shorter network and broadcast size − 2
IPv4 /31 (RFC 3021) and /32 none size
IPv6 /126 and shorter the Subnet-Router anycast address, :: of the prefix (RFC 4291) size − 1
IPv6 /127 (RFC 6164) and /128 none size

IPv6 has no broadcast, so the last address of a /126 is a host: a /126 has three usable hosts, ::1 to ::3.

Changing the CIDR

A new CIDR must still hold every address and range on the prefix. Narrowing or moving a prefix past one is refused with the addresses and ranges that would fall outside it (the first five of each, and a count). Move or delete them first, or widen instead. Child prefixes are not stored relations, so they never block a change - the tree re-nests them.

Lifecycle

Hook Trigger Action
prefix_create view POST Save → if gateway is empty, the site has a gateway_policy, auto_gateway is on and the status is not container, autospawn an IPAddress(role=gateway)
prefix_edit view POST Save → tags updated; gateway/site/vlan can be changed
prefix_detail view GET Render IPs / Children / Map tabs

Hierarchy (logical, not stored)

Parent/child is derived, never stored. The list view computes depth via stack-walking sorted prefixes per (vrf, family) bucket. This means:

  • No "parent_id" FK to maintain
  • Deleting a prefix doesn't orphan children
  • Re-CIDR'ing automatically re-roots the tree

The cost is that "find all children" is O(n) within a VRF - fine for IPAMs at the scale Danbyte targets.

Containment in SQL tests the stored text cast to inet (cidr::inet <<= x, >>, >>=), and the GiST index prefix_cidr_inet_gist is on exactly that expression (USING gist ((cidr::inet) inet_ops)), so the aggregate list's coverage, contained_in, the space map and search read the index instead of every prefix in the tenant. A new containment query must use the same bare cidr::inet cast - network(cidr::inet) or cidr::cidr does not match the index.

Because the index casts every row, a cidr that is not an address can't be stored. CIDR validation has refused those since #47, but older installs and imports can still hold such rows. Migration api.0265_drop_unparseable_prefixes runs before the index is built and never deletes a prefix:

  • A value the prefix API accepts today is rewritten to what the API would store: 10.0.60.0/24 (a space) becomes 10.0.60.0/24, and 10.0.20.0/255.255.255.0 becomes 10.0.20.0/24. Each rewrite is logged (old -> new, tenant, id, what hangs off the prefix) as a danbyte.migrations warning and written to the prefix's change log.
  • A value it can't rewrite (banana, 10.0.0.0/33, host bits set such as 10.0.30.5/255.255.255.0), or one whose rewrite is a network the tenant already has in that VRF, stops the migration before it changes anything. The error lists each row with tenant, id, value and why. The upgrade preflight finds the same rows before any migration runs; see Prefixes the upgrade can't repair.

Migration api.0262 builds the index CONCURRENTLY, outside a transaction. A plain build also reads the row versions 0265 just replaced and fails on the old text. So an upgrade from before 0.19 runs its migrations one by one rather than in one transaction; the host upgrade still restores its snapshot when one fails.

manage.py prefix_cidrs lists these rows and what the migration does with each one. --set <id> <cidr> gives one a valid CIDR, normalised the way the API does. It refuses a network the VRF already has and one that no longer holds the prefix's IP addresses. It only fixes rows that are not addresses, and runs before the upgrade's migrations.

0.19.0 and 0.19.1 shipped a version of this migration that deleted those prefixes, and with them every IP address in them (#501). See Prefixes the 0.19 upgrade deleted.

API filters

GET /api/prefixes/ narrows by search, vlan, vrf (global for the global table), site, location, contained_in and within (a prefix id: that prefix and every prefix inside it in its VRF; empty when you may not view it; the list only - a prefix's own reads ignore it, and its space map's within is the zoom window), and by tag: ?tag=<slug> and ?tag_id=<id>, each repeatable, every tag named required. See Filtering by tag.

Tree endpoint

GET /api/prefixes/tree/ answers the list's Tree rail, over the prefixes the caller may view only (a prefix under a hidden one hangs from the nearest visible prefix above it):

Params Answer
vrf=<id> or global (default), offset, limit (default 200, at most 1,000) The VRF's top-level prefixes: {count, offset, limit, results}
parent=<id>, offset, limit That prefix's direct children (404 when it is not visible)
vrf, q=<text> The outermost matches (match: true) and the prefixes above them; truncated past 200
parent=<id>, q=<text> The same search over the prefixes inside that one only (a prefix page's tree searches below the top of its branch); a path's top hangs from parent
reveal=<id> {vrf, path}: root to that prefix, each with its index among its siblings

Each node is {id, cidr, parent, child_count}; child_count counts direct visible children.