Aggregates
IP addressing is by nature hierarchical. The first few levels of the IPv4 hierarchy, for example, look like this:
Network connectivity, cloud connectivity, and infrastructure
View all tagsIP addressing is by nature hierarchical. The first few levels of the IPv4 hierarchy, for example, look like this:
Unlike the web UI, where a user's selected branch remains active until it is changed, the desired branch must be specified with each REST API request. This is accomplished by including the X-NetBox-Branch HTTP header specifying the branch's schema ID.
The following instructions assume you have installed NetBox in the /opt/netbox directory. Adjust instructions as necessary if you've installed NetBox in a different directory.
High-performance, multi-region NetBox Cloud connectivity with AWS Direct Connect for maximum redundancy and scalability.
High-performance dedicated network connectivity to NetBox Cloud via AWS Direct Connect with BGP routing and VLAN hand-off.
Coming Soon
NetBox Cloud connectivity via AWS Private Link with VPC endpoints using private IPs for enhanced security and performance.
All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two sets of endpoints (A and B), such as a console port and a patch panel port, or between two network interfaces. Cables may be connected to the following objects:
Each circuit may have up to two terminations, designated A and Z. At either termination, a circuit may connect to a site, device interface (via a cable), or to a provider network.
Circuits are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for:
NetBox is ideal for managing your network's transit and peering providers and circuits. It provides all the flexibility needed to model physical circuits in both data center and enterprise environments, and allows for "connecting" circuits directly to device interfaces via cables.
A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity).
Common questions and answers about NetBox Cloud connectivity options, setup, and troubleshooting.
Agent configuration file
One of the critical aspects of operating a network is ensuring that every network node is configured correctly. By leveraging configuration templates and context data, NetBox can render complete configuration files for each device on your network.
Here is a collection of configuration samples supported by orb agent
A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server.
A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices, and generally connect to console ports.
Custom scripting was introduced to provide a way for users to execute custom logic from within the NetBox UI. Custom scripts enable the user to directly and conveniently manipulate NetBox data in a prescribed fashion. They can be used to accomplish myriad tasks, such as:
While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs.
The device discovery backend leverages NAPALM to connect to network devices and collect network information.
Devices can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for core switches, distribution switches, and access switches within your network.
A device type represents a particular make and model of hardware that exists in the real world. Device types define the physical attributes of a device (rack height and depth) and its individual components (console, power, network interfaces, and so on).
Every piece of hardware which is installed within a site or rack exists in NetBox as a device. Devices are measured in rack units (U) and can be half depth or full depth. A device may have a height of 0U: These devices do not consume vertical rack space and cannot be assigned to a particular rack unit. A common example of a 0U device is a vertically-mounted PDU.
At its heart, NetBox is a tool for modeling your network infrastructure, and the device object is pivotal to that function. A device can be any piece of physical hardware installed within your network, such as server, router, or switch, and may optionally be mounted within a rack. Within each device, resources such as network interfaces and console ports are modeled as discrete components, which may optionally be grouped into modules.
The Diode project is currently in Public Preview. Please see NetBox Labs Product and Feature Lifecycle for more details.
The Diode Agent is a lightweight network device discovery tool that uses NAPALM to streamline data entry into NetBox through the Diode ingestion service. The following is a basic set of instructions to get started using Diode Agent on a local machine.
reference architecture
Comprehensive guide to help determine if you need specialized cloud connectivity options for NetBox Cloud or if standard internet delivery meets your requirements.
Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the export templates documentation for more information.
From global regions down to individual equipment racks, NetBox allows you to model your network's entire presence. This is accomplished through the use of several purpose-built models. The graph below illustrates these models and their relationships.
Installation Issues
Overview of features and capabilities available in the NetBox Cloud Free Plan, including limitations and upgrade options.
Before getting started
This guide will help you set up and start using Diode to ingest data into NetBox.
Complete setup and configuration guide for NetBox Discovery across Cloud, Enterprise, and Community deployments with step-by-step instructions
Complete setup and configuration guide for NetBox Assurance - from installation to your first operational workflow with step-by-step instructions
You can view an on-demand Webinar Getting Started with Network Test Automation: NetBox + pyATS hosted by NetBox Labs.
This documentation provides example configurations for both nginx and Apache, though any HTTP server which supports WSGI should be compatible.
NetBox
Before Starting
Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces.
Overview of NetBox Cloud's standard Internet Delivery connectivity option with security features and multi-availability zone deployment.
Origin Story
IP address management (IPAM) is one of NetBox's core features. It supports full parity for IP4 and IPv6, advanced VRF assignment, automatic hierarchy formation, and much more.
An IP address object in NetBox comprises a single host address (either IPv4 or IPv6) and its subnet mask, and represents an IP address as configured on a network interface. IP addresses can be assigned to device and virtual machine interfaces, as well as to FHRP groups. Further, each device and virtual machine may have one of its interface IPs designated as its primary IP per address family (one for IPv4 and one for IPv6).
Secure site-to-site connectivity to NetBox Cloud using IPSEC VPN tunnels with flexible routing options and high security.
L2VPN and overlay networks, such as VXLAN and EVPN, can be defined in NetBox and tied to interfaces and VLANs. This allows for easy tracking of overlay assets and their relationships with underlay resources.
This document summarizes the system-level changes made to a Linux host when installing a NetBox Enterprise Embedded Cluster, particularly in relation to directories, files, and runtime configurations affected under /.
A MAC address object in NetBox comprises a single Ethernet link layer address, and represents a MAC address as reported by or assigned to a network interface. MAC addresses can be assigned to device and virtual machine interfaces. A MAC address can be specified as the primary MAC address for a given device or VM interface.
Configure and manage custom hostnames and DNS settings for your NetBox Cloud instance.
NetBox supports Markdown rendering for certain text fields. Some common examples are provided below. For a complete Markdown reference, please see Markdownguide.org.
Automated operational drift detection for NetBox - continuously monitor network infrastructure and maintain accurate documentation with proactive remediation capabilities
Advanced network discovery and observability solution for automated network documentation and drift detection across all NetBox deployments
If you are not automatically redirected, click here to go to the NetBox Documentation.
Advanced installation options for NetBox Enterprise Helm deployment
Basic installation guide using NetBox Labs Enterprise Portal
Overview of NetBox Enterprise Helm installation methods and architecture
System requirements and prerequisites for NetBox Enterprise Helm installation
Troubleshooting guide for NetBox Enterprise Helm installation issues
Configuration guide for customizing NetBox Enterprise Helm deployment using values-extra.yaml
Kubernetes dependencies
System requirements
Host system requirements
NetBox Ansible Collection - Quick Start
Model Types
v2.11.12 (2021-08-23)
v2.2.10 (2018-02-21)
v2.5.13 (2019-05-31)
v2.6.12 (2020-01-13)
v2.7.12 (2020-04-08)
v3.0.12 (2021-12-06)
v3.1.11 (2022-04-05)
v3.2.9 (2022-08-16)
v3.3.10 (2022-12-13)
v3.4.10 (2023-04-27)
v3.5.9 (2023-08-28)
v3.7.8 (2024-05-06)
v4.2.9 (2025-04-30)
v4.3.3 (2025-06-26)
The network discovery backend leverages NMAP to scan networks and discover IP information.
This guide outlines the steps necessary for planning a successful migration to NetBox. Although it is written under the context of a completely new installation, the general approach outlined here works just as well for adding new data to existing NetBox deployments.
Configure and manage IP prefix lists for NetBox Cloud security, including both synchronized and non-synchronized prefix list creation and management.
A prefix is an IPv4 or IPv6 network and mask expressed in CIDR notation (e.g. 192.0.2.0/24). A prefix entails only the "network portion" of an IP address: All bits in the address not covered by the mask must be zero. (In other words, a prefix cannot be a specific IP address.) Prefixes are automatically organized by their parent aggregate and assigned VRF.
This model can be used to represent the boundary of a provider network, the details of which are unknown or unimportant to the NetBox user. For example, it might represent a provider's regional MPLS network to which multiple circuits provide connectivity.
A provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each circuit within NetBox must be assigned a provider and a circuit ID which is unique to that provider.
Configure and manage public IP addressing settings for NetBox Cloud instances.
Looking to try NetBox Discovery as quickly and easily as possible? The Quickstart Guide on the NetBox Labs blog has you covered! In a few commands you will install and pre-configure everything you need to start experimenting:
NetBox releases are numbered as major, minor, and patch releases. For example, version 3.1.0 is a minor release, and v3.1.5 is a patch release. Briefly, these can be described as follows:
How you choose to employ sites when modeling your network may vary depending on the nature of your organization, but generally a site will equate to a building or campus. For example, a chain of banks might create a site to represent each of its branches, a site for its corporate headquarters, and two additional sites for its presence in two colocation facilities.
Tunnels can be arranged into administrative groups for organization. For example, you might crete a group to manage all peer-to-peer tunnels inside a mesh network. The assignment of a tunnel to a group is optional.
A tunnel represents a private virtual connection established among two or more endpoints across a shared infrastructure by employing protocol encapsulation. Common encapsulation techniques include Generic Routing Encapsulation (GRE), IP-in-IP, and IPSec. NetBox supports modeling both peer-to-peer and hub-and-spoke tunnel topologies.
Distribution and Installation
Comprehensive guide to the NetBox Assurance web interface - navigation, deviation management, workflows, and daily operations for network drift detection
A virtual circuit can connect two or more interfaces atop a set of decoupled physical connections. For example, it's very common to form a virtual connection between two virtual interfaces, each of which is bound to a physical interface on its respective device and physically connected to a provider network via an independent physical circuit.
A virtual device context (VDC) represents a logical partition within a physical device, to which interfaces from the parent device can be allocated. Each VDC effectively provides an isolated control plane, but relies on shared resources of the parent device. A VDC is somewhat similar to a virtual machine in that it effects isolation between various components, but stops short of delivering a fully virtualized environment.
A VRF object in NetBox represents a Virtual Routing and Forwarding (VRF) domain. Each VRF is essentially an independent routing table. VRFs are commonly used to isolate customers or organizations from one another within a network, or to route overlapping address space (e.g. multiple instances of the 10.0.0.0/8 space). Each VRF may be assigned to a specific tenant to aid in organizing the available IP space by customer or internal user.
Virtual machines and clusters can be modeled in NetBox alongside physical infrastructure. IP addresses and other resources are assigned to these objects just like physical objects, providing a seamless integration between physical and virtual networks.
Complementing its IPAM capabilities, NetBox also tracks VLAN information to assist with layer two network configurations. VLANs are defined per IEEE 802.1Q and related standards, and can be assigned to groups and functional roles.
A VLAN translation rule represents a one-to-one mapping of a local VLAN ID (VID) to a remote VID. Many rules can belong to a single policy.
The home of documentation for NetBox Cloud, Enterprise, Integrations, SDKs and Extensions.
Comprehensive comparison matrix of NetBox Cloud connectivity options including Internet Delivery, AWS Private Link, IPSEC VPN, and AWS Direct Connect.
Just as NetBox provides robust modeling for physical cable plants, it also supports modeling wireless LANs and point-to-point links.
A wireless LAN is a set of interfaces connected via a common wireless channel, identified by its SSID and authentication parameters. Wireless interfaces can be associated with wireless LANs to model multi-acess wireless segments.