Microsoft DHCP Integration FAQ and Troubleshooting

This document provides answers to commonly asked questions about the NetBox Microsoft DHCP integration.

General Questions

Q: Does the integration support multiple DHCP servers? A: Yes. Deploy a separate agent instance for each DHCP server, each with its own configuration pointing to a different MSFT_DHCP_HOST.

Q: Can NetBox push data back to the Windows DHCP Server? A: No. The integration is one-way - data flows from Microsoft DHCP Server into NetBox only. No changes are written back to the DHCP server.

Q: Is the integration free to use? A: The Microsoft DHCP integration is available with commercial editions of NetBox.

Q: Do I have to have NetBox Assurance to use this integration? A: Yes. The integration sends discovered data to NetBox via Diode and NetBox Assurance, where you review and apply changes before they are written to NetBox.

Q: Which versions of NetBox are supported? A: NetBox Cloud and NetBox Enterprise v4.2.3 and later.

Q: Does the integration support IPv6 scopes? A: No. The current implementation syncs DHCPv4 scopes only, using Get-DhcpServerv4Scope and related cmdlets.

Technical Questions

Q: What authentication method does the integration use? A: The integration uses NTLM authentication over WinRM (Windows Remote Management). No agent software needs to be installed on the Windows DHCP Server.

Q: What permissions does the service account need? A: The account must be able to run the DHCP Server PowerShell cmdlets: Get-DhcpServerv4Scope, Get-DhcpServerv4Lease, Get-DhcpServerv4Reservation, Get-DhcpServerv4OptionValue, and Get-DhcpServerv4ExclusionRange. Membership in the local Administrators group on the DHCP server is sufficient. Alternatively, membership in the built-in DHCP Administrators group provides appropriate read access.

Q: Are DHCP leases synchronized by default? A: No. Lease synchronization is opt-in. By default the integration syncs scopes (as prefixes), exclusion ranges (as IP ranges), and reservations (as IP addresses). To enable lease sync, set MSFT_DHCP_LEASE_SCOPE_IDS to a comma-separated list of scope IDs (network addresses) for which you want leases ingested.

Q: Why is lease synchronization opt-in? A: DHCP leases are transient and active networks can have thousands of them. Syncing all leases from all scopes may not be desirable for NetBox. Specifying scope IDs explicitly lets you control which scopes contribute lease data to NetBox.

Q: What happens if a reservation and a lease exist for the same IP address? A: The reservation always takes precedence. The IP address is ingested with status reserved using the reservation data, and the lease entry is discarded.

Q: What NetBox objects are created from a DHCP scope? A: Each scope creates one Prefix in NetBox with status reserved, is_pool set to true, and mark_utilized set to true. Scope metadata (name, state, address range, lease duration, and DHCP options) is stored in custom fields on the prefix.

Q: What NetBox objects are created from exclusion ranges? A: Each exclusion range creates one IP Range in NetBox with status reserved.

Q: What tags are applied to synchronized objects? A: All entities from the Microsoft DHCP integration are tagged with microsoft, dhcp, discovered, and a unique per-server tag in the format msft-dhcp-{host} (e.g., msft-dhcp-dhcp-server.corp.example.com).

Q: What custom fields does the integration create? A: Bootstrap mode creates seven custom fields on Prefix objects: dhcp_server, msft_dhcp_scope_name, msft_dhcp_scope_state, msft_dhcp_scope_start_range, msft_dhcp_scope_end_range, msft_dhcp_lease_duration_seconds, and msft_dhcp_options.

Q: How often should the integration run? A: A daily schedule ("0 2 * * *") suits most environments. If lease data is important and changes frequently, consider a shorter interval such as every 6 hours ("0 */6 * * *").

Q: What is the BOOTSTRAP setting for? A: Bootstrap mode creates the seven required custom fields in NetBox without connecting to the DHCP server. Run it once before the first full sync, apply the resulting deviations in NetBox Assurance, then set BOOTSTRAP: False for all subsequent runs.

---

Troubleshooting

WinRM Connection Issues

Problem: The agent cannot connect to the Windows DHCP Server

• Verify WinRM is enabled on the target server. Run winrm quickconfig on the server or check that the WinRM service is running
• Confirm port 5986 (HTTPS) or 5985 (HTTP) is reachable from the agent host
• Check firewall rules on the Windows Server and any intermediate network devices
• Test basic connectivity with Test-WsMan -ComputerName <hostname> from another Windows machine on the same network

