NetBox

https://netboxlabs.com/docs/netbox/
Admin
NetBox is an open-source web application designed to manage and document computer networks,...
Tokens:136,448
Snippets:2,182
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Serve Documentation Locally

Source: https://netboxlabs.com/docs/netbox/development/release-checklist

Start the documentation server using MkDocs to review changes. Navigate to the installation documentation to perform manual checks.

```bash
mkdocs serve
```

--------------------------------

### Enable and Start NetBox Services

Source: https://netboxlabs.com/docs/netbox/installation/4b-uwsgi

Enable the NetBox and NetBox-RQ services to start at boot time and start them immediately.

```bash
sudo systemctl enable --now netbox netbox-rq  

```

--------------------------------

### Running RQ Worker with Custom Queues

Source: https://netboxlabs.com/docs/netbox/plugins/development/background-jobs

Advise users to reconfigure the default RQ worker or run a dedicated worker to service custom queues. This command example shows how to start a worker for specific custom queues.

```bash
python manage.py rqworker my_plugin.foo my_plugin.bar
```

--------------------------------

### Install Git

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Installs the git package if it is not already present on the system.

```bash
sudo apt install -y git  
```

--------------------------------

### Install Apache

Source: https://netboxlabs.com/docs/netbox/installation/http-server

Install the Apache web server on Ubuntu 24.04. This is the first step in setting up Apache as the HTTP server for NetBox.

```bash
sudo apt install -y apache2
```

--------------------------------

### Viewset Example

Source: https://netboxlabs.com/docs/netbox/plugins/development/rest-api

Example of creating a viewset for a plugin model by subclassing NetBoxModelViewSet.

```APIDOC
## Viewset Example

To create a viewset for a plugin model, subclass `NetBoxModelViewSet` in `api/views.py`, and define the `queryset` and `serializer_class` attributes.

```python
# api/views.py
from netbox.api.viewsets import NetBoxModelViewSet
from my_plugin.models import MyModel
from .serializers import MyModelSerializer

class MyModelViewSet(NetBoxModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
```
```

--------------------------------

### Install Python Package Manually

Source: https://netboxlabs.com/docs/netbox/plugins/installation

Alternatively, install a plugin manually using `python setup.py install`. For development purposes, use `python setup.py develop` to install the plugin in editable mode.

```bash
python setup.py install
```

```bash
python setup.py develop
```

--------------------------------

### Install pyuwsgi Package

Source: https://netboxlabs.com/docs/netbox/installation/4b-uwsgi

Activate the Python virtual environment and install the pyuwsgi package using pip.

```bash
source /opt/netbox/venv/bin/activate 
pip3 install pyuwsgi  

```

--------------------------------

### Install nginx

Source: https://netboxlabs.com/docs/netbox/installation/http-server

Install the nginx web server on Ubuntu 24.04. This is the first step in setting up nginx as the HTTP server for NetBox.

```bash
sudo apt install -y nginx
```

--------------------------------

### Enable and Start NetBox Services

Source: https://netboxlabs.com/docs/netbox/installation/4a-gunicorn

Enable and start the NetBox WSGI and background worker services to initiate at boot time.

```bash
sudo systemctl enable --now netbox netbox-rq
```

--------------------------------

### NetBox Development Server Output

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Example output indicating the NetBox development server has started successfully. This output confirms the application is running and accessible on the specified port.

```text
Performing system checks...  
  
System check identified no issues (0 silenced).  
January 26, 2026 - 17:00:00  
Django version 5.2.10, using settings 'netbox.settings'  
Starting development server at http://0.0.0.0:8000/  
Quit the server with CONTROL-C.  

```

--------------------------------

### URL Query String Example

Source: https://netboxlabs.com/docs/netbox/models/extras/savedfilter

This example shows how a URL query string can be structured to apply multiple filters.

```text
?status=active&region_id=51&tag=alpha&tag=bravo
```

--------------------------------

### Install Redis Server

Source: https://netboxlabs.com/docs/netbox/installation/redis

Installs the Redis server package on Debian-based systems. This is the primary step for setting up a local Redis instance.

```bash
sudo apt install -y redis-server  

```

--------------------------------

### Basic Circuit Query Example

Source: https://netboxlabs.com/docs/netbox/integrations/graphql-api

This example demonstrates how to query for circuit IDs and provider names of circuits with an active status.

```APIDOC
## Query Circuit List with Status

### Description
Retrieves a list of circuits, filtered by their status, and returns their unique ID and the name of their associated provider.

### Method
POST

### Endpoint
/graphql/

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example
```json
{
  "query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the query results.
  - **circuits** (array) - A list of circuit objects.
    - **cid** (string) - The circuit ID.
    - **provider** (object) - Information about the circuit provider.
      - **name** (string) - The name of the provider.

#### Response Example
```json
{
  "data": {
    "circuits": [
      {
        "cid": "1002840283",
        "provider": {
          "name": "CenturyLink"
        }
      },
      {
        "cid": "1002840457",
        "provider": {
          "name": "CenturyLink"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Full LDAP/Active Directory Configuration Example

Source: https://netboxlabs.com/docs/netbox/installation/ldap

A comprehensive example configuration for connecting to Active Directory, including server URI, bind credentials, certificate handling, user/group search, and attribute mapping.

```python
import ldap
from django_auth_ldap.config import LDAPSearch, NestedGroupOfNamesType

# Server URI
AUTH_LDAP_SERVER_URI = "ldaps://ad.example.com:3269"

# The following may be needed if you are binding to Active Directory.
AUTH_LDAP_CONNECTION_OPTIONS = {
    ldap.OPT_REFERRALS: 0
}

# Set the DN and password for the NetBox service account.
AUTH_LDAP_BIND_DN = "CN=NETBOXSA,OU=Service Accounts,DC=example,DC=com"
AUTH_LDAP_BIND_PASSWORD = "demo"

# Include this setting if you want to ignore certificate errors. This might be needed to accept a self-signed cert.
# Note that this is a NetBox-specific setting which sets:
#     ldap.set_option(ldap.OPT_X_TLS_REQUIRE_CERT, ldap.OPT_X_TLS_NEVER)
LDAP_IGNORE_CERT_ERRORS = False

# Include this setting if you want to validate the LDAP server certificates against a CA certificate directory on your server
# Note that this is a NetBox-specific setting which sets:
#     ldap.set_option(ldap.OPT_X_TLS_CACERTDIR, LDAP_CA_CERT_DIR)
LDAP_CA_CERT_DIR = '/etc/ssl/certs'

# Include this setting if you want to validate the LDAP server certificates against your own CA.
# Note that this is a NetBox-specific setting which sets:
#     ldap.set_option(ldap.OPT_X_TLS_CACERTFILE, LDAP_CA_CERT_FILE)
LDAP_CA_CERT_FILE = '/path/to/example-CA.crt'

# This search matches users with the sAMAccountName equal to the provided username. This is required if the user's
# username is not in their DN (Active Directory).
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    "ou=Users,dc=example,dc=com",
    ldap.SCOPE_SUBTREE,
    "(|(userPrincipalName=%(user)s)(sAMAccountName=%(user)s))"
)

# If a user's DN is producible from their username, we don't need to search.
AUTH_LDAP_USER_DN_TEMPLATE = None

# You can map user attributes to Django attributes as so.
AUTH_LDAP_USER_ATTR_MAP = {
    "username": "sAMAccountName",
    "email": "mail",
    "first_name": "givenName",
    "last_name": "sn",
}

AUTH_LDAP_USER_QUERY_FIELD = "username"

# This search ought to return all groups to which the user belongs. django_auth_ldap uses this to determine group
# hierarchy.
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "dc=example,dc=com",
    ldap.SCOPE_SUBTREE,
    "(objectClass=group)"
)
AUTH_LDAP_GROUP_TYPE = NestedGroupOfNamesType()

