Adding Models
1. Define the model class
Monitoring, backups, upgrades, and operational tasks
View all tags1. Define the model class
NetBox Enterprise is designed to harness the power of Kubernetes while minimizing the amount of work the average person needs to manage it.
NetBox includes a slew of features which enable integration with other tools and resources powering your network.
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.
NetBox plugins can defer certain operations by enqueuing background jobs, which are executed asynchronously by background workers. This is helpful for decoupling long-running processes from the user-facing request-response cycle.
Branch operations, such as syncing and merging, are tracked as events. This record of events serves as a history for each branch.
A branch represents a divergent state from the main database.
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.
Conditions are NetBox's mechanism for evaluating whether a set data meets a prescribed set of conditions. It allows the author to convey simple logic by declaring an arbitrary number of attribute-value-operation tuples nested within a hierarchy of logical AND and OR statements.
Administrative tasks for the NetBox Labs Console, including managing administrator accounts, permissions, and security settings.
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.
Creating Models
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.
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.
NetBox includes the ability to automatically perform certain functions in response to internal events. These include:
An event rule is a mechanism for automatically taking an action (such as running a script or sending a webhook) in response to an event in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating an event for device objects and designating a webhook to be transmitted. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
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.
Below is a list of tasks to consider when adding a new field to a core model.
Installation Issues
Overview of features and capabilities available in the NetBox Cloud Free Plan, including limitations and upgrade options.
Complete setup and configuration guide for NetBox Discovery across Cloud, Enterprise, and Community deployments with step-by-step instructions
Setting up a Development Environment
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.
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.
Overview of NetBox Cloud's standard Internet Delivery connectivity option with security features and multi-availability zone deployment.
Origin Story
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.
NetBox Upgrade Maintenance Windows
Configure automatic group synchronization and role mapping between Microsoft Entra ID and NetBox Cloud for streamlined user access management.
Complete guide to migrating your existing NetBox deployment to NetBox Cloud, including data migration and configuration transfer.
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.
ADMINS
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.
Comprehensive overview of the NetBox Cloud Administrative Console interface, features, and sections including deployment, database, and monitoring panels.
Configuration File
Advanced network discovery and observability solution for automated network documentation and drift detection across all NetBox deployments
1.10.1/1.10.2
Much like the NetBox software itself, NetBox Enterprise uses 2 main datastores: PostgreSQL, and Redis.
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
Tested Versions
This section of the documentation discusses installing and configuring the NetBox application itself.
NetBox Ansible Collection - Quick Start
v2.0.10 (2017-07-14)
v2.10.10 (2021-04-15)
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)
v2.8.9 (2020-08-04)
v2.9.11 (2020-12-11)
v3.0.12 (2021-12-06)
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.6.9 (2023-12-28)
v3.7.8 (2024-05-06)
v4.0.11 (2024-09-03)
v4.1.11 (2025-01-06)
v4.2.9 (2025-04-30)
v4.3.3 (2025-06-26)
Configure automatic group synchronization and role mapping between Okta and NetBox Cloud for streamlined user access management.
This section covers operational procedures for NetBox Enterprise.
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
NetBox supports optionally exposing native Prometheus metrics from the application. Prometheus is a popular time series metric platform used for monitoring.
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.
This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases:
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:
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
Plugins can declare custom endpoints on NetBox's REST API to retrieve or manipulate models or other data. These behave very similarly to views, except that instead of rendering arbitrary content using a template, data is returned in JSON format using a serializer.
What is a REST API?
NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command:
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 plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.
This page provides instructions for setting up the uWSGI WSGI server. If you plan to use gunicorn instead, go here.
Writing Basic Views
Code Structure
NetBox can be configured via Event Rules to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.
A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
Complete guide to creating, downloading, and restoring database backups in NetBox Cloud, including on-demand backups and restore procedures.