DHCP Discovery (Windows Discovery Agent)

DHCP discovery is a feature of the LightMesh Windows Discovery Agent. The agent runs on your Windows DHCP server, collects scope and lease data through Microsoft DHCP PowerShell cmdlets, caches it locally, and syncs it to LightMesh. After the first successful sync, LightMesh shows DHCP servers, scopes, leases, lease history, and DHCP-linked IP address state next to your IPAM data.

Windows Server Core: Use the dedicated DHCP Discovery on Windows Server Core guide. Server Core requires the headless zip (not the desktop MSI) and PowerShell service registration instead of the in-app dashboard.

Prerequisites

On the Windows machine where you install the agent:

• Operating system: 64-bit Windows (x86_64). Windows Server 2016 or later is recommended for production DHCP collection.

• DHCP PowerShell module: The Microsoft DHCP cmdlets the agent calls must be available on that server:

  IPv4

  • Get-DhcpServerv4Scope
  • Get-DhcpServerv4Lease (per scope)
  • Get-DhcpServerv4Reservation (per scope)
  • Get-DhcpServerv4ExclusionRange (per scope)
  • Get-DhcpServerv4OptionValue (per scope)
  • Get-DhcpServerv4Failover (once per cycle)

  IPv6

  • Get-DhcpServerv6Scope
  • Get-DhcpServerv6Lease (per prefix)
  • Get-DhcpServerv6Reservation (per prefix)
  • Get-DhcpServerv6ExclusionRange (per prefix)
  • Get-DhcpServerv6OptionValue (per prefix)

• Permissions: Local administrator rights to install, uninstall, or control the Windows service (expect a UAC prompt). The service itself can run under a configured service account after installation.

• Network: Outbound HTTPS from the DHCP server to your LightMesh URL (see examples below). The server must resolve and reach that host.

• Disk: Write access for the SQLite database file and agent log files (default paths are under the agent install directory).

LightMesh URL examples

Set Base URL in the agent to the same hostname you use in the browser, without a trailing path such as /graphql. Examples:

• SaaS: https://next.lightmesh.com
• Self-hosted: https://mylightmesh.domain.com (replace with your tenant hostname)

Who can create API keys and download the agent

Sign in to LightMesh as a user with the Owner or Administrator application role. Those roles can open Admin > API Keys to create keys and Settings > Downloads to download the Windows Discovery Agent. If your organization uses custom roles, use whichever role your admin assigns for those menus.

1. Create a DHCP Server API key

1. Go to Admin > API Keys.
2. Create a new API key for the agent.
3. Set Role to DHCP Server so the key can sync DHCP scopes, leases, and lease history without full tenant API access.

Copy the generated key and store it securely. You will paste it into the agent as the API token.

2. Download the Windows Discovery Agent

1. Go to Settings > Downloads.
2. On the Windows Discovery Agent card, select the DHCP tab.
3. Expand System requirements if you need OS, permissions, DHCP cmdlet, network, or disk details for your environment.
4. Under Windows installer (.msi), click Download MSI.

Use the MSI for full Windows Server (with Desktop Experience), Windows 10, or Windows 11. Do not use the MSI as the primary install on Windows Server Core — use the Server Core package (.zip) in the Windows Server Core guide instead.

The same card lists a Server Core package (.zip) on the right for headless deployments. The DNS and SNMP tabs are placeholders for future discovery types; they are not separate agent downloads today.

Optional direct download (same MSI as Download MSI):

https://get.lightmesh.com/lightmesh-discovery-agent-win-64-latest

Run the MSI on the Windows DHCP server that will run collection.

3. Open the LightMesh Discovery Agent

Run the discovery agent on Windows as Administrator:

1. Right-click lightmesh-discovery-agent.exe.
2. Click Run as administrator.

Administrator rights are required to install and register the Windows service. Without them, Register on the Dashboard may fail or prompt for elevation.

The app opens Dashboard, Configuration, Logs, and Help & Setup.

If the window fails to open, look for startup_error.log next to the executable.

4. Configure the agent

Open Configuration. The footer shows the path to config.toml (for example under C:\Program Files\lightmesh-discovery-agent\bin\).

LightMesh API

Expand LightMesh API and set:

• Base URL: Your LightMesh URL (see examples above).
• API Token: The DHCP Server API key from step 1.
• DHCP Server ID (GraphQL): Usually leave blank on first run; the agent can bootstrap an ID when needed.

Live connectivity check (Base URL)

The Base URL field includes a built-in connectivity probe. After you enter Base URL and API Token, the agent automatically tests https://<host>/graphql using the values in the form — you do not need to click Save & Apply first.

• Checking… — probe in progress (spinner).
• OK with a green checkmark — HTTP 2xx and no GraphQL errors; the URL and token can reach LightMesh.
• Failed with a red cross — a short summary plus hints (DNS, TCP, TLS, proxy, timeout, HTTP 401/403/404/5xx, or GraphQL application errors).

Use Refresh on the Base URL row to run the probe again after you change credentials or fix network issues.

