FAQ & Troubleshooting

This document provides answers to commonly asked questions about the NetBox Infoblox NIOS integration.

General Questions

Q: Does the integration support multiple Infoblox Grid Masters? A: Yes, to ingest data from multiple Infoblox grids, you can run separate integration instances with different configurations, each pointing to a different Grid Master.

Q: Does the integration support multiple Network Views? A: Yes, the integration can synchronize data from multiple network views. You can configure which network views to sync in the agent configuration file.

Q: Can NetBox push configurations to Infoblox? A: No. The integration is currently data-in only, synchronizing from Infoblox NIOS into NetBox.

Q: Are objects deleted in Infoblox removed from NetBox? A: No. The integration does not delete NetBox objects. Prefixes, IP addresses, VLANs, and VLAN groups for objects deleted in Infoblox, including expired DHCP leases, stay in NetBox with the values from the last run that included them. Handle these removals manually.

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

Q: Do I have to buy NetBox Assurance to use the NetBox Infoblox integration? A: Yes. The NetBox Infoblox NIOS integration extracts and transforms the latest state from Infoblox NIOS which is sent to NetBox Assurance where users can control how it is ingested into NetBox.

Q: Which versions of NetBox are supported? A: 4.2.3 and above.

Q: Which versions of Infoblox NIOS are supported? A: This integration is compatible with Infoblox NIOS 8.x and 9.x using the WAPI (Web API) interface.

Technical Questions

Q: What authentication methods does the integration support? A: The integration supports basic authentication (username and password) to Infoblox NIOS WAPI. You need to provide valid Infoblox credentials with appropriate permissions to read network, DNS, and DHCP data.

Q: What permissions does the Infoblox user account need? A: The Infoblox user account needs read-only access to the following object types:

• Networks and network containers (IPv4 and IPv6)
• IP addresses (leases, fixed addresses, host records)
• DNS records (forward A and AAAA records)
• VLANs (including VLAN views and ranges)
• DHCP ranges (IPv4 and IPv6)
• Network views

Q: How does the integration handle API rate limits? A: The integration uses paginated requests with a maximum of 1000 results per page. For very large datasets, the integration iterates through all pages automatically. Standard HTTP timeouts (30 seconds) are applied to each request.

Q: How are Network Views handled in NetBox? A: Network Views are mapped to tags in NetBox for filtering and organization:

• Each object is tagged with infoblox-network-view:{view_name}
• All objects from a network view share the same tag
• You can filter objects in NetBox by network view using these tags
• VRFs are not created for network views - tagging provides the organizational structure

Q: Are Extensible Attributes synchronized? A: The integration retrieves VLAN associations from Infoblox networks, which are stored in the infoblox_vlans custom field on Prefix objects. Additional extensible attribute synchronization depends on the specific WAPI responses.

Q: What happens to container networks? A: Infoblox network containers are synchronized as NetBox prefixes with the following characteristics:

• Status: active
• Tagged with: network-container for identification
• The hierarchical relationship between containers and networks is maintained in NetBox through the prefix hierarchy

Q: How are hostnames handled? A: The dns_name field on IPAddress objects is populated from:

• Fixed address name field
• Host record (record:host) hostname
• Forward DNS A / AAAA record name
• DHCP lease client_hostname (when lease sync is enabled)

When more than one source contributes the same IP address, status comes from the first source while dns_name is filled by the first source with a non-empty value, so a nameless lease or fixed address does not suppress a real FQDN.

Q: Does the integration synchronize DNS records? A: Yes, forward DNS records. Infoblox A and AAAA records are synchronized as IP addresses (/32 and /128) with the record name as the dns_name and the record comment as the description; disabled records are skipped. This is on by default. Reverse DNS (PTR), CNAME records, and DNS zones are not synchronized.

Q: How are DHCP ranges synchronized? A: DHCP ranges are synchronized as Prefix objects in NetBox with the following characteristics:

• Status: active
• Tagged with: dhcp-range and role:dhcp
• CIDR prefix is calculated from the range's start and end addresses using address summarization
• Fixed addresses (DHCP reservations) are synchronized as IPAddress objects with status dhcp or reserved based on the match_client field

Q: What custom fields are required in NetBox? A: The integration creates the following custom fields during bootstrap:

• infoblox_match_client (IPAddress - Text) - DHCP client matching identifier
• infoblox_agent_circuit_id (IPAddress - Text) - DHCP relay agent circuit ID
• infoblox_agent_remote_id (IPAddress - Text) - DHCP relay agent remote ID
• infoblox_vlans (Prefix - JSON) - VLAN associations from Infoblox

Q: How often should the integration run? A: The recommended schedule depends on how frequently your Infoblox data changes. Common schedules include:

• Daily (e.g., 2:00 AM) for relatively stable environments
• Every 6 hours for environments with frequent changes
• Weekly for very stable environments

Q: Can I filter which networks are synchronized? A: Yes, you can use the scope configuration to filter by specific network views (e.g., only sync "production" view). Use network_views: ["*"] to sync all views, or specify individual views like network_views: ["default", "prod"].

Q: How does DNS view mapping work? A: For host record queries, the integration resolves each network view's DNS view using this precedence:

• An explicit entry in network_to_dns_view_mapping (scope configuration), if you provide one
• The DNS-view association discovered from the grid
• A naming convention fallback (default network view → default DNS view, others → default.{network_view}), used only if grid discovery fails

In most deployments you do not need to set network_to_dns_view_mapping; the grid-discovered association is used automatically. Example override: network_to_dns_view_mapping: {"prod": "prod-dns", "dev": "dev-dns"}

Q: What tags are automatically applied to objects? A: Objects are tagged with:

• Global tags: infoblox, discovered, and infoblox-{hostname} (hostname-specific tag)
• Network view tags: infoblox-network-view:{view_name} (for prefixes and IPs)
• DNS record tags: infoblox-dns-record:a / infoblox-dns-record:aaaa (IPs backed by forward DNS records)
• Container tags: network-container (for network containers)
• DHCP range tags: dhcp-range and role:dhcp
• VLAN tags: infoblox-vlan-view:{view}, infoblox-vlan-status:{status}, etc.

Q: Can the integration extract site information from Infoblox? A: Yes, the integration can extract site information from extensible attributes. If an Infoblox object has a Site extensible attribute, it will be used to set the site scope on the corresponding NetBox object (prefixes and VLAN groups).

Troubleshooting

Connection Issues

Problem: Connection to Infoblox WAPI fails with authentication errors Solution:

• Verify username and password are correct
• Check if the user account has the required read permissions
• Ensure the Infoblox Grid Master is accessible from your agent host
• Verify SSL certificate if using HTTPS (set INFOBLOX_SSL_VERIFY: false for testing only)

Problem: Authentication fails with "401 Unauthorized" Solution:

• Verify the username and password are correctly formatted in the .env file
• Check if the user account is locked or expired
• Ensure the user has permissions to access the WAPI
• Verify the user has access to the specified network views

Problem: API requests return "403 Forbidden" Solution:

• Check if the user account has sufficient permissions
• Verify the user has read access to the required object types
• Ensure the user has access to the specified network views
• Check if there are any IP-based access restrictions on the Grid Master

Problem: Connection timeout errors Solution:

• Verify network connectivity between the agent host and Grid Master
• Check firewall rules allow HTTPS traffic to the Grid Master
• Ensure the Grid Master hostname or IP is correct in the configuration
• Test connectivity using curl or wget to the WAPI endpoint

Common Error Messages

Missing required configuration (KeyError: 'INFOBLOX_HOST', 'INFOBLOX_USER', or 'INFOBLOX_PWD')

In non-bootstrap mode, INFOBLOX_HOST, INFOBLOX_USER, and INFOBLOX_PWD are all required. If one is missing, the run fails with a KeyError for that key, shown in the log as Fatal error running Infoblox backend: 'INFOBLOX_HOST' (with KeyError: 'INFOBLOX_HOST' in the traceback).