# Define a group required to login.
AUTH_LDAP_REQUIRE_GROUP = "CN=NETBOX_USERS,DC=example,DC=com"

```

--------------------------------

### Change Logging Example

Source: https://netboxlabs.com/docs/netbox/customization/custom-scripts

Example of how to generate change log data when editing an existing object by taking a snapshot before modification.

```python
if obj.pk and hasattr(obj, 'snapshot'):
    obj.snapshot()

obj.property = "New Value"
obj._changelog_message = 'Example Message Text' # Optional
obj.full_clean()
obj.save()
```

--------------------------------

### Example Device Export Template for Nagios

Source: https://netboxlabs.com/docs/netbox/customization/export-templates

An example Jinja2 template to generate a Nagios host configuration from a list of devices, including status and primary IP checks.

```jinja2
{% for device in queryset %}{% if device.status and device.primary_ip %}define host{
        use                     generic-switch
        host_name               {{ device.name }}
        address                 {{ device.primary_ip.address.ip }}
}
{% endif %}{% endfor %}  

```

--------------------------------

### Cursor Pagination - First Page

Source: https://netboxlabs.com/docs/netbox/integrations/graphql-api

Example of fetching the first page using cursor-based pagination with a start value of 0 and a limit of 20.

```APIDOC
## Cursor Pagination - First Page

### Description
Fetches the first page of results using cursor-based pagination.

### Method
query

### Endpoint
N/A (GraphQL Operation)

### Parameters
#### Query Parameters
- **pagination.start** (integer) - Required - The primary key ID of the first record to fetch. Use 0 for the first page.
- **pagination.limit** (integer) - Optional - The maximum number of records to return. Defaults to 100.

### Request Example
```graphql
query {
  device_list(pagination: {start: 0, limit: 20}) {
    id
  }
}
```

### Response
#### Success Response (200)
- **data.device_list** (list) - A list of device objects.
  - **id** (integer) - The unique identifier for the device.
```

--------------------------------

### Example SENTRY_SEND_DEFAULT_PII Configuration

Source: https://netboxlabs.com/docs/netbox/configuration/error-reporting

This is an example of enabling the `send_default_pii` option directly. Be aware that enabling this will log sensitive data like cookies and authentication tokens. This parameter is being removed in favor of `SENTRY_CONFIG`.

```python
SENTRY_SEND_DEFAULT_PII = True
```

--------------------------------

### Router Example

Source: https://netboxlabs.com/docs/netbox/plugins/development/rest-api

Example of exposing plugin API views using DRF's DefaultRouter in `api/urls.py`.

```APIDOC
## Router Example

Routers map URLs to REST API views (endpoints). NetBox does not provide any custom components for this; the `DefaultRouter` class provided by DRF should suffice for most use cases.

Routers should be exposed in `api/urls.py`. This file **must** define a variable named `urlpatterns`.

```python
# api/urls.py
from netbox.api.routers import NetBoxRouter
from .views import MyModelViewSet

router = NetBoxRouter()
router.register('my-model', MyModelViewSet)
urlpatterns = router.urls
```