Run this check before Register on the Dashboard so the Windows service starts with a valid LightMesh connection.

Collector: poll interval

Expand Collector. Poll Interval (secs) is how often the Windows service wakes up, runs DHCP collection, and pushes changes to LightMesh. The default is often 300 (five minutes). Larger intervals reduce load; smaller intervals refresh LightMesh sooner.

This setting works together with Polling Interval on the DHCP server detail page in LightMesh (for example Every 5 minutes). Align agent poll interval and LightMesh polling expectations with your operations team so refresh cadence matches what you monitor.

SQLite: queue batch size and retries

Expand SQLite:

• Database Path: Local SQLite file used as cache and outbound queue.
• Queue Batch Size: Maximum number of queued entities sent per batch to LightMesh during sync. Increase it on busy servers with large lease counts if your deployment supports larger payloads; decrease it if you hit timeouts or payload limits.
• Max Send Attempts, Retry Base (secs), Retry Max (secs): Control retries when LightMesh is unreachable or returns errors.

Click Save & Apply after you enter your settings so they are written to config.toml.

5. Register and start the Windows service

Before you click Register (or Register Service) on the Dashboard, confirm in Configuration that Base URL and API Token are set correctly and that you clicked Save & Apply. Registering the service before those values are saved can leave the service running without a valid LightMesh connection.

Use the Dashboard to register and start the service, or run from an elevated PowerShell prompt:

.\lightmesh-discovery-agent.exe --service-install
.\lightmesh-discovery-agent.exe --service-start

For a one-off foreground run:

.\lightmesh-discovery-agent.exe --service-run

After the service is running, scope counts, lease counts, queue depth, and sync history update on the Dashboard.

6. Logs in the agent

Open Logs to inspect what the agent is doing.

• Reload refreshes the view; Auto-scroll follows new lines when enabled.
• App logs only hides noisy graphics stack lines (for example GPU or wgpu-related messages) so DHCP collection and LightMesh sync lines are easier to read.
• The viewer shows roughly the last 5000 lines of the log file.

Important: Detailed DHCP collection and LightMesh sync messages appear when the Windows service runs a cycle or when you trigger Run collection now from the tray or dashboard. Simply leaving the Configuration window open without a running collection does not produce those lines.

Typical INFO lines include counts for IPv4 and IPv6 scopes, leases, reservations, exclusion ranges, option values, and failover relationships, followed by queue flush or service cycle completed.

7. DHCP in LightMesh: servers, scopes, and parent subnet

After sync succeeds, open DHCP in the top navigation. Use Servers, Scopes, and Leases to browse what the agent imported.

On a DHCP server detail page you can change Polling Interval, Pause Sync / Resume Sync, and review each scope.

Parent Subnet opens Subnets > IP Addresses

On the server Scopes table, the Parent Subnet column shows the subnet LightMesh associated with each scope (for example 10.60.0.0/21). Click the external link icon next to the subnet to open that subnet in Subnets with the IP Addresses tab. That view lists DHCP-sourced assignments for addresses inside the scope range; set the row filter to DHCP when you want only DHCP-backed addresses.

Open an individual scope or lease from Scopes / Leases to see utilization, lease rows, and lease history drawers as in the main LightMesh DHCP UI.

Operational notes

• Pause Sync stops updates for selected servers or scopes without deleting the last known DHCP data in LightMesh.
• Resume Sync allows the agent to update those records again on the next cycle.
• Archive marks a server archived; scopes and leases show last-known state until you restore the server.
• Export on the global Scopes tab downloads CSV exports for selected scopes or all scopes.
• The agent keeps a local queue in SQLite. If LightMesh is unavailable, sends retry with exponential backoff up to Max Send Attempts.

Troubleshooting

If DHCP data does not appear in LightMesh:

1. Confirm the Windows service is running and the Dashboard shows recent sync activity.

2. Open Configuration and check the Base URL connectivity probe. Fix Base URL or API Token until the probe shows OK, then Save & Apply and restart the service if needed.

3. Open Logs, disable App logs only temporarily if you need full detail, and look for PowerShell, authentication, or network errors. Failed sync cycles log an actionable summary (for example DNS, TCP, TLS, proxy, or HTTP 401/403).

4. Confirm the API key uses the DHCP Server role and has not expired.

5. On the DHCP server, verify cmdlets succeed, for example:

   Get-DhcpServerv4Scope | Select-Object ScopeId,Name,State
   

6. Confirm Base URL uses a hostname reachable from the Windows server (avoid localhost unless LightMesh runs on the same machine). From PowerShell on the collector you can also run:

   Resolve-DnsName <host-from-base-url>
   Test-NetConnection <host-from-base-url> -Port 443
   netsh winhttp show proxy
   

If the connectivity probe or logs mention IPv6 and IPv4, IPv6 routing may be broken while IPv4 works — common on some enterprise networks. If logs mention TLS certificate validation, install your organization’s SSL inspection root into the Windows certificate store.

Once collection and sync succeed, each polling cycle refreshes DHCP data in LightMesh and the IP Addresses views linked from Parent Subnet.