Add a New User to Free Plan
Step-by-step guide to inviting and adding new users to a NetBox Cloud Free Plan instance through the console administration interface.
Installation guides and setup procedures
View all tagsStep-by-step guide to inviting and adding new users to a NetBox Cloud Free Plan instance through the console administration interface.
NetBox Enterprise is designed to harness the power of Kubernetes while minimizing the amount of work the average person needs to manage it.
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.
Local Authentication
Object-Based Permissions
Coming Soon
Coming Soon
Coming Soon
The NetBox branching plugin allows you to create and work with branches in NetBox, similar to version control systems. This enables you to make changes in isolation and merge them back to the main branch when ready.
v0.6.0
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).
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.
Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the dcimsite table, which has columns named name, facility, physicaladdress, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
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.
Data sources can be defined to reference data which exists on systems of record outside NetBox, such as a git repository or Amazon S3 bucket. Plugins can register their own backend classes to introduce support for additional resource types. This is done by subclassing NetBox's DataBackend class.
Creating Models
Device bays represent a space or slot within a parent device in which a child device may be installed. For example, a 2U parent chassis might house four individual blade servers. The chassis would appear in the rack elevation as a 2U device with four device bays, and each server within it would be defined as a 0U device installed in one of the device bays. Child devices do not appear within rack elevations or count as consuming rack units.
The device discovery backend leverages NAPALM to connect to network devices and collect network information.
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 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.
The Diode SDK is a Python library for sending data to the Diode server over gRPC/protbuf for ingestion in to NetBox.
Requirements
Comprehensive guide to help determine if you need specialized cloud connectivity options for NetBox Cloud or if standard internet delivery meets your requirements.
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
Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific rear port on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each.
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
This guide will help you get started with development on pynetbox. It covers setting up your development environment and running tests.
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 cheat sheet serves as a convenient reference for NetBox contributors who already somewhat familiar with using git. For a general introduction to the tooling and workflows involved, please see GitHub's guide Getting started with git.
This page provides instructions for setting up the gunicorn WSGI server. If you plan to use uWSGI instead, go here.
This documentation provides example configurations for both nginx and Apache, though any HTTP server which supports WSGI should be compatible.
ServiceNow Integration Overview
NetBox
Check out the NetBox Cloud Free Plan! Skip the installation process and grab your own NetBox Cloud instance, preconfigured and ready to go in minutes. Completely free!
Before Starting
The instructions below detail the general process for installing and configuring a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin before attempting to install it.
While NetBox Enterprise comes with a variety of certified and other community plugins built-in, there are cases where you will want to include additional plugins in your NetBox runtime.
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.
Beginning in NetBox v4.3, the use of inventory items has been deprecated. They are planned for removal in a future NetBox release. Users are strongly encouraged to begin using modules and module types in place of inventory items. Modules provide enhanced functionality and can be configured with user-defined attributes.
Coming Soon
This guide explains how to implement LDAP authentication using an external server. User authentication will fall back to built-in Django users in the event of a failure.
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 /.
This guide explains how to configure single sign-on (SSO) support for NetBox using Microsoft Entra ID as an authentication backend.
This guide explains how to configure single sign-on (SSO) support for NetBox Enterprise using Microsoft Entra ID (formerly Azure Active Directory) as an authentication backend.
Complete guide to configuring single sign-on (SSO) for NetBox Cloud using Microsoft Entra ID (formerly Azure Active Directory) as an authentication backend.
Migrating from NetBox open source to NetBox Labs Enterprise is a simple and efficient process. Because NetBox Enterprise is built on the same open source platform, database imports can be completed quickly, enabling a smooth transition.
This document serves as a handbook for maintainers of plugins that were written prior to the release of NetBox v4.0. It serves to capture all the changes recommended to ensure a plugin is compatible with NetBox v4.0 and later releases.
ADMINS
Module bays represent a space or slot within a device in which a field-replaceable module may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device.
A module type represents a specific make and model of hardware component which is installable within a device's module bay and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it.
A module is a field-replaceable hardware component installed within a device which houses its own child components. The most common example is a chassis-based router or switch.
Automated operational drift detection for NetBox - continuously monitor network infrastructure and maintain accurate documentation with proactive remediation capabilities
NetBox is the world's leading source of truth for network infrastructure, featuring an extensive and complex data model. But sometimes it can be challenging to orchestrate changes, especially when working within a large team. This plugin introduces a new paradigm for NetBox to help overcome these challenges: branching.
How to access the NetBox Labs Console through direct URL or from within NetBox Cloud UI, including login options and account setup.
View and manage installed plugins in your NetBox Cloud instance through the administrative console.
Comprehensive overview of the NetBox Cloud Administrative Console interface, features, and sections including deployment, database, and monitoring panels.
Advanced network discovery and observability solution for automated network documentation and drift detection across all NetBox deployments
The NetBox Discovery agent is based on the Orb open source project. Orb agent is one component of the NetBox Discovery solution and provides network discovery and observability capabilities.
Overview
1.10.1/1.10.2
Much like the NetBox software itself, NetBox Enterprise uses 2 main datastores: PostgreSQL, and Redis.
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
Comprehensive Helm installation guides for NetBox Enterprise
Configuration guide for customizing NetBox Enterprise Helm deployment using values-extra.yaml
You should be able to follow these instructions for installing NetBox Enterprise in most environments.
Direct access guides for NetBox Enterprise installation
Kubernetes dependencies
System requirements
Host system requirements
Tested Versions
Required Information
This section of the documentation discusses installing and configuring the NetBox application itself.
NetBox Ansible Collection - Quick Start
v2.1.6 (2017-10-11)
v2.2.10 (2018-02-21)
v2.6.12 (2020-01-13)
v2.7.12 (2020-04-08)
v2.8.9 (2020-08-04)
v3.0.12 (2021-12-06)
v3.2.9 (2022-08-16)
v3.4.10 (2023-04-27)
v3.6.9 (2023-12-28)
v4.0.11 (2024-09-03)
v4.1.11 (2025-01-06)
v4.2.9 (2025-04-30)
v4.3.3 (2025-06-26)
Step-by-step guide to configuring single sign-on (SSO) for NetBox Cloud using Okta as an authentication backend with OpenID Connect.
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.
PLUGINS
Plugins are packaged Django apps that can be installed alongside NetBox to provide custom functionality not present in the core application. Plugins can introduce their own models and views, but cannot interfere with existing components. A NetBox user may opt to install plugins provided by the community or build his or her own.
Just getting started with plugins? Check out our NetBox Plugin Tutorial on GitHub! This in-depth guide will walk you through the process of creating an entire plugin from scratch. It even includes a companion demo plugin repo to ensure you can jump in at any step along the way. This will get you up and running with plugins in no time!
This section entails the installation and configuration of a local PostgreSQL database. If you already have a PostgreSQL database service in place, skip to the next section.
Power outlets represent the outlets on a power distribution unit (PDU) or other device that supplies power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device.
A power panel represents the origin point in NetBox for electrical power being disseminated by one or more power feeds. In a data center environment, one power panel often serves a group of racks, with an individual power feed extending to each rack, though this is not always the case. It is common to have two sets of panels and feeds arranged in parallel to provide redundant power to each rack.
A power port is a device component which draws power from some external source (e.g. an upstream power outlet), and generally represents a power supply internal to a device.
Python API client library for NetBox.
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:
A rack type defines the physical characteristics of a particular model of rack.
The rack model represents a physical two- or four-post equipment rack in which devices can be installed. Each rack must be assigned to a site, and may optionally be assigned to a location within that site. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique.
Like front ports, rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable).
Install Redis
This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases:
The instructions below detail the general process for removing a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin before attempting to remove it.
Replicating the Database
ALLOWED_HOSTS
What is a REST API?
NetBox generally follows the Django style guide, which is itself based on PEP 8. ruff is used for linting (with certain exceptions).
Several models in NetBox support the automatic synchronization of local data from a designated remote source. For example, configuration templates defined in NetBox can source their content from text files stored in a remote git repository. This is accomplished using the core data source and data file models.
BASE_PATH
NetBox Enterprise Installs
NetBox coordinates all translation work using the Transifex platform. Signing up for a Transifex account is free.
Distribution and Installation
Step-by-step guide to upgrading your NetBox Cloud instance to newer versions through the administrative console.
Upgrading NetBox to a new version is pretty simple, however users are cautioned to always review the release notes and save a backup of their current deployment prior to beginning an upgrade.
Comprehensive guide to the NetBox Assurance web interface - navigation, deviation management, workflows, and daily operations for network drift detection
This page provides instructions for setting up the uWSGI WSGI server. If you plan to use gunicorn instead, go here.
Code Structure