This will make the plugin's view accessible at `/api/plugins/my-plugin/my-model/`.
```

--------------------------------

### Example systemd Status Output

Source: https://netboxlabs.com/docs/netbox/installation/4a-gunicorn

Example output from 'systemctl status netbox.service' showing the service is active and running, including details about the gunicorn process.

```text
● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-01-26 11:00:00 CST; 7s ago
       Docs: https://docs.netbox.dev/
   Main PID: 7283 (gunicorn)
      Tasks: 6 (limit: 4545)
     Memory: 556.1M (peak: 556.3M)
        CPU: 3.387s
     CGroup: /system.slice/netbox.service
             ├─7283 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>
             ├─7285 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>
             ├─7286 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>
             ├─7287 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>
             ├─7288 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>
             └─7289 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox>

Jan 26 11:00:00 netbox systemd[1]: Started netbox.service - NetBox WSGI Service.
...
```

--------------------------------

### AND Constraint Example

Source: https://netboxlabs.com/docs/netbox/administration/permissions

Use a JSON object to define constraints that must all be met (logical AND). This example grants access to active sites in the Americas region.

```json
{
  "status": "active",
  "region__name": "Americas"
}
```

--------------------------------

### Serializer Example

Source: https://netboxlabs.com/docs/netbox/plugins/development/rest-api

Example of creating a serializer for a plugin model by subclassing NetBoxModelSerializer.

```APIDOC
## Serializer Example

To create a serializer for a plugin model, subclass `NetBoxModelSerializer` in `api/serializers.py`. Specify the model class and the fields to include within the serializer's `Meta` class.

```python
# api/serializers.py
from rest_framework import serializers
from netbox.api.serializers import NetBoxModelSerializer
from my_plugin.models import MyModel

class MyModelSerializer(NetBoxModelSerializer):
    foo = SiteSerializer(nested=True, allow_null=True)

    class Meta:
        model = MyModel
        fields = ('id', 'foo', 'bar', 'baz')
        brief_fields = ('id', 'url', 'display', 'bar')
```
```

--------------------------------

### Install Plugin in Development Mode

Source: https://netboxlabs.com/docs/netbox/plugins/development

Installs the plugin using pip's editable mode, creating symbolic links to the development directory. Run this command from the plugin's root directory.

```bash
$ pip install -e .

```

--------------------------------

### Example SENTRY_DSN Configuration

Source: https://netboxlabs.com/docs/netbox/configuration/error-reporting

This is an example of how to configure the Sentry Data Source Name (DSN) directly. Note that this parameter is being removed in favor of `SENTRY_CONFIG`.

```python
SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
```

--------------------------------

### Copy NetBox Configuration File

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Copies the example configuration file to 'configuration.py' in the NetBox configuration directory, preparing it for local customization.

```bash
cd /opt/netbox/netbox/netbox/  
sudo cp configuration_example.py configuration.py  
```

--------------------------------

### Create NetBox Installation Directory

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Creates the base directory for NetBox installation if it does not exist and changes the current directory to it.

```bash
sudo mkdir -p /opt/netbox/  
cd /opt/netbox/  
```

--------------------------------

### Example Custom Dashboard Widget

Source: https://netboxlabs.com/docs/netbox/plugins/development/dashboard-widgets

A complete example of a custom dashboard widget that displays configurable content using a `Textarea`.

```python
from django import forms
from extras.dashboard.utils import register_widget
from extras.dashboard.widgets import DashboardWidget, WidgetConfigForm


@register_widget
class ReminderWidget(DashboardWidget):
    default_title = 'Reminder'
    description = 'Add a virtual sticky note'

    class ConfigForm(WidgetConfigForm):
        content = forms.CharField(
            widget=forms.Textarea()
        )

    def render(self, request):
        return self.config.get('content')
```

--------------------------------

### Install System Packages for LDAP

Source: https://netboxlabs.com/docs/netbox/installation/ldap

Installs necessary system packages required for LDAP integration. Ensure you have the appropriate permissions to run these commands.

```bash
sudo apt install -y libldap2-dev libsasl2-dev libssl-dev  
```

--------------------------------

### Install django-storages for Remote File Storage

Source: https://netboxlabs.com/docs/netbox/release-notes/version-2.7

Install the necessary package to enable remote file storage backends. This is a prerequisite for configuring external storage.

```bash
pip install django-storages

```

--------------------------------

### Example Response for Multiple IP Addresses

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This is an example response when retrieving multiple IP addresses. It shows the pagination details and a list of IP address objects.

```json
{
  "count": 42031,
  "next": "http://netbox/api/ipam/ip-addresses/?limit=50&offset=50",
  "previous": null,
  "results": [
    {
      "id": 5618,
      "address": "192.0.2.1/24",
      ...
    },
    {
      "id": 5619,
      "address": "192.0.2.2/24",
      ...
    },
    {
      "id": 5620,
      "address": "192.0.2.3/24",
      ...
    },
    ...
  ]
}


