Skip to main content
CloudEnterprise

Getting Started with the Microsoft DHCP Integration for NetBox

Customer Preview

The Microsoft DHCP integration is currently in customer preview. Contact support@netboxlabs.com if you have not already been onboarded.

This guide covers how to set up and run the Microsoft DHCP Integration for NetBox.

Prerequisites​

Before you begin, ensure you have the following:

  • NetBox Cloud or NetBox Enterprise with NetBox Assurance
  • Orb Agent Pro credentials (required to download the integration agent image)
  • Windows DHCP Server with WinRM enabled and a service account with access to the DHCP Server PowerShell module
  • Host System with Docker support
  • Network connectivity between your host and both your NetBox instance and the Windows DHCP Server

Host Requirements​

System​

  • Operating System: Linux, macOS, or Windows with Docker support
  • Memory: Minimum 2GB RAM (4GB recommended)
  • Storage: 1GB free disk space
  • Docker: Version 20.10 or later

Network​

  • Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
  • Outbound WinRM access to your Windows DHCP Server - port 5986 for HTTPS (default) or port 5985 for HTTP
  • DNS resolution for both NetBox and Windows DHCP Server hostnames
  • Firewall rules configured to allow the above connections from your agent host

Windows DHCP Server Requirements​

The integration connects to the DHCP server using WinRM (Windows Remote Management) over NTLM authentication and runs PowerShell commands remotely. The following must be configured on the target Windows Server:

  • WinRM enabled - run winrm quickconfig on the server or use Group Policy to enable WinRM
  • HTTPS listener - configure a WinRM HTTPS listener on port 5986 (recommended), or use HTTP on port 5985
  • Service account - a domain account that is a member of the local Administrators group on the DHCP server, or has sufficient privileges to run DHCP Server PowerShell cmdlets (Get-DhcpServerv4Scope, Get-DhcpServerv4Lease, Get-DhcpServerv4Reservation, Get-DhcpServerv4OptionValue, Get-DhcpServerv4ExclusionRange)
  • DHCP Server PowerShell module - installed as part of the DHCP Server role or DHCP Server Tools feature on Windows Server
info

The integration uses NTLM authentication. The username must be in the format DOMAIN\username. Local accounts can use .\username or HOSTNAME\username.

NetBox Setup​

Generate Diode Client Credentials​

  1. Log into your NetBox instance
  2. Navigate to Diode → Client Credentials
  3. Click + Add a Credential
  4. Enter a descriptive name (e.g., "Microsoft DHCP Integration")
  5. Click Create Add client credentials
  6. Important: Copy and securely store the Client ID and Client Secret - you will need these in the agent configuration copy client credentials
  7. Navigate to Diode → Settings
  8. Copy the value of the Diode target - you will need this in the agent configuration copy Diode target

Agent Setup and Configuration​

info

You can deploy multiple agents, each configured to sync data from a different Windows DHCP Server.

Step 1: Authenticate to the NetBox Labs Image Registry​

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and Token provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

Step 2: Configure the Agent​

  1. Create the configuration file (you can name the file anything you like):
touch agent.yaml
  1. Edit the configuration file with your preferred editor and add the following configuration. Important: Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode > Settings > Diode target in the NetBox UI:
orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: msft_dhcp_agent_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      msft_dhcp_worker:
        config:
          package: nbl_msft_dhcp
          schedule: "0 2 * * *" # Daily at 2:00 AM. Set your desired schedule (see examples below)
          MSFT_DHCP_HOST: ${MSFT_DHCP_HOST}
          MSFT_DHCP_USERNAME: ${MSFT_DHCP_USERNAME}
          MSFT_DHCP_PASSWORD: ${MSFT_DHCP_PASSWORD}
          # MSFT_DHCP_USE_SSL: true                   # Optional: use HTTPS WinRM on port 5986 (default: true)
          # MSFT_DHCP_PORT: 5986                      # Optional: override the WinRM port
          # MSFT_DHCP_VERIFY_SSL: false               # Optional: verify WinRM TLS certificate (default: false)
          # MSFT_DHCP_LEASE_SCOPE_IDS: "192.168.0.0,10.0.1.0"  # Optional: comma-separated scope IDs to sync leases for
          BOOTSTRAP: True  # Set to True for initial setup, False for regular operation
        scope:            # Required — leave empty (Microsoft DHCP does not support scope filtering)
Schedule Examples

