Technical Information

Microsoft DHCP to NetBox Object Mapping

Object Type Mapping

Microsoft DHCP Object	NetBox Object	Notes
DHCP Scope	`Prefix`	One prefix per scope; `status` = `reserved`; `is_pool` = `true`; `mark_utilized` = `true`
Exclusion Range	`IPRange`	One IP range per exclusion range; `status` = `reserved`
Reservation	`IPAddress`	`status` = `reserved`; always synced
Lease	`IPAddress`	`status` = `dhcp`; opt-in per scope via `MSFT_DHCP_LEASE_SCOPE_IDS`

Prefix Field Mapping (DHCP Scopes)

NetBox Field	Source	Notes
`prefix`	`ScopeId` + `SubnetMask`	CIDR calculated from scope network address and subnet mask
`status`	Static	Always `reserved`
`is_pool`	Static	Always `true`
`mark_utilized`	Static	Always `true`
`description`	Static	`Microsoft DHCP - DHCP Scope - {host}`
`custom_fields`	Scope metadata + options	See custom fields table below

IP Range Field Mapping (Exclusion Ranges)

NetBox Field	Source	Notes
`start_address`	`StartRange`	CIDR notation using the prefix length from the parent scope
`end_address`	`EndRange`	CIDR notation using the prefix length from the parent scope
`status`	Static	Always `reserved`
`description`	Static	`Microsoft DHCP - Exclusion range in scope {scope_id} - {host}`

IP Address Field Mapping

Reservations

NetBox Field	Source	Notes
`address`	`IPAddress`	CIDR notation derived from parent scope subnet mask
`status`	Static	Always `reserved`
`description`	`Name`	`Microsoft DHCP - {host}, Reservation for {Name}`

Leases

NetBox Field	Source	Notes
`address`	`IPAddress`	CIDR notation derived from parent scope subnet mask
`status`	Static	Always `dhcp`
`description`	`HostName`	`Microsoft DHCP - {host}, Leased IP for {HostName}`

Reservation vs. Lease Precedence

When a reservation and a lease exist for the same IP address, the reservation always takes precedence. The IP address is ingested with status reserved using the reservation data.

Custom Fields

The following custom fields are created during bootstrap mode and applied to Prefix objects:

Custom Field Name	Label	Type	Description
`dhcp_server`	DHCP Server	text	Source DHCP server hostname or IP that this scope was synced from
`msft_dhcp_scope_name`	MS DHCP Scope Name	text	Microsoft DHCP scope display name
`msft_dhcp_scope_state`	MS DHCP Scope State	text	Microsoft DHCP scope state (e.g. Active, Inactive)
`msft_dhcp_scope_start_range`	MS DHCP Scope Start Range	text	First address in the Microsoft DHCP scope range
`msft_dhcp_scope_end_range`	MS DHCP Scope End Range	text	Last address in the Microsoft DHCP scope range
`msft_dhcp_lease_duration_seconds`	MS DHCP Lease Duration (seconds)	integer	Microsoft DHCP scope lease duration in seconds
`msft_dhcp_options`	MS DHCP Options	JSON	Microsoft DHCP scope-level option values as reported by Get-DhcpServerv4OptionValue. List of objects with OptionId, Name, Type, Value.

All custom fields are read-only in the NetBox UI (ui_editable: no).

Example `msft_dhcp_options` Value

[
  {"Name": "DNS Servers", "OptionId": 6, "Type": "IPv4Address", "Value": ["192.168.0.1"]},
  {"Name": "Router", "OptionId": 3, "Type": "IPv4Address", "Value": ["192.168.0.254"]},
  {"Name": "Lease", "OptionId": 51, "Type": "DWord", "Value": ["691200"]}
]

Tag	Applied To	Description
`microsoft`	All entities	Applied to all objects from this integration
`dhcp`	All entities	Identifies objects sourced from a DHCP server
`discovered`	All entities	Standard tag applied to all controller integration objects
`msft-dhcp-{host}`	All entities	Unique per-agent tag identifying the source DHCP server; e.g., `msft-dhcp-dhcp-server.corp.example.com`

Configuration Reference

Parameter	Type	Default	Description
`MSFT_DHCP_HOST`	string	required	Windows DHCP Server hostname or IP address
`MSFT_DHCP_USERNAME`	string	required	WinRM service account (typically `DOMAIN\username`)
`MSFT_DHCP_PASSWORD`	string	required	WinRM service account password
`MSFT_DHCP_USE_SSL`	bool	`true`	Use HTTPS WinRM on port 5986; set `false` for HTTP on port 5985
`MSFT_DHCP_PORT`	int	`5986` / `5985`	Override the default WinRM port
`MSFT_DHCP_VERIFY_SSL`	bool	`false`	Verify the WinRM TLS certificate; off by default as Windows servers commonly use self-signed certificates
`MSFT_DHCP_LEASE_SCOPE_IDS`	string	unset	Comma-separated list of scope IDs (network addresses) for which leases are synced; e.g., `192.168.0.0,10.0.1.0`
`BOOTSTRAP`	bool	`false`	When `true`, emits only custom field definitions with no DHCP server connection required

Connection Details

The integration uses the pypsrp library to connect over WinRM/PSRP with NTLM authentication. The following PowerShell cmdlets are executed on the target server:

Cmdlet	Purpose
`Get-DhcpServerv4Scope`	Retrieves all DHCP scopes
`Get-DhcpServerv4Lease`	Retrieves leases; called only for scopes listed in `MSFT_DHCP_LEASE_SCOPE_IDS`
`Get-DhcpServerv4Reservation`	Retrieves all reservations across all scopes
`Get-DhcpServerv4OptionValue`	Retrieves per-scope DHCP option values
`Get-DhcpServerv4ExclusionRange`	Retrieves exclusion ranges for each scope