netbox-windows-dhcp-plugin

A NetBox plugin that keeps Microsoft Windows DHCP servers in step with the data modelled by netbox-plugin-dhcp, in both directions, over WinRM or SSH.

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

Status: pre-release. Every v1 feature is built and tested against an in-memory fake server and PowerShell stubs. Some cmdlets the plugin uses have not been checked against a real Windows server yet; they are marked # unverified: in the code, and the lab tests that settle them are waiting for a lab server (see the roadmap and 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.
• DHCPv6 scopes, reservations (DUID and IAID), user classes and option values.
• A Leases tab on the subnet page, read live from Windows in a background job.
• WinRM (NTLM, Kerberos, Basic; 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

Windows Server 2016 or later with the DHCP Server role.

Quick start

pip install --pre netbox-windows-dhcp-plugin   # or ==0.1.0rc1; --pre is needed until 0.1.0 is out
# extras: [kerberos] for Kerberos (needs system GSSAPI libraries), [branching] for branching and change control

PLUGINS = ["netbox_dhcp", "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. 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, netbox-plugin-dhcp, 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.