Failover¶

Windows DHCP failover pairs two servers that share IPv4 scopes, in load balance or hot standby mode. Changes are made on one partner and replicated to the other.

The model¶

A Failover relationship (Windows DHCP > Failover relationships) holds:

"Primary" here is the plugin's word for the partner it writes to. It is not the Windows server role (active or standby).

Give both partners a Windows server in NetBox. The partner's host is what the relationship names on Windows (its computer_name when it is reached through a management host, else its host; short and fully qualified names match).

How it syncs¶

• Import cannot tell which partner should be the primary: the first partner imported becomes it. Import the server you want to write to first. After that, the partner's imports and pushes leave the relationship alone, and applying it from the partner is refused while NetBox holds it with the other server as primary.
• Push writes relationships, and the scopes in them, to the primary only. After a push to the primary, the scopes it changed are replicated to the partner with Invoke-DhcpServerv4FailoverReplication (all the relationship's scopes when a server-level object such as an option definition changed).
• A push to the partner server leaves the relationship's scopes alone: they belong to the primary.

So edit failover scopes as scopes of the primary server in NetBox; the partner's copies follow through replication.

Shared secret¶

With message authentication, put the secret in a credential profile and name it in Shared secret profile:

PLUGINS_CONFIG = {
    "netbox_windows_dhcp_plugin": {
        "credentials": {
            "failover-secret": {
                "secret_env": "DHCP_FAILOVER_SECRET",
                "allowed_hosts": ["dhcp1.corp.example", "dhcp2.corp.example"],
            },
        },
    },
}

The secret goes to both servers, so allowed_hosts must cover both partners; it is checked when the relationship is saved and again whenever a push sends the secret. It is read from the profile only when a push needs it, goes straight to the cmdlet, and is never stored or logged. NetBox only records whether authentication is on, so a secret rotated on Windows is not noticed. An imported relationship with authentication has no profile yet: the difference stays visible until you set one.

Scopes joining and leaving¶

• A scope added to a managed relationship's subnets is added to it on Windows.
• A scope removed from the relationship leaves it, which removes the scope from the partner (as Windows does). The plugin only does that for a relationship it manages, unchanged on Windows since the last push, and never for a scope NetBox does not manage.
• A scope deleted in NetBox leaves its relationship first, in the same push, after a lease check: a scope with leases is refused before anything changes.
• Removing a relationship removes its scopes from the partner, as Windows documents.

Changing the partner, or turning authentication off, is refused: Windows only allows it by removing the relationship.