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) becomes10.0.60.0/24, and10.0.20.0/255.255.255.0becomes10.0.20.0/24. Each rewrite is logged (old -> new, tenant, id, what hangs off the prefix) as adanbyte.migrationswarning and written to the prefix's change log. - A value it can't rewrite (
banana,10.0.0.0/33, host bits set such as10.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.
Related¶
- Prefix CRUD - the create / edit flow
- Tree + sections - the list rendering
- Space map - the per-mask grid view