```

--------------------------------

### Check NetBox Installation Method

Source: https://netboxlabs.com/docs/netbox/installation/upgrading

Determine if NetBox was installed from a release package or git repository. This helps in choosing the correct upgrade method.

```bash
ls -ld /opt/netbox /opt/netbox/.git  
```

--------------------------------

### Example SENTRY_TRACES_SAMPLE_RATE Configuration

Source: https://netboxlabs.com/docs/netbox/configuration/error-reporting

This is an example of configuring the transaction sampling rate directly. A low sampling rate (0.1 to 0.2) is recommended to avoid performance penalties. This parameter is being removed in favor of `SENTRY_CONFIG`.

```python
SENTRY_TRACES_SAMPLE_RATE = 0.2
```

--------------------------------

### Install NetBox UI Dependencies with Yarn

Source: https://netboxlabs.com/docs/netbox/development/web-ui

Installs all required front-end dependencies for the NetBox UI. Ensure you are in the 'netbox/project-static' directory before running.

```bash
$ cd netbox/project-static
$ yarn
```

--------------------------------

### Constraint Examples Table

Source: https://netboxlabs.com/docs/netbox/administration/permissions

This table provides examples of various constraint definitions and their corresponding descriptions for filtering objects.

```json
{"status": "active"}
```

```json
{"status__in": ["planned", "reserved"]}
```

```json
{"status": "active", "role": "testing"}
```

```json
{"name__startswith": "Foo"}
```

```json
{"name__iendswith": "bar"}
```

```json
{"vid__gte": 100, "vid__lt": 200}
```

```json
[{"vid__lt": 200}, {"status": "reserved"}]
```

--------------------------------

### Install Pre-Commit Hooks

Source: https://netboxlabs.com/docs/netbox/development/getting-started

Install and enable pre-commit hooks to automatically validate code before committing. This includes linters, system checks, and asset validation.

```bash
python -m pip install ruff pre-commit
pre-commit install
```

--------------------------------

### Add sentry-sdk to Local Requirements

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Install the sentry-sdk library for Sentry integration by adding it to the local_requirements.txt file.

```bash
sudo sh -c "echo 'sentry-sdk' >> /opt/netbox/local_requirements.txt"
```

--------------------------------

### Start NetBox Webhook Receiver

Source: https://netboxlabs.com/docs/netbox/integrations/webhooks

Run this command from the NetBox root directory to start the local webhook listener. Ensure NetBox is configured to send webhooks to `http://localhost:9000/`.

```bash
$ python netbox/manage.py webhook_receiver  
Listening on port http://localhost:9000. Stop with CONTROL-C.  

```

--------------------------------

### Example Response for Creating a Prefix

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This is the JSON response after successfully creating a new IPAM prefix. It includes all the details of the created object.

```json
{
  "id": 18691,
  "url": "http://netbox/api/ipam/prefixes/18691/",
  "display_url": "http://netbox/api/ipam/prefixes/18691/",
  "display": "192.0.2.0/24",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "prefix": "192.0.2.0/24",
  "vrf": null,
  "scope_type": "dcim.site",
  "scope_id": 6,
  "scope": {
    "id": 6,
    "url": "http://netbox/api/dcim/sites/6/",
    "display": "US-East 4",
    "name": "US-East 4",
    "slug": "us-east-4",
    "description": ""
  },
  "tenant": null,
  "vlan": null,
  "status": {
    "value": "active",
    "label": "Active"
  },
  "role": null,
  "is_pool": false,
  "mark_utilized": false,
  "description": "",
  "comments": "",
  "tags": [],
  "custom_fields": {},
  "created": "2025-04-29T15:44:47.597092Z",
  "last_updated": "2025-04-29T15:44:47.597092Z",
  "children": 0,
  "_depth": 0
}


```

--------------------------------

### Example SENTRY_SAMPLE_RATE Configuration

Source: https://netboxlabs.com/docs/netbox/configuration/error-reporting

This is an example of configuring the error sampling rate directly. The value must be between 0 (disabled) and 1.0 (report all errors). This parameter is being removed in favor of `SENTRY_CONFIG`.

```python
SENTRY_SAMPLE_RATE = 0.2
```

--------------------------------

### IP Address Retrieval Example

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This example demonstrates how to retrieve information about a specific IP address using a curl command and jq for pretty-printing the JSON response.

```APIDOC
## GET /api/ipam/ip-addresses/{id}/

### Description
Retrieves details for a specific IP address.

### Method
GET

### Endpoint
/api/ipam/ip-addresses/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the IP address.

### Request Example
```bash
curl -s http://netbox/api/ipam/ip-addresses/2954/ | jq '.'
```

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the IP address.
- **url** (string) - The API URL for the IP address.
- **family** (object) - IP address family (IPv4 or IPv6).
- **address** (string) - The IP address with its subnet mask.
- **vrf** (object or null) - The VRF associated with the IP address.
- **tenant** (object or null) - The tenant associated with the IP address.
- **status** (object) - The operational status of the IP address.
- **role** (object or null) - The role assigned to the IP address.
- **assigned_object_type** (string) - The type of object assigned to this IP address.
- **assigned_object_id** (integer) - The ID of the assigned object.
- **assigned_object** (object) - Details of the assigned object.
- **nat_inside** (object or null) - NAT mapping for inside interface.
- **nat_outside** (object or null) - NAT mapping for outside interface.
- **dns_name** (string) - The DNS name associated with the IP address.
- **description** (string) - A description for the IP address.
- **tags** (array) - List of tags associated with the IP address.
- **custom_fields** (object) - Custom fields for the IP address.
- **created** (string) - The date the IP address was created.
- **last_updated** (string) - The date the IP address was last updated.

#### Response Example
```json
{
  "id": 2954,
  "url": "http://netbox/api/ipam/ip-addresses/2954/",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "address": "192.168.0.42/26",
  "vrf": null,
  "tenant": null,
  "status": {
    "value": "active",
    "label": "Active"
  },
  "role": null,
  "assigned_object_type": "dcim.interface",
  "assigned_object_id": 114771,
  "assigned_object": {
    "id": 114771,
    "url": "http://netbox/api/dcim/interfaces/114771/",
    "device": {
      "id": 2230,
      "url": "http://netbox/api/dcim/devices/2230/",
      "name": "router1",
      "display_name": "router1"
    },
    "name": "et-0/1/2",
    "cable": null,
    "connection_status": null
  },
  "nat_inside": null,
  "nat_outside": null,
  "dns_name": "",
  "description": "Example IP address",
  "tags": [],
  "custom_fields": {},
  "created": "2020-08-04",
  "last_updated": "2020-08-04T14:12:39.666885Z"
}
```
```

