FAQ & Troubleshooting

This document provides answers to commonly asked questions about the NetBox Microsoft DNS integration.

General Questions

Q: Does the integration support multiple DNS servers? A: Yes. Deploy a separate agent instance for each DNS server, each with its own configuration pointing to a different MSFT_DNS_HOST.

Q: Can NetBox push DNS records back to the Windows DNS Server? A: No. The integration is one-way - data flows from Microsoft DNS Server into NetBox only. No changes are written back to the DNS server.

Q: Are records deleted on the DNS server removed from NetBox? A: No. The integration does not delete NetBox objects. An IP address whose A, AAAA, or PTR record is deleted stays in NetBox with the values from the last run that included it. Handle these removals manually.

Q: Is the integration free to use? A: The Microsoft DNS integration is available with commercial editions of NetBox.

Q: Do I have to have NetBox Assurance to use this integration? A: Yes. The integration sends discovered data to NetBox via Diode and NetBox Assurance, where you review and apply changes before they are written to NetBox.

Q: Which versions of NetBox are supported? A: NetBox Cloud and NetBox Enterprise v4.2.3 and later.

Q: Does the integration sync reverse lookup zones? A: Yes. PTR records from reverse-lookup zones (*.in-addr.arpa and *.ip6.arpa) are synced as IP addresses. This surfaces statically-assigned IPs that have a reverse mapping but no forward A or AAAA record. Autocreated zones are excluded. When an IP has both a PTR record and forward records, the PTR target FQDN becomes the primary dns_name.

Q: Does the integration sync all record types? A: No. A records (IPv4), AAAA records (IPv6), and PTR records (reverse zones) are synchronized. Other record types (CNAME, MX, SRV, TXT, etc.) are not ingested.

Technical Questions

Q: What authentication method does the integration use? A: The integration uses NTLM authentication over WinRM (Windows Remote Management). No agent software needs to be installed on the Windows DNS Server.

Q: What permissions does the service account need? A: The account must be able to run Get-DnsServerZone and Get-DnsServerResourceRecord on the target server. Membership in the local Administrators group on the DNS server is sufficient. If you prefer a least-privilege approach, the account needs read access to the DNS Server PowerShell module.

Q: What happens when multiple DNS names point to the same IP address? A: All FQDNs for that IP are collected across all zones and deduplicated case-insensitively. If the IP has a PTR record, the PTR target FQDN is set as the primary dns_name; otherwise the alphabetically first forward name is used. Any remaining names are stored as a JSON array in the msft_dns_additional_names custom field.

Q: What tags are applied to synchronized objects? A: Every IP address ingested by the integration is tagged with microsoft, dns, discovered, and a unique per-server tag in the format msft-dns-{host} (e.g., msft-dns-dns-server.corp.example.com).

Q: How often should the integration run? A: This depends on how frequently your DNS records change. A daily schedule ("0 2 * * *") suits most environments. For environments with frequent changes, every 6 hours ("0 */6 * * *") is reasonable.

Q: Can I limit which zones are synchronized? A: Yes. Use MSFT_DNS_INCLUDE_ZONES to specify zones or glob patterns to include, and MSFT_DNS_EXCLUDE_ZONES to exclude zones. Both settings support fnmatch glob patterns and are case-insensitive. Exclude is applied after include and always takes precedence. These filters apply to forward-lookup zones; reverse (PTR) records are scoped by their target FQDN instead.

Q: Can I assign discovered IP addresses to a NetBox tenant? A: Yes. Use MSFT_DNS_ZONE_TENANT_MAP to map zone names or glob patterns to NetBox tenant names. IP addresses discovered in a matching zone are assigned that tenant, and each mapped tenant is created in NetBox if it does not already exist. This is aimed at MSP and multi-client deployments where one DNS server hosts zones for several clients. Reverse (PTR) zones are not tenant-mapped, so an IP discovered only via PTR carries no tenant.

Q: What is the BOOTSTRAP setting for? A: Bootstrap mode creates the msft_dns_additional_names custom field in NetBox without connecting to the DNS server. Run it once before the first full sync, then set BOOTSTRAP: False for all subsequent runs. On NetBox Cloud and NetBox Enterprise 2.3.0 and later, the custom field is created directly. On NetBox Enterprise before 2.3.0, also apply the resulting deviation in NetBox Assurance.

