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: 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: Does the integration support incremental sync? A: Yes, as an opt-in. By default, every run performs a full walk of the grid. Set INFOBLOX_INCREMENTAL_SYNC: true in the policy config to enable an incremental engine that processes only objects changed since the last run, using the Infoblox change feed and a watermark. Incremental sync requires Object Change Tracking (OCT) enabled on the grid (Grid → Grid Manager → Grid Properties → General → Advanced). If OCT is not enabled, the integration logs a warning and falls back to a full sync. The first run after enabling it, and any run after the agent restarts, performs a full sync to establish a baseline. VLAN and VLAN View data is always collected on a full walk, even in incremental mode.

Q: Can I trigger a sync on demand? A: Yes. Add a trigger_api block (with port and token_file) to the policy config to expose an authenticated POST /sync endpoint that starts a sync immediately. Requests must present the bearer token from the configured token file. When the block is omitted, syncs run only on the configured schedule.

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:

• Increase the timeout values in the agent configuration
• 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
• 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:

• Ensure you stopped the agent after seeing "executed successfully"
• Navigate to NetBox Assurance → Deviation Types
• 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)