The schedule field uses cron syntax. Here are some common examples:

  • "0 */6 * * *" - Every 6 hours (e.g., 00:00, 06:00, 12:00, 18:00)
  • "0 2 * * *" - Daily at 2:00 AM
  • "0 9 * * 1" - Weekly on Monday at 9:00 AM

Lease Synchronization​

By default, the integration syncs DHCP scopes (as prefixes), exclusion ranges (as IP ranges), and reservations (as IP addresses with status reserved). Lease synchronization is opt-in and must be explicitly enabled.

To enable lease sync, set MSFT_DHCP_LEASE_SCOPE_IDS to a comma-separated list of scope IDs (using the scope network address, e.g., 192.168.0.0). Leases from those scopes are ingested as IP addresses with status dhcp.

config:
  MSFT_DHCP_LEASE_SCOPE_IDS: "192.168.0.0,10.0.1.0,172.16.10.0"
Reservations Override Leases

If a reservation and a lease exist for the same IP address, the reservation takes precedence. The IP address is ingested with status reserved and the lease entry is discarded.

Why opt-in? DHCP leases are transient and can number in the tens of thousands on active networks. Syncing all leases from all scopes into NetBox may not be desirable. By specifying scope IDs, you control which scopes contribute lease data.

Bootstrap Mode (First-Time Setup)​

Bootstrap mode creates the required custom fields in NetBox before the first full DHCP sync. In bootstrap mode, the agent does not connect to the DHCP server.

What Bootstrap Mode Does:

  • Creates 7 custom fields on Prefix objects:
    • dhcp_server - source DHCP server hostname
    • msft_dhcp_scope_name - DHCP scope display name
    • msft_dhcp_scope_state - scope state (Active or Inactive)
    • msft_dhcp_scope_start_range - first address in the scope range
    • msft_dhcp_scope_end_range - last address in the scope range
    • msft_dhcp_lease_duration_seconds - lease duration in seconds
    • msft_dhcp_options - scope-level DHCP options as JSON

Configuration:

config:
  BOOTSTRAP: True  # Set to True for initial setup, False for regular operation

First-Time Run Process:

  1. Run the agent with BOOTSTRAP: True in your configuration
  2. Monitor the output for the text executed successfully
  3. Stop the agent immediately by pressing Ctrl+C in your terminal once you see executed successfully
  4. Apply the deviations in NetBox Assurance (see Apply Deviations below)
  5. Set BOOTSTRAP: False for all future runs

Important Notes:

  • Bootstrap mode is only for first-time setup - do not run it on a schedule
  • Stop the agent manually with Ctrl+C after seeing executed successfully
  • Once deviations are applied, set BOOTSTRAP: False for regular operation

Optional - Dry Run Mode​

The agent can be run in Dry Run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for troubleshooting or reviewing what the integration will ingest before committing to your NetBox instance.

Enable dry run in the diode section of your agent configuration file:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/ # saves the output file to this directory

Step 3: Run the Agent​

Method 1: Set Environment Variables Manually​

  1. Export Diode credentials as environment variables:
export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"
  1. Export DHCP server credentials as environment variables:
export MSFT_DHCP_HOST="dhcp-server.corp.example.com"
export MSFT_DHCP_USERNAME="CORP\svc-netbox"
export MSFT_DHCP_PASSWORD="your-password"
  1. Run the agent with the following command:
docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e MSFT_DHCP_HOST \
  -e MSFT_DHCP_USERNAME \
  -e MSFT_DHCP_PASSWORD \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml
  1. Create a .env file in your current directory:
touch .env
  1. Edit the .env file with your preferred editor and add the following content:
# NetBox Diode credentials
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

# Microsoft DHCP Server credentials
MSFT_DHCP_HOST=dhcp-server.corp.example.com
MSFT_DHCP_USERNAME=CORP\svc-netbox
MSFT_DHCP_PASSWORD=your-password
Important

Replace the placeholder values with your actual credentials:

  • your-client-id and your-client-secret from the NetBox Diode setup
  • dhcp-server.corp.example.com with your Windows DHCP Server hostname or IP address
  • CORP\svc-netbox with your service account in DOMAIN\username format
  • your-password with the service account password
  1. Run the agent with the following command:
docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml
Security Best Practice

Add .env to your .gitignore file to prevent accidentally committing credentials to version control:

echo ".env" >> .gitignore

Expected Output​