Troubleshooting

WinRM Connection Issues

Problem: The agent cannot connect to the Windows DNS Server

Verify WinRM is enabled on the target server. Run winrm quickconfig on the server or check that the WinRM service is running
Confirm port 5986 (HTTPS) or 5985 (HTTP) is reachable from the agent host
Check firewall rules on the Windows Server and any intermediate network devices
Test basic connectivity with Test-WsMan -ComputerName <hostname> from another Windows machine on the same network

Problem: Authentication fails with an NTLM error

Verify the username format is DOMAIN\username (or .\username for local accounts)
Check the password is correct and has not expired
Ensure the account is a member of the local Administrators group on the DNS server
If using a domain account, confirm the agent host can reach the domain controller for NTLM negotiation

Problem: SSL/TLS certificate errors when connecting over WinRM HTTPS

Windows servers commonly use self-signed certificates for WinRM. The default configuration sets MSFT_DNS_VERIFY_SSL: false to accommodate this
If you have a valid certificate on the WinRM HTTPS listener, you can set MSFT_DNS_VERIFY_SSL: true
To use HTTP instead (not recommended for production), set MSFT_DNS_USE_SSL: false - this switches to port 5985

Problem: Connection is refused or times out

Check that the WinRM listener is configured. Run winrm enumerate winrm/config/listener on the server to confirm listeners are active
Verify you are using the correct port. The default for HTTPS WinRM is 5986; for HTTP it is 5985
To override the port, set MSFT_DNS_PORT in your configuration

Configuration Issues

Problem: Missing required config errors in the agent log

ValueError: Missing required config: MSFT_DNS_HOST, MSFT_DNS_USERNAME

Ensure all required environment variables are set: MSFT_DNS_HOST, MSFT_DNS_USERNAME, MSFT_DNS_PASSWORD
If using a .env file, confirm the file path is correct and the variables are not commented out
Check the docker run command passes either --env-file .env or individual -e flags for each variable

Problem: Zone filtering results in zero zones being synced

Check your MSFT_DNS_INCLUDE_ZONES patterns match at least one zone on the server
Pattern matching is case-insensitive but must otherwise match the full zone name
If the agent logs a warning that zones were discovered but all filtered out, adjust your include/exclude patterns
Setting MSFT_DNS_INCLUDE_ZONES: [] (empty list) intentionally syncs zero zones - omit the key to sync all zones

Data Issues

Problem: Expected IP addresses are not appearing in NetBox

Confirm the DNS zone containing those records is not excluded by your zone filters
Check the agent logs for the number of A and AAAA records retrieved per zone
Verify the records exist in a forward-lookup zone (A/AAAA) or a reverse-lookup zone (PTR)
Run the agent in dry run mode to inspect the raw entity output before it reaches NetBox

Problem: DNS names are not appearing on IP address objects

The dns_name field is populated from the FQDN constructed as HostName.ZoneName
Check that the zone name is correct and records have a valid HostName
Records with @ as the hostname use the zone name itself as the FQDN

Problem: The msft_dns_additional_names custom field is missing in NetBox

This field is created during bootstrap mode. If it is not present, run the agent once with BOOTSTRAP: True, then switch back to BOOTSTRAP: False. On NetBox Enterprise before 2.3.0, also apply the resulting deviation in NetBox Assurance

Bootstrap Issues

Problem: No deviations appear in NetBox Assurance after bootstrap

On NetBox Cloud and NetBox Enterprise 2.3.0 and later, this is expected. Bootstrap creates only a custom field, and the custom field is created directly. Look for msft_dns_additional_names under Customization > Custom Fields instead
Confirm BOOTSTRAP: True is set in the policy config (not just as an environment variable)
Check the agent log for Added 1 Microsoft DNS custom fields
On NetBox Enterprise before 2.3.0, navigate to Assurance → Deviation Types after stopping the agent and look for a custom field deviation
If nothing appears, check the Diode target and credentials are correct

Problem: Bootstrap mode still attempts to connect to the DNS server

In bootstrap mode the agent should not connect to the DNS server. If you see connection attempts, verify BOOTSTRAP: True is parsed correctly (it must be the boolean True, not the string "True")