Problem: Authentication fails with an NTLM error

• Verify the username format is DOMAIN\username (or .\username for local accounts)
• Check the password is correct and has not expired
• Ensure the account is a member of the local Administrators group or the DHCP Administrators group on the server
• If using a domain account, confirm the agent host can reach the domain controller for NTLM negotiation

Problem: SSL/TLS certificate errors when connecting over WinRM HTTPS

• Windows servers commonly use self-signed certificates for WinRM. The default configuration sets MSFT_DHCP_VERIFY_SSL: false to accommodate this
• If you have a valid certificate on the WinRM HTTPS listener, you can set MSFT_DHCP_VERIFY_SSL: true
• To use HTTP instead (not recommended for production), set MSFT_DHCP_USE_SSL: false - this switches to port 5985

Problem: Connection is refused or times out

• Check that the WinRM listener is configured. Run winrm enumerate winrm/config/listener on the server to confirm listeners are active
• Verify you are using the correct port. The default for HTTPS WinRM is 5986; for HTTP it is 5985
• To override the port, set MSFT_DHCP_PORT in your configuration

Configuration Issues

Problem: Missing required config errors in the agent log

ValueError: Missing required config: MSFT_DHCP_HOST, MSFT_DHCP_USERNAME

• Ensure all required environment variables are set: MSFT_DHCP_HOST, MSFT_DHCP_USERNAME, MSFT_DHCP_PASSWORD
• If using a .env file, confirm the file path is correct and the variables are not commented out
• Check the docker run command passes either --env-file .env or individual -e flags for each variable

Problem: MSFT_DHCP_LEASE_SCOPE_IDS is set but leases are not appearing

• Verify the scope IDs are the network addresses of the scopes (e.g., 192.168.0.0, not 192.168.0.1)
• Each scope ID must be a valid IPv4 address - the agent validates the format at startup and will error on invalid values
• Confirm the scopes with those IDs actually have active leases on the DHCP server
• Check the agent log for Lease sync enabled for scopes: to confirm the setting was parsed correctly

Data Issues

Problem: DHCP scopes are not appearing as prefixes in NetBox

• Check the agent logs for the number of scopes retrieved: Retrieved X DHCP scopes
• If zero scopes are returned, verify the service account has permission to run Get-DhcpServerv4Scope
• Confirm the DHCP Server role is installed and active on the target server

Problem: Custom fields are not populated on prefix objects

• Custom fields are created in bootstrap mode and populated during regular sync runs
• If the custom fields exist in NetBox but show no values, check the agent logs for scope processing errors
• Verify the deviations for the custom field values have been applied in NetBox Assurance

Problem: Exclusion ranges are not appearing as IP ranges in NetBox

• Exclusion ranges only appear if the DHCP scopes have exclusions configured
• Check the agent log for Built X IP range entities. If zero, there are no exclusion ranges on the server
• Verify the service account can run Get-DhcpServerv4ExclusionRange

Problem: Reservations are not appearing as IP addresses

• Reservations are always synced regardless of MSFT_DHCP_LEASE_SCOPE_IDS configuration
• If reservations are missing, check the agent log for errors from Get-DhcpServerv4Reservation
• Verify the service account has permission to read reservation data

Problem: The msft_dhcp_options custom field is empty on some prefixes

• msft_dhcp_options is only populated when the scope has option values configured
• Scopes with no options set will not have this field populated - this is expected behavior
• Check the DHCP server directly to confirm whether options are configured for those scopes

Bootstrap Issues

Problem: No deviations appear in NetBox Assurance after bootstrap

• Confirm BOOTSTRAP: True is set in the policy config (not just as an environment variable)
• Check the agent log for Registered 7 custom field definitions
• After stopping the agent, navigate to Assurance → Deviation Types and look for custom field deviations
• If nothing appears, check the Diode target and credentials are correct

Problem: Bootstrap mode still attempts to connect to the DHCP server

• In bootstrap mode the agent should not connect to the DHCP server. If you see connection attempts, verify BOOTSTRAP: True is parsed correctly (it must be the boolean True, not the string "True")

Problem: Some custom fields are missing after bootstrap

• Bootstrap creates all seven custom fields in a single run. If any are missing, check the agent log for errors during custom field creation
• Ensure all deviations from the bootstrap run have been applied in NetBox Assurance, not just a subset