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: 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: No. Only forward-lookup zones are processed. Reverse lookup zones and autocreated zones are excluded.

Q: Does the integration sync all record types? A: No. Only A records (IPv4) and AAAA records (IPv6) are synchronized. Other record types (CNAME, MX, PTR, 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. The alphabetically first name is set as the dns_name field on the NetBox IP address object. 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.

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, apply the resulting deviation in NetBox Assurance, then set BOOTSTRAP: False for all subsequent runs.

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 (not a reverse zone)
• 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, apply the resulting deviation in NetBox Assurance, then switch back to BOOTSTRAP: False

Bootstrap Issues

Problem: No deviations appear in NetBox Assurance after bootstrap

• 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
• After stopping the agent, navigate to Assurance → Deviation Types 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")