--------------------------------

### Install NetBox Requirements

Source: https://netboxlabs.com/docs/netbox/development/getting-started

Install all required Python packages for NetBox development using pip. This command should be run with the virtual environment activated.

```bash
python -m pip install -r requirements.txt  

```

--------------------------------

### Example Custom Link URL with Jinja

Source: https://netboxlabs.com/docs/netbox/customization/custom-links

This example shows how to construct a URL for a custom link using Jinja templating to include the object's name.

```html
<a href="https://nms.example.com/nodes/?name=Router4">View NMS</a>
```

--------------------------------

### Example SENTRY_TAGS Configuration

Source: https://netboxlabs.com/docs/netbox/configuration/error-reporting

This is an example of configuring custom tags to be applied to Sentry error reports. Avoid using the `netbox.` prefix for custom tag names.

```python
SENTRY_TAGS = {
    "custom.foo": "123",
    "custom.bar": "abc",
}
```

--------------------------------

### Add django-storages to Local Requirements

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Install the django-storages library by adding it to the local_requirements.txt file for remote file storage.

```bash
sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
```

--------------------------------

### Install Python Package with Pip

Source: https://netboxlabs.com/docs/netbox/plugins/installation

Install a plugin's Python package using pip within NetBox's virtual environment. Always refer to the specific plugin's documentation for exact package names and any prerequisites.

```bash
$ source /opt/netbox/venv/bin/activate
(venv) $ pip install <package>
```

--------------------------------

### Example REST API Request with v2 Token

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This example demonstrates a cURL request to the DCIM sites endpoint using a v2 token for authentication and specifying JSON acceptance with indentation.

```bash
$ curl -H "Authorization: Bearer nbt_4F9DAouzURLb.zjebxBPzICiPbWz0Wtx0fTL7bCKXKGTYhNzkgC2S" \
-H "Accept: application/json; indent=4" \
https://netbox/api/dcim/sites/  
{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [...] 
}
```

--------------------------------

### Add boto3 to Local Requirements

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Install the boto3 library for Amazon S3 backend integration by adding it to the local_requirements.txt file.

```bash
sudo sh -c "echo 'boto3' >> /opt/netbox/local_requirements.txt"
```

--------------------------------

### Cursor Pagination - Subsequent Page

Source: https://netboxlabs.com/docs/netbox/integrations/graphql-api

Example of fetching a subsequent page using cursor-based pagination, where the start value is determined by the last record's ID from the previous page.

```APIDOC
## Cursor Pagination - Subsequent Page

### Description
Fetches a subsequent page of results using cursor-based pagination.

### Method
query

### Endpoint
N/A (GraphQL Operation)

### Parameters
#### Query Parameters
- **pagination.start** (integer) - Required - The primary key ID of the first record to fetch. Set to the last record's ID + 1 from the previous response.
- **pagination.limit** (integer) - Optional - The maximum number of records to return. Defaults to 100.

### Request Example
```graphql
query {
  device_list(pagination: {start: 124, limit: 20}) {
    id
  }
}
```

### Response
#### Success Response (200)
- **data.device_list** (list) - A list of device objects.
  - **id** (integer) - The unique identifier for the device.
```

--------------------------------

### Grant Custom Default Permissions

Source: https://netboxlabs.com/docs/netbox/configuration/security

Apply custom default permissions to all authenticated users. This example allows all users to create device roles starting with 'temp'. Remember to reproduce default mappings if retaining them.

```python
DEFAULT_PERMISSIONS = {
    'dcim.add_devicerole': (
        {'name__startswith': 'temp'},
    )
}
```

--------------------------------

### Enable Apache modules and site, then reload

Source: https://netboxlabs.com/docs/netbox/installation/http-server

Enable necessary Apache modules (ssl, proxy, proxy_http, headers, rewrite), enable the NetBox site configuration, and reload Apache to apply changes.

```bash
sudo a2enmod ssl proxy proxy_http headers rewrite
```

```bash
sudo a2ensite netbox
```

```bash
sudo systemctl restart apache2
```

--------------------------------

### List Interfaces by Device ID

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This example shows how to filter and retrieve a list of interfaces belonging to a specific device using query parameters.

```APIDOC
## GET /api/dcim/interfaces/

### Description
Retrieves a list of interfaces, filterable by device ID.

### Method
GET

### Endpoint
/api/dcim/interfaces/

### Parameters
#### Query Parameters
- **device_id** (integer) - Required - Filters interfaces to only those belonging to the specified device.

### Request Example
```bash
GET /api/dcim/interfaces/?device_id=123
```
```

--------------------------------

### Install PostgreSQL

Source: https://netboxlabs.com/docs/netbox/installation/postgresql

Installs PostgreSQL 14 or later on Debian-based systems. Ensure your system's package list is up-to-date before installation.

```bash
sudo apt update 
sudo apt install -y postgresql
```

--------------------------------

### Install System Packages for NetBox

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Installs essential system packages required for NetBox and its dependencies. Ensure Python 3.12 or later is installed.

