Skip to content

IP address

A single IP address. Lives inside exactly one Prefix, inherits its VRF.

Fields

Field Type Default Notes
id UUID uuid4() PK
tenant FK → Tenant required Denormalised from prefix.tenant
prefix FK → Prefix required The containing prefix
vrf FK → VRF NULL Mirrors prefix.vrf; denormalised for the unique constraint
ip_address inet required Bare address, never address/length. The API accepts 10.0.0.1/31: a length other than the prefix's lands in mask_length, the prefix's own leaves it empty, and a mask_length sent alongside wins. See Stored form
mask_length smallint NULL Length the address carries on its interface when it differs from the prefix's (a /31 link inside an aggregate). cidr in the API and the render context is address/length with this, else the prefix's
status choice assigned available · assigned · reserved · dhcp_pool · floating
role choice "" "" · gateway · loopback · vip · hsrp · vrrp · anycast · secondary
description text ""
mac_address char(17) "" Hardware address paired with this IP (e.g. a DHCP reservation)
dns_name char(255) "" Hostname / DNS name (PTR). Auto-filled by reverse-DNS monitoring when enabled
last_seen datetime NULL Last time the check engine saw this IP reachable. Engine-set, read-only
monitoring_excluded bool false Every check on the address is parked: nothing runs, no alerts, the time off is not counted. Read-only here; set with POST /api/monitoring/ips/<id>/exclude/. The IP list filters on it: ?monitoring_excluded=true
monitoring_excluded_at / _by / _reason datetime / char(150) / char(200) NULL / "" / "" When, who (username) and why it was excluded. Cleared when it is included again; the change log keeps the history. Not in the API row - the Monitoring tab reads them
availability_since datetime NULL Availability counts from here: uptime, SLA and availability figures leave out what came before. History is kept. Read-only here; set with POST /api/monitoring/ips/<id>/reset-availability/
availability_reset_at / _by / _reason datetime / char(150) / char(200) NULL / "" / "" When, who and why the availability was last reset. The reason is required. Not in the API row
custom_fields JSONB {} Anything org-specific lives here, not as a hardcoded column
tags M2M Tag empty

Uniqueness

UniqueConstraint(
    fields=["tenant", "vrf", "ip_address"],
    nulls_distinct=False,
    name="uniq_ip_tenant_vrf_addr",
)

Same IP in two VRFs is fine.

Site scope

An address belongs to its own site, else its prefix's. A permission limited to sites reaches an address in another site's prefix no more than it reaches the prefix. Only an address with no site in a site-less prefix is shared.

The API row and the export show prefix, assigned_device, assigned_interface, switch, switch_interface, assigned_vm and assigned_vm_interface only when the caller may view that row; otherwise the field is null.

vrf is never set directly - it always mirrors prefix.vrf. Saving the address re-derives it, and moving the prefix into another VRF carries its addresses with it. To move an address between VRFs, point it at a prefix in the target VRF.

Stored form

The column is PostgreSQL inet, which keeps a mask it is given: 10.0.0.5/24 is stored and read back as 10.0.0.5/24. Danbyte stores the host only. The field drops a mask on every ORM write, including bulk_create(), update() and writes from a shell or script, which skip the API's validation. save() moves a length that differs from the prefix's to mask_length; one equal to the prefix's leaves it empty. A mask_length passed to create() wins. On an update, the address's length replaces the stored one, so 10.0.0.1/30 on an address stored with /31 saves /30. A value still stored with a mask reads back as the bare host.

Migration api 0185 stores rows that carry a mask as bare hosts. It leaves a row alone when the bare address is already taken in the same tenant and VRF (inet equality counts the mask, so the constraint let both in), and logs a warning on the danbyte.migrations logger naming both rows. Delete or renumber one of them. To list any that remain:

SELECT id, ip_address FROM api_ipaddress
WHERE masklen(ip_address) < CASE family(ip_address) WHEN 4 THEN 32 ELSE 128 END;

Status vs role

Concept What it means Examples
Status Lifecycle available, assigned, reserved, DHCP-pool, floating
Role Functional purpose gateway, VIP, HSRP, VRRP, loopback, anycast, secondary

These are orthogonal. An assigned IP can also be a VIP. A reserved IP can have no role (just a hold).

Gateway role

Setting an IP's role = gateway:

  1. Clears role on any other IP in the same prefix that was previously gateway
  2. Sets prefix.gateway to this IP's address

Done via the _make_gateway(prefix, ip) helper. Both the auto-spawn flow (on prefix create) and the "Set as gateway" form-button on the prefix detail page use it.

Validation

  • Must fall inside its parent prefix's CIDR - enforced in IPAddressSerializer.validate() (the SPA/API path): rejected with a 400 if the address isn't a member of the selected prefix's network, or if its family (v4/v6) doesn't match. Judged when the address or prefix changes, in any spelling: an address stored outside its prefix still saves from its form. The Allocate only from ranges check follows the same rule.
  • Must not collide with another IP in the same (tenant, vrf) - DB-level unique constraint (failsafe).

Host-part prefill - when adding an IP inside a prefix, the form prefills the network portion from the prefix CIDR (the fully-fixed leading octets, e.g. 10.0.10.0/24 → 10.0.10.) so the operator types only the host part. See networkPrefill() in frontend/src/components/ip-form.tsx.

Addresses a device or VM uses

GET /api/ips/?device=<id> lists every address the device uses:

  • assigned to the device,
  • assigned to one of its interfaces,
  • its primary, OOB or secondary address, even when that address is assigned to another object.

?virtual_machine=<id> does the same for a VM: assigned to the VM, to one of its interfaces, or its primary address. Each address is listed once. A device or VM outside the active tenant lists nothing.

?assigned_vm= and ?assigned_interface= keep their narrower meaning: the address's own assignment only.

The device and VM ip_count, the IPs tab and the Overview's IP addresses count use the same set (api/ip_usage.py). GET /api/devices/<id>/ips/ returns it too. A device or VM list counts its page in one query, so a list costs the same however many addresses the tenant holds.

PRTG sensors

With the PRTG integration on, an address PRTG reaches a device on gets a Sensors tab listing that device's PRTG sensors - see Where sensors show up. Its sensors and channels can be pinned to the address's Overview (Pinned sensors).

The IP address list's Tree

The IP address list has the same Filters / Tree rail as the prefix list (Browse by tree). Pick a VRF and a prefix in the tree and the list shows the addresses inside that prefix - on it or on any prefix below it. With the tree open and nothing picked, it shows the VRF's addresses. The pick is ?within=<id>, kept as a Within … chip when you switch back to Filters. Prefixes you may not view are left out of the tree as on the prefix list.

A prefix's IPs tab has the same switch, with the tree showing the branch around that prefix for moving between prefix pages - see On a prefix's page.

API filters

GET /api/ips/ narrows by search, dns_name, prefix, vrf (global for the global table), within (a prefix id: the addresses on that prefix or on any prefix inside it; empty when you may not view it), site, status, role, assigned_interface, assigned_vm, device, virtual_machine, monitoring_excluded and scope, and by tag: ?tag=<slug> and ?tag_id=<id>, each repeatable, every tag named required. See Filtering by tag.