Skip to main content
← back to extensions

Unifi Dhcp Reservation

@sntxrr/unifi-dhcp-reservationv2026.07.31.1· 1d agoMODELS
01README

Declarative DHCP fixed-IP reservations on a local UniFi controller (UDM / UDM Pro / UDM SE). sync reads every reservation the controller holds; drift compares a desired set against it without writing, reporting missing, mismatched, unmanaged, duplicate and DHCP-pool-overlapping entries; apply reconciles the controller to the desired set and supports dryRun. device_drift does the same read-only comparison for adopted hardware, which cannot hold reservations at all and is addressed through device config instead — the one surface drift is blind to. Reservations live on the legacy Network API as user objects carrying use_fixedip/fixed_ip. Adds TOTP/MFA login support, which the upstream @mgreten/unifi auth flow lacks — UniFi SSO accounts with MFA reject password-only logins with MFA_AUTH_REQUIRED. Catches the failure mode where a reservation silently never takes effect because its address is already claimed by a statically-configured host.

02Models1
@sntxrr/unifi/dhcp_reservationv2026.07.31.1unifi_dhcp_reservation.ts

Global Arguments

ArgumentTypeDescription
hoststringUDM IP address or hostname, e.g. 192.0.2.1
usernamestringUniFi admin username
passwordstringUniFi admin password (use a vault reference)
totpSecret?stringBase32 TOTP secret for MFA-enabled accounts (use a vault reference).
sitestringUniFi site name
fn sync()
Read every fixed-IP reservation from the controller and store one
fn drift(desired: array)
Compare a desired reservation set against the controller without
ArgumentTypeDescription
desiredarrayThe reservation set that should exist.
fn inventory(macs?: array, ips?: array, unreservedOnly: boolean)
List every host the controller knows about — clients and adopted
ArgumentTypeDescription
macs?arrayOnly these MACs (any separator style).
ips?arrayOnly these addresses.
unreservedOnlybooleanOnly hosts without a fixed-IP reservation.
fn verify(desired: array)
Pre-flight a desired reservation set against live DHCP leases: where
ArgumentTypeDescription
desiredarrayThe reservation set that should exist.
fn set_pool(start: string, stop: string, dryRun: boolean)
Change the DHCP range of the LAN network. Reports which hosts hold a
ArgumentTypeDescription
startstringFirst address of the new DHCP range.
stopstringLast address of the new DHCP range.
dryRunbooleanReport what the change would displace without writing.
fn device_pin(devices: array, netmask: string, gateway: string, dns1?: string, dns2?: string, dryRun: boolean)
Set a static address in device config on adopted UniFi hardware
ArgumentTypeDescription
devicesarrayThe devices to pin.
netmaskstring
gatewaystringDefault gateway for the fabric.
dns1?string
dns2?string
dryRunboolean
fn apply(desired: array, dryRun: boolean)
Reconcile the controller to a desired reservation set. Creates
ArgumentTypeDescription
desiredarrayThe reservation set that should exist.
dryRunbooleanReport the actions that would be taken without writing.

Resources

reservation(infinite)— A DHCP fixed-IP reservation known to the controller.
drift(infinite)— Comparison of a desired reservation set against the controller.
verification(infinite)— Pre-flight of a desired reservation set against live DHCP leases.
inventory(infinite)— Every host the controller knows about, clients and adopted hardware.
pool_change(infinite)— Outcome of changing the DHCP range, and what it displaces.
device_pin_result(infinite)— Outcome of pinning one adopted device to a static address.
apply_result(infinite)— Outcome of reconciling one reservation.
03Previous Versions1
2026.07.21.2
04Stats
A
100 / 100
Downloads
0
Archive size
49.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
Repository
https://github.com/sntxrr/swamp-unifi
05Platforms
06Labels
#unifi#ubiquiti#udm#dhcp#reservations#drift#homelab#networking