Technical Information
Microsoft DNS to NetBox Object Mapping
Object Type Mapping
| Microsoft DNS Object | NetBox Object | Notes |
|---|---|---|
| A record (IPv4) | IPAddress | Address as /32 CIDR; dns_name set to FQDN; status = active |
| AAAA record (IPv6) | IPAddress | Address as /128 CIDR; dns_name set to FQDN; status = active |
Only forward-lookup zones are processed. Reverse lookup zones and autocreated zones are excluded.
IP Address Field Mapping
| NetBox Field | Source | Notes |
|---|---|---|
address | Address field from DNS record | Formatted as CIDR - /32 for A records, /128 for AAAA records |
dns_name | HostName + ZoneName | Constructed as HostName.ZoneName; uses ZoneName alone when HostName is @ or empty |
status | Static | Always active |
description | Static | Microsoft DNS - {host}, A record or Microsoft DNS - {host}, AAAA record |
Multiple DNS Names
When more than one DNS record points to the same IP address, the integration:
- Collects all FQDNs for that IP across all zones
- Sorts them alphabetically
- Sets the alphabetically first FQDN as
dns_name - Stores all remaining FQDNs in the
msft_dns_additional_namescustom field as a JSON array
Example: IP 10.0.1.10 with A records for portal.corp.example.com, web1.corp.example.com, and www.corp.example.com:
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 mode and applied to IP Address objects:
| Custom Field Name | Label | Type | Object Type | Description |
|---|---|---|---|---|
msft_dns_additional_names | Microsoft DNS Additional Names | JSON | ipam.ipaddress | Additional DNS names pointing to this IP address |
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:
| Tag | Description |
|---|---|
microsoft | Applied to all entities from this integration |
dns | Identifies objects sourced from a DNS server |
discovered | Standard tag applied to all controller integration objects |
msft-dns-{host} | Unique per-agent tag identifying the source DNS server; e.g., msft-dns-dns-server.corp.example.com |
Zone Filtering Behavior
| Scenario | Result |
|---|---|
Neither INCLUDE_ZONES nor EXCLUDE_ZONES set | All forward-lookup zones are synced |
INCLUDE_ZONES set | Only zones matching at least one include pattern are synced |
EXCLUDE_ZONES set | Zones matching any exclude pattern are removed from the result set |
| Both set | Include filter applied first, then exclude filter |
INCLUDE_ZONES: [] (empty list) | Zero zones synced |
EXCLUDE_ZONES: [] (empty list) | No zones excluded (equivalent to omitting the key) |
| All zones filtered out after discovery | Warning logged |
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.
Configuration Reference
| Parameter | Type | Default | Description |
|---|---|---|---|
MSFT_DNS_HOST | string | required | Windows DNS Server hostname or IP address |
MSFT_DNS_USERNAME | string | required | WinRM service account (typically DOMAIN\username) |
MSFT_DNS_PASSWORD | string | required | WinRM service account password |
MSFT_DNS_USE_SSL | bool | true | Use HTTPS WinRM on port 5986; set false for HTTP on port 5985 |
MSFT_DNS_PORT | int | 5986 / 5985 | Override the default WinRM port |
MSFT_DNS_VERIFY_SSL | bool | false | Verify the WinRM TLS certificate; off by default as Windows servers commonly use self-signed certificates |
MSFT_DNS_INCLUDE_ZONES | list[string] | null (all zones) | Glob patterns or exact zone names; only matching zones are synced |
MSFT_DNS_EXCLUDE_ZONES | list[string] | null (none excluded) | Glob patterns or exact zone names; applied after include filter |
BOOTSTRAP | bool | false | When true, emits only custom field definitions with no DNS server connection required |
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:
| Cmdlet | Purpose |
|---|---|
Get-DnsServerZone | Retrieves all DNS zones; filtered to forward-lookup, non-autocreated zones |
Get-DnsServerResourceRecord -RRType A | Retrieves A records for each zone |
Get-DnsServerResourceRecord -RRType AAAA | Retrieves AAAA records for each zone |