146 docs tagged with "Authentication"

Step-by-step guide to inviting and adding new users to a NetBox Cloud Free Plan instance through the console administration interface.

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.

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.

Local Authentication

Object-Based Permissions

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.

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.

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 cluster is a logical grouping of physical resources within which virtual machines run. Physical devices may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside.

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.

A contact represents an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site.

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:

NetBox validates every object prior to it being written to the database to ensure data integrity. This validation includes things like checking for proper formatting and that references to related objects are valid. However, you may wish to supplement this validation with some rules of your own. For example, perhaps you require that every site's name conforms to a specific pattern. This can be done using custom validation rules.

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.

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.

Requirements

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.

SENTRY_DSN

NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.

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

A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual IP address (VIP) in a redundant manner. Examples of such protocols include:

Form Classes

Overview of features and capabilities available in the NetBox Cloud Free Plan, including limitations and upgrade options.

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

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 guide explains how to configure single sign-on (SSO) support for NetBox using Google OAuth2 as an authentication backend.

NetBox provides a read-only GraphQL API to complement its REST API. This API is powered by Strawberry Django.

An Internet Key Exchange (IKE) policy defines an IKE version, mode, and set of proposals to be used in IKE negotiation. These policies are referenced by IPSec profiles.

An Internet Key Exhcnage (IKE) proposal defines a set of parameters used to establish a secure bidirectional connection across an untrusted medium, such as the Internet. IKE proposals defined in NetBox can be referenced by IKE policies, which are in turn employed by IPSec profiles.

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

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.

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.

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).

An IPSec profile defines an IKE policy, IPSec policy, and IPSec mode used for establishing an IPSec tunnel.

The Job model is used to schedule and record the execution of background tasks.

All primary and organizational models in NetBox support journaling. A journal is a collection of human-generated notes and comments about an object maintained for historical context. It supplements NetBox's change log to provide additional information about why changes have been made or to convey events which occur outside NetBox. Unlike the change log, in which records typically expire after a configurable period of time, journal entries persist for the life of their associated object.

A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS, or EPL. Each L2VPN can be identified by name as well as by an optional unique identifier (VNI would be an example). Once created, L2VPNs can be terminated to interfaces and VLANs.

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.

Configure and manage custom hostnames and DNS settings for your NetBox Cloud instance.

This guide explains how to configure single sign-on (SSO) support for NetBox using Microsoft Entra ID as an authentication backend.

Configure automatic group synchronization and role mapping between Microsoft Entra ID and NetBox Cloud for streamlined user access management.

Complete guide to configuring single sign-on (SSO) for NetBox Cloud using Microsoft Entra ID (formerly Azure Active Directory) as an authentication backend.

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

Each module type may optionally be assigned a profile according to its classification. A profile can extend module types with user-configured attributes. For example, you might want to specify the input current and voltage of a power supply, or the clock speed and number of cores for a processor.

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.

Menus

How to access the NetBox Labs Console through direct URL or from within NetBox Cloud UI, including login options and account setup.

Configuration File

Thanks for your interest in contributing to NetBox! This introduction covers a few important things to know before you get started.

1.10.1/1.10.2

Much like the NetBox software itself, NetBox Enterprise uses 2 main datastores: PostgreSQL, and Redis.

Place the following in configuration overrides python section

Advanced installation options for NetBox Enterprise Helm deployment

Basic installation guide using NetBox Labs Enterprise Portal

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

You should be able to follow these instructions for installing NetBox Enterprise in most environments.

Kubernetes dependencies

System requirements

This section of the documentation discusses installing and configuring the NetBox application itself.

NetBox Ansible Collection - Quick Start

NetBox Labs products and features can go through multiple release stages before becoming generally available. These stages in the release life cycle can present varying degrees of stability and support. The following are the NetBox Labs release stages:

v2.1.6 (2017-10-11)

v2.11.12 (2021-08-23)

v2.2.10 (2018-02-21)

v2.3.7 (2018-07-26)

v2.5.13 (2019-05-31)

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.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.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)

The network discovery backend leverages NMAP to scan networks and discover IP information.

This guide explains how to configure single sign-on (SSO) support for NetBox using Okta as an authentication backend.

Configure automatic group synchronization and role mapping between Okta and NetBox Cloud for streamlined user access management.

Step-by-step guide to configuring single sign-on (SSO) for NetBox Cloud using Okta as an authentication backend with OpenID Connect.

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.

As part of its DCIM feature set, NetBox supports modeling facility power as discrete power panels and feeds. These are most commonly used to document power distribution within a data center, but can serve more traditional environments as well.

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 individual accounts associated with a provider.

Users can reserve specific units within a rack for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant.

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.

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 configuration parameters listed here control remote authentication for NetBox. Note that REMOTEAUTHENABLED must be True in order for these settings to take effect.

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?

Configure automatic group synchronization and role mapping between SAML identity providers and NetBox Cloud.

Configure SAML-based single sign-on (SSO) for NetBox Cloud with your organization's identity provider.

NetBox v3.4 introduced a new global search mechanism, which employs the extras.CachedValue model to store discrete field values from many models in a single table.

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).

ALLOWTOKENRETRIEVAL

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.

Syncing a Branch

BASE_PATH

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.

New Tables in ServiceNow

Most core objects within NetBox's data model support tenancy. This is the association of an object with a particular tenant to convey ownership or dependency. For example, an enterprise might represent its internal business units as tenants, whereas a managed services provider might create a tenant in NetBox to represent each of its customers.

A tunnel termination connects a device or virtual machine interface to a tunnel. The tunnel must be created before any terminations may be added.

NetBox can model private tunnels formed among virtual termination points across your network. Typical tunnel implementations include GRE, IP-in-IP, and IPSec. A tunnel may be terminated to two or more device or virtual machine interfaces. For convenient organization, tunnels may be assigned to user-defined groups.

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.

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.

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

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 machine (VM) represents a virtual compute instance hosted within a cluster. Each VM must be assigned to a site and/or cluster, and may optionally be assigned to a particular host device within a cluster.

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.

VLAN translation is a feature that consists of VLAN translation policies and VLAN translation rules. Many rules can belong to a policy, and each rule defines a mapping of a local to remote VLAN ID (VID). A policy can then be assigned to an Interface or VMInterface, and all VLAN translation rules associated with that policy will be visible in the interface details.

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.

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.

A wireless link represents a connection between exactly two wireless interfaces. Unlike a wireless LAN, which permit an arbitrary number of client associations, wireless links are used to model point-to-point wireless connections.

Complete guide to creating, downloading, and restoring database backups in NetBox Cloud, including on-demand backups and restore procedures.