• Add the missing key to your policy config.
• Verify the hostname or IP address is correct and reachable.
• Check that the username and password are correct and properly escaped in the .env file.

scope.network_views configuration error: N network view(s) not found in Infoblox: [...]

• One or more names in scope.network_views do not exist on the grid. The error lists the missing views and the available ones.
• Verify the view names match exactly (case-sensitive), or use ["*"] to sync all views.
• Ensure the user has access to the specified network views.

WAPI request failures after setting INFOBLOX_VERSION

• The integration does not validate the WAPI version itself; an unsupported value causes the WAPI requests to fail against the grid.
• Remove INFOBLOX_VERSION to use the default (2.11), or set a version your NIOS grid supports.

Data Synchronization Issues

Problem: Not all networks are being synchronized Solution:

• Check the scope configuration for network view filters
• Verify the user has access to all required network views
• Check agent logs for any error messages about specific networks
• Ensure networks are not in a network view that's excluded from sync

Problem: DHCP ranges or VLANs are not synchronized Solution:

• Check if DHCP ranges or VLANs exist in the specified network views
• Ensure the user has read access to DHCP range and VLAN objects
• Review agent logs for DHCP or VLAN-related errors
• Verify the objects are in allowed network views

Problem: VLAN associations are not appearing in NetBox Solution:

• Verify the custom field infoblox_vlans was created during bootstrap
• Check that the networks in Infoblox actually have VLAN associations
• Review the custom field data on prefixes in NetBox to see if VLANs are stored in JSON format
• Ensure the user has read access to network and VLAN objects

Problem: Host records not synchronizing from certain network views Solution:

• The integration discovers each network view's DNS view from the grid automatically; check that the affected network view has a DNS view associated with it in Infoblox
• If discovery does not resolve the correct DNS view, set an explicit mapping with network_to_dns_view_mapping in scope config
• Only if grid discovery fails does the integration fall back to a naming convention (default → default, others → default.{network_view})
• Review agent logs for DNS view-related errors
• Ensure the user has access to the DNS views in Infoblox

Problem: Network status not set as expected Solution:

• Check the status field on prefixes in NetBox
• All networks (including containers) should show status active
• Container networks are identified by the network-container tag, not by status
• DHCP range prefixes are tagged with dhcp-range and role:dhcp
• Review the integration logs for any status mapping issues

Performance Issues

Problem: Integration takes a very long time to complete Solution:

• Limit synchronization to specific network views using scope configuration
• Check network latency between agent and Grid Master
• Review Infoblox Grid Master performance and load
• Consider breaking up large deployments into multiple agents with different network view scopes

Problem: Integration times out during synchronization Solution:

• Reduce the scope of data being synchronized
• Check Infoblox Grid Master performance
• Consider running the integration more frequently with smaller data sets

Bootstrap Issues

Problem: Bootstrap mode fails to create custom fields Solution:

• Ensure the Diode credentials have permission to create custom fields in NetBox
• Check NetBox Assurance for any errors during custom field creation
• On NetBox Enterprise before 2.3.0, verify the deviations are applied after bootstrap completes
• Review agent logs for specific error messages about custom field creation

Problem: Can't find deviations after bootstrap Solution:

• On NetBox Cloud and NetBox Enterprise 2.3.0 and later, this is expected. Bootstrap creates only custom fields, and the custom fields are created directly. Look for them under Customization > Custom Fields instead
• Ensure you stopped the agent after seeing "executed successfully"
• Navigate to NetBox Assurance → Deviation Types
• On NetBox Enterprise before 2.3.0, look for deviations related to custom fields (bootstrap only creates custom fields, not tags)
• Tags are created automatically during normal operation, not in bootstrap mode
• If no deviations appear, check agent logs for errors
• Verify bootstrap mode was actually enabled (BOOTSTRAP: True)