API key for the Diode service to interact with NetBox
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.
Plugin system, extensions, and third-party integrations
View all tagsThe 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.
The registry is an in-memory data structure which houses various application-wide parameters, such as the list of enabled plugins. It is not exposed to the user and is not intended to be modified by any code outside of NetBox core.
NetBox includes the ability to execute certain functions as background tasks. These include:
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.
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
exempt_models
The following plugin configuration parameters are available.
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.
Configuration templates can be used to render device configurations from context data. Templates are written in the Jinja2 language and can be associated with devices roles, platforms, and/or individual devices.
Setting up Group Mapping for SAML requires the base SAML SSO Setup to be configured and working first.
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:
Each NetBox user can customize his or her personal dashboard by adding and removing widgets and by manipulating the size and position of each. Plugins can register their own dashboard widgets to complement those already available natively.
CUSTOM_VALIDATORS
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.
A data source represents some external repository of data which NetBox can consume, such as a git repository. Files within the data source are synchronized to NetBox by saving them in the database as data file objects.
Creating Models
The Diode project is currently in Public Preview. Please see NetBox Labs Product and Feature Lifecycle for more details.
Plugins can register their own custom event types for use with NetBox event rules. This is accomplished by calling the register() method on an instance of the EventType class. This can be done anywhere within the plugin. An example is provided below.
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.
The exception classes listed here may be raised by a plugin to alter NetBox's default behavior in various scenarios.
NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.
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.
Installation Issues
Filter sets define the mechanisms available for filtering or searching through a set of objects in NetBox. For instance, sites can be filtered by their parent region or group, status, facility ID, and so on. The same filter set is used consistently for a model whether the request is made via the UI or REST API. (Note that the GraphQL API uses a separate filter class.) NetBox employs the django-filters2 library to define filter sets.
Form Classes
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
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
Defining the Schema Class
NetBox includes a housekeeping management command that should be run nightly. This command handles:
NetBox
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.
Origin Story
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 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.
Menus
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.
This plugin adds change management support to NetBox. Leveraging the netbox-branching plugin, it implements policy and workflow controls to ensure proposed changes undergo formal review prior to being merged. It also retains a written record of all approved changes.
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.
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.
1.10.1/1.10.2
Place the following in configuration overrides python section
Advanced installation options for NetBox Enterprise Helm deployment
System requirements and prerequisites for NetBox Enterprise Helm installation
Troubleshooting guide for NetBox Enterprise Helm installation issues
You should be able to follow these instructions for installing NetBox Enterprise in most environments.
Kubernetes dependencies
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.8.9 (2020-08-04)
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.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)
NetBox includes a system for generating user notifications, which can be marked as read or deleted by individual users. There are two built-in mechanisms for generating a notification:
NetBox employs a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
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!
Python API client library for NetBox.
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.
ALLOWED_HOSTS
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?
Global Search
Plugins can define and register their own models to extend NetBox's core search functionality. Typically, a plugin will include a file named search.py, which holds all search indexes for its models (see the example below).
NetBox employs the django-tables2 library for rendering dynamic object tables. These tables display lists of objects, and can be sorted and filtered by various parameters.
Templates are used to render HTML content generated from a set of context data. NetBox provides a set of built-in templates suitable for use in plugin views. Plugin authors can extend these templates to minimize the work needed to create custom templates while ensuring that the content they produce matches NetBox's layout and style. These templates are all written in the Django Template Language (DTL).
Step-by-step guide to upgrading your NetBox Cloud instance to newer versions through the administrative console.
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.
Writing Basic Views
Code Structure
The home of documentation for NetBox Cloud, Enterprise, Integrations, SDKs and Extensions.