```bash
sudo apt install -y python3 python3-pip python3-venv python3-dev \
build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
libssl-dev zlib1g-dev  
```

--------------------------------

### Check NetBox Service Logs

Source: https://netboxlabs.com/docs/netbox/installation/4b-uwsgi

If the NetBox service fails to start, use journalctl to check for log messages indicating the problem.

```bash
journalctl -eu netbox  

```

--------------------------------

### Example of Saved Filter Query Parameters

Source: https://netboxlabs.com/docs/netbox/features/search

Illustrates how a complex set of filter parameters can be represented as a saved filter for easier reuse.

```url
?status=planned&device_type_id=78&region_id=12
```

```url
?filter=my-custom-filter
```

--------------------------------

### Replicate Uploaded Media Directory

Source: https://netboxlabs.com/docs/netbox/installation/upgrading

Ensure that user-uploaded media files are available in the new NetBox installation by copying the media directory.

```bash
sudo cp -pr /opt/netbox-$OLDVER/netbox/media/ /opt/netbox/netbox/  
```

--------------------------------

### Example GraphQL Query Response

Source: https://netboxlabs.com/docs/netbox/integrations/graphql-api

This is an example of the JSON response you can expect when querying for circuits.

```json
{
  "data": {
    "circuits": [
      {
        "cid": "1002840283",
        "provider": {
          "name": "CenturyLink"
        }
      },
      {
        "cid": "1002840457",
        "provider": {
          "name": "CenturyLink"
        }
      }
    ]
  }
}
```

--------------------------------

### Configure nginx for NetBox

Source: https://netboxlabs.com/docs/netbox/installation/http-server

Copy the NetBox nginx configuration file and create a symbolic link to enable it. Ensure 'netbox.example.com' is replaced with your domain or IP, matching ALLOWED_HOSTS.

```bash
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
```

```bash
sudo rm /etc/nginx/sites-enabled/default
```

```bash
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
```

--------------------------------

### Install django-auth-ldap Package

Source: https://netboxlabs.com/docs/netbox/installation/ldap

Installs the django-auth-ldap package within the activated Python virtual environment. This package is essential for enabling LDAP authentication.

```bash
source /opt/netbox/venv/bin/activate  
pip3 install django-auth-ldap  
```

--------------------------------

### Configure NetBox for Okta SSO

Source: https://netboxlabs.com/docs/netbox/administration/authentication/okta

Add these parameters to your configuration.py file to enable Okta authentication. Replace placeholders with your specific Okta credentials and domain.

```python
REMOTE_AUTH_BACKEND = 'social_core.backends.okta_openidconnect.OktaOpenIdConnect'  
SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '{Client ID}'  
SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '{Client secret}'  
SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = 'https://{Okta domain}/oauth2/'  
```

--------------------------------

### Start NetBox Development Server

Source: https://netboxlabs.com/docs/netbox/development/getting-started

Run the Django development server to serve NetBox locally. The server auto-reloads on code changes and performs system checks.

```bash
$ ./manage.py runserver
```

--------------------------------

### Basic Context Data Example

Source: https://netboxlabs.com/docs/netbox/features/context-data

This JSON represents a basic configuration context, defining a list of syslog servers. It can be applied to objects based on certain characteristics.

```json
{
    "syslog-servers": [
        "192.168.43.107",
        "192.168.48.112"
    ]
}
```

--------------------------------

### Configure Plugin Build with pyproject.toml

Source: https://netboxlabs.com/docs/netbox/plugins/development

Defines project metadata and build system requirements for packaging a NetBox plugin. Ensure 'setuptools' is listed in requires and build-backend.

```toml
# See PEP 518 for the spec of this file
# https://www.python.org/dev/peps/pep-0518/

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name =  "my-example-plugin"
version = "0.1.0"
authors = [
    {name = "John Doe", email = "test@netboxlabs.com"},
]
description = "An example NetBox plugin."
readme = "README.md"

classifiers=[
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Developers',
    'Natural Language :: English',
    "Programming Language :: Python :: 3 :: Only",
    'Programming Language :: Python :: 3.12',
    'Programming Language :: Python :: 3.13',
    'Programming Language :: Python :: 3.14',
]

requires-python = ">=3.12.0"

```

--------------------------------

### Creating a Device with Rack Specification

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

Examples of how to specify a related rack object when creating a new device, either by its numeric ID or by a set of unique attributes.

```APIDOC
## Creating a Device with Rack Specification

### Description
When creating a new device, the related rack can be specified by its numeric ID (PK) or by a set of attributes that uniquely identify the rack.

### Request Example (by ID)
```json
{
    "name": "MyNewDevice",
    "rack": 123,
    ...
}
```

### Request Example (by Attributes)
```json
{
    "name": "MyNewDevice",
    "rack": {
        "site": {
            "name": "Equinix DC6"
        },
        "name": "R204"
    },
    ...
}
```

**Note:** If the provided parameters do not return exactly one object, a validation error is raised.
```

--------------------------------

### VLAN Serialization Example

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

An example of a complete serialization of a VLAN object, including nested brief representations of related objects like site and group.

```APIDOC
## VLAN Serialization Example

### Description
This example shows the complete representation of a VLAN object, including nested brief representations of its parent site and group.

### Response Example
```json
{
    "id": 1048,
    "site": {
        "id": 7,
        "url": "http://netbox/api/dcim/sites/7/",
        "name": "Corporate HQ",
        "slug": "corporate-hq"
    },
    "group": {
        "id": 4,
        "url": "http://netbox/api/ipam/vlan-groups/4/",
        "name": "Production",
        "slug": "production"
    },
    "vid": 101,
    "name": "Users-Floor1",
    "tenant": null,
    "status": {
        "value": 1,
        "label": "Active"
    },
    "role": {
        "id": 9,
        "url": "http://netbox/api/ipam/roles/9/",
        "name": "User Access",
        "slug": "user-access"
    },
    "description": "",
    "display_name": "101 (Users-Floor1)",
    "custom_fields": {}
}
```
```

