-
Notifications
You must be signed in to change notification settings - Fork 2.6k
Frequently Asked Questions
- Why Doesn't NetBox Scan for IPs?
- Why Does NetBox Require Every IP to Have a Mask?
- Is There a Maximum Number of Objects I can Define?
- Why Can't I Connect a Virtual Circuit to an Interface?
- How Can I Add New Interface Types?
- Why Does NetBox Support Only Image Attachments?
- Why Aren't Device Type Component Modifications Retroactive?
- Why Can't Circuits Have More Than Two Terminations?
- Why Can't I Pass Exported Data Directly Into the Import Form?
- How Can I Model Half-Width Devices?
NetBox does not do any probing of IP addresses natively, for several reasons.
There are myriad standalone IP scanning tools available. nmap is arguably the most popular, though many others exist. We could not begin to match the maturity and efficiency of these tools by writing our own from scratch. Users are much better served by using these tools directly and then, after careful review of the results, importing data into NetBox manually.
Let's assume we implemented some form of wrapper around nmap or another tool so that it could be used directly from NetBox. This means that everything you want to scan must be reachable by the server(s) on which NetBox is installed. It's very likely that your security policy may not allow NetBox to talk directly with every node on the network.
And even if it does, you might not want it to. For example, suppose you have NetBox running in the United States and need to scan a /16 of IPv4 space in China. Rather than transmitting 65,000 probes across the Pacific, it would be much more efficient to scan the network from a bastion host in the same country.
But suppose your network is entirely constrained to a single geographic region and NetBox can talk to everything. You still have to deal with the reality that scanning isn't going to be 100% correct. Scanning can't tell you for certain whether an IP is in use; only whether it is responsive at a given moment. For example, suppose a host is temporarily offline, or has been configured to block ICMP requests. These won't show up in your scan.
What happens when a previously defined IP stops showing up in a scan? Should it be deleted? The host might actually still exist, though. Maybe we should mark it as "previously used" somehow. But then we're still using a database record to track an IP that might not even exist. And should we automatically add new IPs that pop up? What if they're not supposed to be there?
All this boils down to a single concept: NetBox is intended to represent the intended state of the network, as defined by humans, whereas scanning a live network reflects only its actual state at that moment. When you attempt to define the correct state by referencing the actual state with no intermediate process of validation, bad things happen.
The subnet mask is part of an IP address: You cannot assign an IP address to an interface in the real world without also specifying its subnet mask. A device uses its interface's mask to determine the boundary of its layer two domain.
In keeping with its core design philosophy of directly modeling the real world, NetBox requires that the subnet mask be stored along with each IP address. This allows users to validate real-world configurations against NetBox data in a very efficient manner, as well as aiding the detection of invalid addresses within NetBox.
Omitting the mask from the IP address model would require us to make dangerous inferences about each IP address. For example, if you are given only the IP address 192.0.2.123, you cannot determine its network without additional information. You could look for its most-specific parent prefix: let's assume 192.0.2.0/24 has been created. But that doesn't necessarily indicate that our IP has a /24 mask. That /24 might be a smaller container used for administrative organization inside a larger parent, or there might be a more-specific /25 or /26 prefix missing from NetBox. Or it could be a loopback IP that should have a /32 mask.
Treating an IP address and its subnet mask as an atomic unit ensures a much greater degree of efficiency and accuracy.
NetBox does not enforce any firm caps on the number of objects of any type created in NetBox. The only real limitation is the size of the PostgreSQL database which powers NetBox, and this is very unlikely to become a concern for real-world use. Despite NetBox being in use by many thousands of organizations globally for many years, we have yet to receive any reports of users encountering problems concerning the number of objects defined.
It's important to understand the difference between physical and virtual circuits. Suppose you have five sites arranged in a hub-and-spoke topology. The hub site has a point-to-point virtual circuit to each of its spoke sites; spoke-to-spoke traffic must pass through the hub. The virtual circuits are configured as 802.1Q-tagged subinterfaces on the hub site's router.
In this scenario, there are five physical circuits: One to each of the five sites from the provider. These five circuits carry traffic to support an overlay comprising four virtual circuits (one to each spoke site from the hub). A physical circuit is responsible for the physical transmission of a signal from one point to another, whereas a virtual circuit is a purely logical construct.
NetBox models only physical circuits, which can be terminated to physical interfaces on devices. While the ability to model virtual circuits would certainly be useful, it is impractical to account for the myriad technologies which might be used to establish a topology.
The set of available interface types (previously referred to as "form factors" in early releases) is statically defined in NetBox. Users cannot add arbitrary types for interfaces (or other device components). There are several reasons for this:
- An interface type represents an actual classification that exists in the real world, such as 1000BASE-T or SFP+. Unless your organization manufactures custom network hardware, it is extremely unlikely that you'll need to define a new interface type.
- Allowing users to define arbitrary types would very likely lead to the creation of duplicate or redundant types.
- Representing each type as a database object would impose a substantial performance penalty.
- Allowing custom types would make the device library much more difficult, if not impossible, to use.
- Limiting types to the predefined set clearly conveys NetBox's scope as a source of truth for network infrastructure.
However, if you encounter a new commercially-available interface type that has not yet been added to NetBox, please consider opening a feature request to have it added.
NetBox supports the attachment of images to certain models, namely sites, racks, and devices. This feature was added as a convenience to provide readily-accessible photographic documentation of installations. For instance, a data center technician might opt to upload a close-up photo of a device and its connections to clarify where each named interface resides on the box.
While NetBox might seem like an ideal place to store additional documents (PDFs, configurations, etc.), these are best maintained with the rest of your network's static documentation in a dedicated file store with appropriate access controls and revision history. Although other files cannot be uploaded to NetBox, you can link to them from NetBox in the comments section of an object, with custom links or within a custom URL field.
NetBox uses device types to define the physical characteristics of a device, including the components installed within it (console ports, interfaces, etc.). When a new device is created, any component templates defined on the device type are automatically populated on the new device, reducing the work needed to model new devices. However, this automation occurs only when a device is first created: Adding or removing components on a device type does not automatically remove or add them to device instances.
This is because automatically removing components requires NetBox to make very dangerous assumptions. For example, suppose you had a device type which included some interfaces on an optional module. After creating some devices, you decided these interfaces shouldn't be created automatically anymore, because new devices were no longer being deployed with that module installed. If NetBox were to automatically delete these interfaces from all devices of this type, it would result in many interfaces being deleted erroneously.
There's a similar issue when attempting to add components automatically. Say you had created a number of devices from an incomplete device type (perhaps they're missing a few interfaces), then you create the missing components on the device type. If NetBox were to populate these components automatically on the existing device instances, it would risk colliding with any components that had already been added to the devices. This would force us to either trigger an error, and prevent the new component templates from being added to the device type, or to ignore the collision, possibly resulting in an unexpected state (e.g. the device components may have been created with incorrect or missing data).
To avoid these problems, NetBox simply leaves it to the user to determine how best to rectify potential discrepancies. Once a device type has been updated, its device instances can easily have components added or removed in bulk. This approach ensures that all changes are driven by intent rather than by assumptions.
This question often stems from conflating physical and virtual circuits. A physical circuit is established between exactly two endpoints, whereas a virtual circuit can connect an arbitrary number of endpoints via one or more physical circuits. In a scenario where it seems that a circuit has more than two endpoints, there are actually multiple circuits, each with its own A and Z side terminations, abstracted in a way that they seem to function as a single circuit. A good rule to keep in mind is that circuits possess no forwarding logic: A packet entering one end will always egress the other.
To date, NetBox support only the modeling of physical circuits, however support for virtual circuit modeling is planned for a future release.
The bulk import and bulk export functions for objects in NetBox are two entirely different functions. When exporting a list of objects, NetBox will by default replicate the currently configured view, including only the columns configured for display in the user interface. NetBox also offers an "All Data" export option, which will include all available fields.
However, this data is formatted for intended consumption by a human, which is to say it's prioritized for readability: Column headers are capitalized, punctuation is included, etc. This format often differs significantly from the expected format for bulk import data. The bulk import function also often requires additional contextual data that is not present in any of the default export formats, for good reason.
For example, when exporting a list of devices, NetBox will include the assigned site and rack (if any), but not the rack's group. If there are multiple racks with the same name within the site, each within a different group, this data will not be sufficient to import devices: Additional information (i.e. the group assigned to each rack) is needed so that NetBox knows which rack to assign to each device. It would be extremely inefficient to include all such possible information in the default export format for all objects.
Additionally, redirecting data exported from NetBox back into NetBox is not a common use case. If you find yourself doing this, you may want to consider a more programmatic approach using the REST API or Python shell. However, if you decide this is the required course of action, you always have the option of creating a custom export template to arrange whatever data you need in whatever format you like. These can easily be used to export data in a format that is acceptable to NetBox's bulk import forms.
Some rack-mounted devices don't consume the entire horizontal rack unit, such as the Mellanox Spectrum SN2010. These devices do not mount within a rack directly: They require a separate mounting bracket to be affixed within a rack unit.
To model these devices in NetBox, first create a device type to represent the mounting bracket and assign it the appropriate number of device bays (however many child devices the bracket is capable of holding). Then, ensure that the device type which represents the child device has its subdevice role set to "child." Next, install the parent device (representing the bracket) in the rack, and the child devices within its device bays. This ensures that you have adequately represented the real-world installation of these devices.