Skip to content

IPAM and DCIM (phpIPAM, NetBox)

New in the next release

This is on the dev and qa builds now, and in the next release.

Connecting an IPAM lets capacity planning check, before you add a host, that there are addresses left in the subnets your existing hosts and their BMCs are on. NetBox is a DCIM as well, so it also answers how many rack units are free and which PDU outlets have nothing plugged in. When NetBox is connected, its racks are used in place of the racks set on Settings.

Both are read-only. Ferrule never writes to either, and says nothing about where the documentation and the network disagree (yet).

They're read on every edition; the add-host check that uses them is Business and MSP.

phpIPAM

What Ferrule reads: every subnet, its usage (used, free, size), its first free address and its VLAN number. Folders aren't subnets, and are left out. A full subnet has no first free address, which phpIPAM answers with an error; that's expected. Usage is read for the first 300 subnets, one request each; past that, the panel says so.

  1. Administration → API: turn the API on, then Create API key.
  2. App ID ferrule, App permissions Read, App security SSL with App code token. Copy the App code.
  3. In the setup wizard, add phpIPAM: the address (https://ipam.lab), the app ID as API app ID, and the app code as the secret.
Editing the stack by hand 
SOURCE_7=phpipam https://ipam.lab name=ipam user=ferrule every=10m
SOURCE_7_SECRET=<app code>

NetBox

What Ferrule reads: prefixes, with at least 50 of their free addresses (enough to say "plenty", without listing a /16); racks, and how many units their mounted devices fill (devices with no position, such as 0U PDUs, take none); and PDUs' power outlets, free when no cable is recorded and it isn't marked connected.

  1. In NetBox, open your profile, API Tokens, and add a token with Write enabled off.
  2. In the setup wizard, add NetBox: the address (https://netbox.lab), and the token as the secret.

NetBox 4.5's v2 tokens (nbt_…) and the older ones both work: a token that starts nbt_ is sent as a bearer token, any other as Token.

How each is worked out:

  • A prefix's size is its addresses, less the network and broadcast addresses on an IPv4 prefix of /30 or bigger that isn't a pool. Deprecated prefixes are left out.
  • Free addresses: NetBox is asked for up to 50. Fewer than 50 is the exact count; 50 shows as at least 50. The first of them is the first free.
  • A rack's free units are its height less the units its devices fill, from each device type's height. A device with no position (a 0U PDU, one not mounted) takes none. Each device's height is kept, so capacity planning knows what a new host like an existing one takes.
  • A PDU's free outlets are its power outlets with no cable that aren't marked connected.
  • Lists are read 1,000 at a time, up to 20,000 of each.
Editing the stack by hand 
SOURCE_8=netbox https://netbox.lab name=netbox every=10m
SOURCE_8_SECRET=<API token>

Every ten minutes is plenty: none of this changes by the minute.

Where it shows up

Each gets a panel on the LAN tab: subnets with the fullest first (free of size, and the first free address), and from NetBox, racks with their free units and what's in them, and each PDU's free outlets.

Capacity planning uses them when it checks adding a host: free addresses in each subnet the existing host and its BMC are on, and from NetBox, the rack's free units against the host's height. NetBox's racks win over the racks set on Settings.

Neither raises alerts. Metrics:

Metric What it is
infra_ipam_subnet_free_addresses Addresses left in a subnet (source, subnet)
infra_ipam_subnet_size_addresses Usable addresses in it
infra_dcim_rack_free_units A rack's free units (source, rack)

If something's wrong

What you see What to do
set user= on the slot to the phpIPAM API app's ID Fill in API app ID: the app ID from step 2, not your user name.
phpIPAM refused the credentials (401) The app code is wrong, or the app's security isn't SSL with App code token.
phpIPAM: … phpIPAM's own error, such as an app that's been disabled.
NetBox refused the credentials (401) The token is wrong, expired, or limited to other addresses.
NetBox denied the account access (403) The token's user can't view IPAM or DCIM: give them view permission.
racks not read: … The token can read IPAM but not DCIM. Subnets still work.
A subnet shows free — Its usage wasn't read: it's past the first 300, or NetBox didn't answer for it.
The add-host check can't find a subnet for an address No prefix in the IPAM holds it. Add the subnet to the IPAM.