--------------------------------

### List and Order Interfaces by Device ID

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This example demonstrates how to filter interfaces by device ID and order the results by creation date in descending order.

```APIDOC
## GET /api/dcim/interfaces/

### Description
Retrieves a list of interfaces, filterable by device ID and orderable by creation date.

### Method
GET

### Endpoint
/api/dcim/interfaces/

### Parameters
#### Query Parameters
- **device_id** (integer) - Required - Filters interfaces to only those belonging to the specified device.
- **ordering** (string) - Optional - Defines the sort order. Use a negative prefix (e.g., `-created`) for descending order.

### Request Example
```bash
GET /api/dcim/interfaces/?device_id=123&ordering=-created
```
```

--------------------------------

### Configure Redis with Host, Port, and Credentials

Source: https://netboxlabs.com/docs/netbox/configuration/required-parameters

Use this configuration for standard Redis connections. Ensure `HOST` and `PORT` are set correctly for your Redis instance.

```python
REDIS = {
    'tasks': {
        'HOST': 'redis.example.com',
        'PORT': 1234,
        'USERNAME': 'netbox',
        'PASSWORD': 'foobar',
        'DATABASE': 0,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'USERNAME': '',
        'PASSWORD': '',
        'DATABASE': 1,
        'SSL': False,
    }
}
```

--------------------------------

### Webhook Receiver Output Example

Source: https://netboxlabs.com/docs/netbox/integrations/webhooks

This is an example of the output you will see in your terminal when the webhook receiver successfully processes an incoming request. It displays request headers and the body.

```text
[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 -  
Host: localhost:9000  
User-Agent: curl/7.58.0  
Accept: */*  
Content-Length: 14  
Content-Type: application/x-www-form-urlencoded  
  
{"foo": "bar"}  
------------  

```

--------------------------------

### Configure Plugin Settings

Source: https://netboxlabs.com/docs/netbox/configuration/plugins

Define specific configuration parameters for installed plugins. Each plugin has its own set of supported parameters, which must be referenced in its documentation. A plugin must also be listed in the PLUGINS setting for its configuration to be applied.

```python
PLUGINS_CONFIG = {
    'plugin1': {
        'foo': 123,
        'bar': True
    },
    'plugin2': {
        'foo': 456,
    },
}
```

--------------------------------

### Launch NetBox Shell

Source: https://netboxlabs.com/docs/netbox/administration/netbox-shell

Run these commands to navigate to the NetBox directory, activate the virtual environment, and launch the management shell.

```bash
cd /opt/netbox  
source /opt/netbox/venv/bin/activate  
python3 netbox/manage.py nbshell  
```

--------------------------------

### Provision New Branch Site Script

Source: https://netboxlabs.com/docs/netbox/customization/custom-scripts

This script automates the creation of a new branch site and associated access switches. It prompts the user for site name, switch count, and switch model, then creates the objects and returns a CSV of the new devices.

```python
from django.utils.text import slugify  
from dcim.choices import DeviceStatusChoices, SiteStatusChoices  
from dcim.models import Device, DeviceRole, DeviceType, Manufacturer, Site  
from extras.scripts import *  

class NewBranchScript(Script):

    class Meta(Script.Meta):
        name = "New Branch"
        description = "Provision a new branch site"
        field_order = ['site_name', 'switch_count', 'switch_model']

    site_name = StringVar(
        description="Name of the new site"
    )
    switch_count = IntegerVar(
        description="Number of access switches to create"
    )
    manufacturer = ObjectVar(
        model=Manufacturer,
        required=False
    )
    switch_model = ObjectVar(
        description="Access switch model",
        model=DeviceType,
        query_params={
            'manufacturer_id': '$manufacturer'
        }
    )

    def run(self, data, commit):

        # Create the new site
        site = Site(
            name=data['site_name'],
            slug=slugify(data['site_name']),
            status=SiteStatusChoices.STATUS_PLANNED
        )
        site.full_clean()
        site.save()
        self.log_success(f"Created new site: {site}")

        # Create access switches
        switch_role = DeviceRole.objects.get(name='Access Switch')
        for i in range(1, data['switch_count'] + 1):
            switch = Device(
                device_type=data['switch_model'],
                name=f'{site.slug}-switch{i}',
                site=site,
                status=DeviceStatusChoices.STATUS_PLANNED,
                role=switch_role
            )
            switch.full_clean()
            switch.save()
            self.log_success(f"Created new switch: {switch}")

        # Generate a CSV table of new devices
        output = [
            'name,make,model'
        ]
        for switch in Device.objects.filter(site=site):
            attrs = [
                switch.name,
                switch.device_type.manufacturer.name,
                switch.device_type.model
            ]
            output.append(','.join(attrs))

        return '\n'.join(output)
```

--------------------------------

### User Token Constraint Example

Source: https://netboxlabs.com/docs/netbox/administration/permissions

Use the special `$user` token to reference the current user within a constraint. This example restricts access to objects created by the current user.

```json
{
  "created_by": "$user"
}
```

--------------------------------

### OR Constraint Example

Source: https://netboxlabs.com/docs/netbox/administration/permissions

