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: