Skip to main content

129 docs tagged with "Configuration"

Configuration guides and setup instructions

View all tags

Add a New User to Free Plan

To invite a new user to a NetBox Cloud Free instance, the user will need to have a valid email address, and be added as an administrator in the NetBox Labs Console.

AWS Direct Connect (Single Region)

AWS Direct Connect is available via hosted connections from BT, Equinix Fabric, MegaPort, Optus, PCCW, Zayo etc. VLAN hand-off is with BGP and Single or Dual Direct Connect services are available. Customer IP space (/24 or /25) is assigned for the VPC, as this is required to host load balancers and proxies within the dedicated customer Account/VPC. Internally we will allocate a /27 per availability zone for each of the 3 availability zones.

Background Jobs

NetBox includes the ability to execute certain functions as background tasks. These include:

Background Jobs

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.

Circuit Group Assignments

Circuits can be assigned to circuit groups for correlation purposes. For instance, three circuits, each belonging to a different provider, may each be assigned to the same circuit group. Each assignment may optionally include a priority designation.

Circuits

A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity).

Clusters

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.

Configuration Contexts

Context data is made available to devices and/or virtual machines based on their relationships to other objects in NetBox. For example, context data can be associated only with devices assigned to a particular site, or only to virtual machines in a certain cluster.

Configuration Rendering

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

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.

Configuring SAML Group Mapping in NetBox Cloud

NetBox Cloud supports SAML-based authentication, including group mappings to enforce role-based access control. For group mapping, you will need to provide your Identity Provider (IdP) group names so we can associate them with the desired NetBox groups.

Console Administration

This guide covers administrative tasks for the NetBox Labs Console, including managing administrator accounts and console settings.

Context Data

Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API.

Custom Links

Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS).

Custom Sessions

Custom sessions can be used to modify the default HTTP behavior. Below are a few examples, most of them from here.

Custom Validation

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.

Dashboard Widgets

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.

Data Backends

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.

Data Files

A data file object is the representation in NetBox's database of some file belonging to a remote data source. Data files are synchronized automatically, and cannot be modified locally (although they can be deleted).

Device Roles

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.

Device Types

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

Devices

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.

Event Rules

NetBox includes the ability to automatically perform certain functions in response to internal events. These include:

Export Templates

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

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.

Getting Started

This guide will help you get started with development on pynetbox. It covers setting up your development environment and running tests.

git Cheat Sheet

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.

Google

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

GraphQL API Overview

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

Group Mapping For Okta Single Sign-On (SSO)

Upgrade your Single Sign-On experience with Group Mapping for Okta SSO – a smarter, more secure way to manage user access. The Group Mapping feature for Okta Single Sign-On, streamlines the synchronization of group memberships from Okta to groups in NetBox Cloud, allowing you to align your user access efficiently and accurately.

Gunicorn

This page provides instructions for setting up the gunicorn WSGI server. If you plan to use uWSGI instead, go here.

Housekeeping

NetBox includes a housekeeping management command that should be run nightly. This command handles:

HTTP Server Setup

This documentation provides example configurations for both nginx and Apache, though any HTTP server which supports WSGI should be compatible.

Installation

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!

Installing a Plugin

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.

Inventory Item Roles

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.

Inventory Item Templates

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.

Inventory Items

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

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.

IP Addresses

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

IP Ranges

This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the size property on an IPRange instance.) Like prefixes and IP addresses, each IP range may optionally be assigned to a VRF.

Journal Entries

Most objects in NetBox support journaling. This is the ability of users to record chronological notes indicating changes to or work performed on resources in NetBox. For example, a data center technician might add a journal entry for a device when swapping out a failed power supply.

Journaling

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.

L2VPN

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.

LDAP Configuration

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.

Locations

Racks and devices can be grouped by location within a site. A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor.

Microsoft Entra ID

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

Module Type Profiles

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.

Module Types

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.

Modules

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.

NetBox Cloud Free Plan Features

The NetBox Cloud Free Plan is perfect for small networks, lab environments, and targeted use cases. It includes up to 100 devices, 500 IP addresses, 10k API requests/month, and 2 operational branches.

NetBox Cloud Hostnames

1. From within the NetBox Labs Console click on Settings and then Hostnames Manager in the left-hand main menu to view the settings for your Organization:

NetBox Cloud Plugins

From within the NetBox Labs Console, you can easily view installed NetBox Cloud Plugins, along with their Scope and Version number. Simply follow these steps:

NetBox Installation

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

NetBox Labs Product and Feature Lifecycle

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:

Object-Based Permissions

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.

Okta

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

Okta SSO Setup

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

Platforms

A platform defines the type of software running on a device or virtual machine. This can be helpful to model when it is necessary to distinguish between different versions or feature sets. Note that two devices of the same type may be assigned different platforms: For example, one Juniper MX240 might run Junos 14 while another runs Junos 15.

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.

PostgreSQL Database Installation

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 Feed

A power feed represents the distribution of power from a power panel to a particular device, typically a power distribution unit (PDU). The power port (inlet) on a device can be connected via a cable to a power feed. A power feed may optionally be assigned to a rack to allow more easily tracking the distribution of power among racks.

Power Outlets

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.

Prefix Lists

You can secure access to your NetBox Cloud instance by adding IPv4 and IPv6 addresses and ranges to Prefix Lists, which can then be applied to NetBox instances to control which source IPs your instances will accept connections from.

Prefixes

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.

Prometheus Metrics

NetBox supports optionally exposing native Prometheus metrics from the application. Prometheus is a popular time series metric platform used for monitoring.

Pynetbox

Python API client library for NetBox.

Racks

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.

Remote Authentication Settings

The configuration parameters listed here control remote authentication for NetBox. Note that REMOTEAUTHENABLED must be True in order for these settings to take effect.

Removing a Plugin

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.

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

Sites

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.

Synchronized Data

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.

Synchronized Data

Some NetBox models support automatic synchronization of certain attributes from remote data sources, such as a git repository hosted on GitHub or GitLab. Data from the authoritative remote source is synchronized locally in NetBox as data files.

Table Configs

This object represents the saved configuration of an object table in NetBox. Table configs can be crafted, saved, and shared among users to apply specific views within object lists. Each table config can specify which table columns to display, the order in which to display them, and which columns are used for sorting.

Tables

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.

Translations

NetBox coordinates all translation work using the Transifex platform. Signing up for a Transifex account is free.

Tunnels

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 to a New NetBox Release

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.

User Preferences

The users.UserConfig model holds individual preferences for each user in the form of JSON data. This page serves as a manifest of all recognized user preferences in NetBox.

Using the REST API

This plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.

uWSGI

This page provides instructions for setting up the uWSGI WSGI server. If you plan to use gunicorn instead, go here.

Virtual Chassis

A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single managed device. Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement.

Virtual Circuits

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.

Virtual Device Context

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.

Virtual Machines

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.

Virtual Routing and Forwarding (VRF)

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.

VLAN Management

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.

VLANs

A Virtual LAN (VLAN) represents an isolated layer two domain, identified by a name and a numeric ID (1-4094) as defined in IEEE 802.1Q. VLANs are arranged into VLAN groups to define scope and to enforce uniqueness.

Which Cloud Connectivity Option is Right for Me?

In many cases where cloud connectivity options seem necessary, NetBox Cloud offers features that can address your needs without additional setup. In the majority of cases Internet Delivery (Single Region) is the most appropriate connectivity option, but there are some general recommendations depending on your use case:

Wireless

Just as NetBox provides robust modeling for physical cable plants, it also supports modeling wireless LANs and point-to-point links.

Wireless LANs

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.

Wireless Links

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.