After starting the agent, depending on the schedule you defined, you should see output similar to the following:

{"time":"2025-09-10T09:00:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.msft_dhcp_diode:Starting Microsoft DHCP integration for host: dhcp-server.corp.example.com"}
{"time":"2025-09-10T09:00:01.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.dhcp_client:Retrieved 6 DHCP scopes"}
{"time":"2025-09-10T09:00:01.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.prefixes:Building prefix entities from Microsoft DHCP scopes"}
{"time":"2025-09-10T09:00:01.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.prefixes:Built 6 prefix entities"}
{"time":"2025-09-10T09:00:01.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.exclusions:Building IP range entities from Microsoft DHCP exclusion ranges"}
{"time":"2025-09-10T09:00:01.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.exclusions:Built 3 IP range entities"}
{"time":"2025-09-10T09:00:01.789012345Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.ip_addresses:Building IP address entities from Microsoft DHCP leases and reservations"}
{"time":"2025-09-10T09:00:01.890123456Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.builders.ip_addresses:Built 24 IP address entities"}
{"time":"2025-09-10T09:00:02.001234567Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_msft_dhcp.msft_dhcp_diode:Returning 40 entities"}
{"time":"2025-09-10T09:00:02.112345678Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy msft_dhcp_worker: Successful ingestion"}
{"time":"2025-09-10T09:00:02.223456789Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: cron[month='*', day='*', day_of_week='*', hour='2', minute='0'], next run at: 2025-09-11 02:00:00 UTC)\" executed successfully"}
Monitoring and Testing

Success Indicators: Look for Successful ingestion in the output, which confirms data was sent to your NetBox instance via Diode.

Testing Mode: For testing purposes, run the agent once and then stop it by pressing Ctrl+C. This is useful for verifying configuration before setting up continuous operation.

Continuous Operation: The agent will continue running according to your schedule until manually stopped or the container is terminated.

View and Apply Discovered Data in NetBox Assurance​

Once the agent has run, DHCP data is staged as deviations in the NetBox Assurance UI.

NetBox Assurance gives you control over operational drift by identifying deviations between your operational state and NetBox, and analytics to understand drift and plan for remediation, and ultimately take action.

Understanding Deviations

Deviations are the delta between the data already in NetBox as the Network Source of Truth, versus the actual operational state of the network as discovered by the integration.

From an initial run, all discovered data may appear as deviations since it did not previously exist in NetBox. Once the initial sync is applied, subsequent runs will surface only new or changed data.

Accessing NetBox Assurance​

  1. Navigate to your NetBox instance
  2. Click on Assurance in the main navigation menu

Explore Deviation Types​

  1. Click on Deviation Types to view the types of deviations discovered View deviation types
  2. Click on the Name of a deviation type to view its deviations Discovered new IP range
  3. Click on the Name of an individual deviation to view the details Discovered IP range detail

View Active Deviations​

  1. Click on Active Deviations to view all deviations that have not yet been Applied or Ignored Active deviations
  2. Click on the Name of a deviation to view the details

Apply Deviations​

  1. Select all the deviations you want to apply. If you are working with a large number of deviations, first set the Per Page view to 500: select 500
  2. Select the first deviation, hold SHIFT and select the last one, then click Apply Selected: apply deviations
  3. Click Apply X Deviations to write the deviations to the NetBox database: confirm apply deviations
Apply Deviations to a Branch

Instead of writing to the Main NetBox database branch, you can select another branch from the drop-down and apply deviations there.

Assurance Docs

For more detailed information on working with NetBox Assurance, refer to the documentation.

View the Microsoft DHCP Data in NetBox​

After running the integration and applying the discovered data, you can view it in the NetBox UI.

  1. Navigate to IPAM → Prefixes to view synchronized DHCP scopes DHCP prefixes
  2. Select an individual prefix to view the details, including all DHCP scope custom fields Prefix details
  3. Navigate to IPAM → IP Ranges to view DHCP exclusion ranges DHCP IP ranges
  4. Navigate to IPAM → IP Addresses to view synchronized reservations and leases DHCP IP addresses
Filtering by Tag

Filter Prefixes, IP Ranges, and IP Addresses by the microsoft or dhcp tag to view only DHCP-discovered objects.

Additional Resources​

Support​

Email support@netboxlabs.com for support.

Related Topics
AssuranceAutomationDiscoveryGetting StartedIntegrationNetBox
Last updated on