Technical Information

Microsoft DNS to NetBox Object Mapping

Object Type Mapping

Forward-lookup zones are processed for A and AAAA records, and reverse-lookup zones (*.in-addr.arpa, *.ip6.arpa) are processed for PTR records. Autocreated zones are excluded.

IP Address Field Mapping

Multiple DNS Names

When more than one DNS record points to the same IP address, the integration:

1. Collects all FQDNs for that IP across all zones, deduplicated case-insensitively (DNS names are case-insensitive per RFC 4343)
2. Selects the primary dns_name:
   • If the IP has a PTR record, the PTR target FQDN becomes the primary dns_name (a PTR is the authoritative reverse mapping), and the forward names move to the additional-names field
   • Otherwise, the alphabetically first forward (A/AAAA) FQDN is used
3. Stores all remaining FQDNs in the msft_dns_additional_names custom field as a JSON array

The tie-break is deterministic and independent of zone processing order, so the same input always produces the same primary dns_name.

Example: IP 10.0.1.10 with A records for portal.corp.example.com, web1.corp.example.com, and www.corp.example.com (no PTR record):

• dns_name: portal.corp.example.com (alphabetically first)
• msft_dns_additional_names: ["web1.corp.example.com", "www.corp.example.com"]

Custom Fields

The following custom field is created during bootstrap and applied to IP Address objects:

Custom fields are read-only in the NetBox UI (ui_editable: no).

Tags

All IP Address entities ingested by the Microsoft DNS integration are tagged with:

Zone Filtering Behavior

Patterns use fnmatch glob syntax. Matching is case-insensitive (RFC 1035). Filtering happens before per-zone record queries, so excluded zones incur no API round-trip.

Zone filters apply to forward-lookup zones only. Reverse-lookup zones are not matched against MSFT_DNS_INCLUDE_ZONES / MSFT_DNS_EXCLUDE_ZONES. Instead, each PTR record is scoped by its target FQDN and that FQDN's parent domains, which makes reverse scoping intentionally more permissive than forward scoping for exact (non-glob) patterns. To confine reverse sync to a single label, use a glob pattern (for example *.example.com) rather than an exact zone name.

Zone-to-tenant mapping

MSFT_DNS_ZONE_TENANT_MAP assigns a NetBox tenant to the IP addresses discovered in matching zones. It is aimed at MSP and multi-client deployments where one Microsoft DNS server hosts zones for many end-clients and each client's records should land under its own tenant.

The value maps a zone name (or fnmatch glob pattern) to a tenant name:

config:
  MSFT_DNS_ZONE_TENANT_MAP:
    "client-a.local": "Client A"
    "client-b.corp": "Client B"
    "*.internal": "Internal"

The environment-variable form uses zone:tenant pairs separated by commas: MSFT_DNS_ZONE_TENANT_MAP="client-a.local:Client A,*.internal:Internal". In this form, zone patterns and tenant names must not contain : or ,.

Matching behavior:

• Zone names are matched case-insensitively, using the same glob rules as MSFT_DNS_INCLUDE_ZONES.
• An exact zone-name match wins over any glob pattern; among glob patterns, the first match in declaration order wins.
• A zone that matches nothing gets no tenant.
• When an IP is referenced by records in more than one zone, the tenant is resolved from the zone of the alphabetically-first forward (A/AAAA) FQDN. Reverse (PTR) zones are never tenant-mapped, so an IP discovered only via PTR carries no tenant.

Each distinct mapped tenant is emitted as a Tenant entity (deduplicated by name, with a slugified slug). Diode creates the tenant in NetBox if it does not already exist. Tenant names must produce distinct slugs; the integration rejects a configuration whose tenant names collapse to the same slug (for example Internal and internal).

Configuration Reference

Connection Details

The integration uses the pypsrp library to connect over WinRM/PSRP with NTLM authentication. The following PowerShell cmdlets are executed on the target server:

Known Limitations

• Records deleted on the DNS server are not removed from NetBox. The integration does not delete NetBox objects. When an A, AAAA, or PTR record is deleted, or its zone is no longer synced, the IP address stays in NetBox with the values from the last run that included it. Handle these removals manually.