Use a JSON list of objects to define constraints where any one object's conditions can be met (logical OR). This example constrains VLANs by ID range or status.

```json
[
  {
    "vid__gte": 100,
    "vid__lt": 200
  },
  {
    "status": "reserved"
  }
]
```

--------------------------------

### Run Database Migrations

Source: https://netboxlabs.com/docs/netbox/development/release-checklist

Execute database migrations to test upgrade paths. This command is used after loading demo data from a previous version to ensure data integrity.

```bash
./manage.py migrate
```

--------------------------------

### Download and Extract Latest NetBox Release

Source: https://netboxlabs.com/docs/netbox/installation/upgrading

Download the latest stable NetBox release and extract it to the desired installation path. This method is for users who originally installed NetBox from a release package.

```bash
# Set $NEWVER to the NetBox version being installed
NEWVER=4.5.0
wget https://github.com/netbox-community/netbox/archive/v$NEWVER.tar.gz
sudo tar -xzf v$NEWVER.tar.gz -C /opt
sudo ln -sfn /opt/netbox-$NEWVER/ /opt/netbox  
```

--------------------------------

### Run NetBox Development Server

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Start NetBox's development server for testing purposes. Ensure the Python virtual environment is active. This server is not suitable for production use.

```bash
python3 manage.py runserver 0.0.0.0:8000 --insecure  
```

--------------------------------

### Cursor Pagination - First Page

Source: https://netboxlabs.com/docs/netbox/integrations/graphql-api

Fetch the first page using cursor-based pagination by setting the start parameter to 0. If the start parameter is omitted, offset-based pagination is used by default.

```graphql
query {
  device_list(pagination: {start: 0, limit: 20}) {
    id
  }
}

```

--------------------------------

### Importing Webhook Callbacks in Plugin Initialization

Source: https://netboxlabs.com/docs/netbox/plugins/development/webhooks

Demonstrates how to import webhook callback modules during plugin initialization within the `ready()` method of the `PluginConfig` class. This ensures callbacks are registered when NetBox starts.

```python
def ready(self):
    super().ready()
    from my_plugin import webhook_callbacks

```

--------------------------------

### Example Paginated API Response

Source: https://netboxlabs.com/docs/netbox/integrations/rest-api

This is an example of a paginated response from a NetBox API list endpoint. It includes the total count of objects, links to the next and previous pages, and the list of objects for the current page.

```http
HTTP 200 OK  
Allow: GET, POST, OPTIONS  
Content-Type: application/json  
Vary: Accept  
  
{
    "count": 2861,
    "next": "http://netbox/api/dcim/devices/?limit=50&offset=50",
    "previous": null,
    "results": [
        {
            "id": 231,
            "name": "Device1",
            ...
        },
        {
            "id": 232,
            "name": "Device2",
            ...
        },
        ...
    ]
}


```

--------------------------------

### Enable Plugin in configuration.py

Source: https://netboxlabs.com/docs/netbox/plugins/installation

Add the plugin's name to the `PLUGINS` list in your `configuration.py` file to enable it within NetBox.

```python
PLUGINS = [
    # ...
    'plugin_name',
]
```

--------------------------------

### Configure Multiple Databases

Source: https://netboxlabs.com/docs/netbox/configuration/required-parameters

Define multiple database connections, including a default and potentially others for plugins. Each database entry requires specific parameters like NAME, USER, PASSWORD, HOST, PORT, CONN_MAX_AGE, and ENGINE.

```python
DATABASES = {
    'default': {...},
    'external1': {...},
    'external2': {...},
}
```

--------------------------------

### Get Custom Fields QuerySet

Source: https://netboxlabs.com/docs/netbox/plugins/development/models

Retrieve the QuerySet of all CustomFields assigned to a model.

```python
>>> tenant = Tenant.objects.first()
>>> tenant.custom_fields
<RestrictedQuerySet [<CustomField: Primary site>, <CustomField: Customer ID>, <CustomField: Is active>]>
```

--------------------------------

### Create a New Object

Source: https://netboxlabs.com/docs/netbox/administration/netbox-shell

Instantiate a model, set required attributes, and call `save()` to create a new object. This example creates a new VLAN.

```python
>>> lab1 = Site.objects.get(pk=7)  
>>> myvlan = VLAN(vid=123, name='MyNewVLAN', site=lab1)  
>>> myvlan.full_clean()  
>>> myvlan.save()  

```

--------------------------------

### Check Python Version

Source: https://netboxlabs.com/docs/netbox/installation/netbox

Verifies that the installed Python version meets the minimum requirement of 3.12.

```bash
python3 -V  
```

--------------------------------

### Example Webhook Payload with Context

Source: https://netboxlabs.com/docs/netbox/plugins/development/webhooks

A sample webhook payload demonstrating the structure, including event details, object data, snapshots, and custom context data provided by a registered callback.

```json
{
    "event": "updated",
    "timestamp": "2025-08-07T14:24:30.627321+00:00",
    "object_type": "dcim.site",
    "username": "admin",
    "request_id": "49e3e39e-7333-4b9c-a9af-19f0dc1e7dc9",
    "data": {
        "id": 2,
        "url": "/api/dcim/sites/2/",
        ...
    },
    "snapshots": {...},
    "context": {
        "foo": 123
    }
}

```

--------------------------------

### Verify PostgreSQL Version

Source: https://netboxlabs.com/docs/netbox/installation/postgresql

Checks the installed PostgreSQL version. NetBox requires version 14 or later.

```bash
psql -V
```
Tokens:
Raw