netbox-windows-dhcp-plugin

A NetBox plugin that models Microsoft Windows DHCP servers in NetBox and keeps both in step, in both directions, over WinRM or SSH.

Documentation: https://thomaschristory.github.io/netbox-windows-dhcp-plugin/

Status: 0.2.0rc1, release candidate. The plugin no longer needs netbox-plugin-dhcp: it holds the whole Windows DHCP configuration in its own models. 0.2.0 is a fresh start from 0.1.x (see the upgrade notes). Every v1 feature is built and tested against an in-memory fake server and PowerShell stubs. The Windows side (scripts, transports, sync rules) is that of 0.1.x, apart from option values now being lists; 0.1.0's lab tests ran in full against two Windows Server 2022 DHCP servers (import, push, leases and failover, over WinRM HTTP and HTTPS and over SSH). 0.2.0 passed the full lab tests (make test-lab, make lab-e2e) on two Windows Server 2025 servers over WinRM HTTP with CredSSP. Kerberos and SSH key authentication have not been tried on a real server yet (see the limitations). Try it on a lab server first.

Features

• Import from Windows, on demand or every import_interval minutes. With netbox-branching each import lands in a branch (plus a change request with netbox-change-control); without it, in an import proposal whose items you apply or dismiss.
• Push to Windows: a reconcile per server when a branch is merged, or a few seconds after a save without branching, plus "Sync now" and "Dry run". A push only deletes Windows objects NetBox manages; objects made by hand on Windows are left alone until imported.
• IPv4 scopes, superscopes, exclusion ranges, reservations, option definitions and values, user and vendor classes, vendor class options, policies, failover relationships (with replication to the partner) and MAC filters, each a plugin model. Scopes and reservations point at NetBox prefixes, IP ranges, IP addresses and MAC addresses, so the addresses show up in IPAM too. A Windows server can be linked to its device or virtual machine.
• DHCPv6 scopes, reservations (DUID and IAID), user classes and option values.
• A Leases tab on the scope page, read live from Windows in a background job.
• WinRM (NTLM, Kerberos, Basic, CredSSP for failover; HTTPS by default) or SSH, as in terraform-provider-windowsddi. Credentials live in named profiles in the plugin configuration, limited to allowed_hosts, never in the database.
• REST API and GraphQL for every model; all Windows I/O in background jobs.

Compatibility

Plugin	NetBox	netbox-plugin-dhcp	netbox-branching	Python
0.2.x	4.7	not used	1.2.2+ (optional)	3.12 to 3.14
0.1.x	4.7	0.2.x (required)	1.2.2+ (optional)	3.12 to 3.14

main is the 0.2 line. The 0.1.x line (latest 0.1.1, branch release/0.1) keeps getting bug fixes, but no new features, for installs that stay on netbox-plugin-dhcp: pin netbox-windows-dhcp-plugin<0.2 to stay on it.

Windows Server 2016 or later with the DHCP Server role.

Quick start

pip install --pre netbox-windows-dhcp-plugin   # or ==0.2.0rc1; 0.1.x stays the default until 0.2.0 is out
# extras: [kerberos] for Kerberos (needs system GSSAPI libraries), [branching] for branching and change control

PLUGINS = ["netbox_windows_dhcp_plugin"]

PLUGINS_CONFIG = {
    "netbox_windows_dhcp_plugin": {
        "credentials": {
            "dhcp-admin": {
                "username": "CORP\\svc-netbox-dhcp",
                "password_env": "DHCP_ADMIN_PASSWORD",
                "allowed_hosts": ["dhcp*.corp.example"],
            },
        },
    },
}

Run python manage.py migrate, restart NetBox and its worker, then add a Windows server under Windows DHCP > Windows servers, click Test connection and Import now (Import with netbox-branching). The first sync walkthrough covers the rest.

Documentation

• Installation and preparing Windows
• Configuration and security
• How objects map, import and push
• Permissions, REST API and GraphQL, troubleshooting
• Design and changelog

The same pages are in the docs/ folder of the repository.

Development

Requires uv and Docker.

make lint        # ruff check and format check
make test        # unit tests, no NetBox needed
make dev         # NetBox, branching and change control in docker
make test-netbox # NetBox integration tests inside the dev stack
make docs        # build the documentation site
make dist        # build and check the wheel and sdist

See Development for the lab tests against a real Windows server.

License

Apache-2.0, see LICENSE.