NetBox

https://netbox.readthedocs.io/en/stable/
Admin
NetBox is a leading network source of truth platform that combines IP address management (IPAM) and...
Tokens:351,755
Snippets:3,196
Trust Score:8.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Run netbox setup to scaffold the instance root

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Runs netbox setup with --target /opt/netbox to create the local configuration skeleton and copy bundled deployment examples. It is non-destructive and does not install systemd units or configure an HTTP server.

```bash
sudo /opt/netbox/venv/bin/netbox setup --target /opt/netbox
```

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

### Start documentation server with zensical serve

Source: https://netbox.readthedocs.io/en/stable/development/release-checklist/

Command to start the documentation server for manually performing a new installation of NetBox in a temporary environment. This step must not be automated to catch errors or omissions in the documentation.

```bash
zensical serve
```

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

### Install Apache

Source: https://netbox.readthedocs.io/en/stable/installation/5-http-server/

Installs the Apache web server using apt.

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

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

### Install nginx

Source: https://netbox.readthedocs.io/en/stable/installation/5-http-server/

Installs the nginx web server using apt.

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

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

### NetBox shell startup banner

Source: https://netbox.readthedocs.io/en/stable/administration/netbox-shell/

Example output when starting the NetBox shell. Shows the NetBox interactive shell banner with Python, Django, and NetBox versions, and hints for lsapps() and lsmodels().

```text
(venv) $ python3 netbox/manage.py nbshell
### NetBox interactive shell (localhost)
### Python v3.12.3 | Django v5.2.10 | NetBox Community v4.5.1
### lsapps() & lsmodels() will show available models. Use help(<model>) for more info.
```

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

### Manual pip install as root

Source: https://netbox.readthedocs.io/en/stable/plugins/installation/

Manual installation method: switch to root shell, activate the virtual environment, and run pip install. Requires write permissions to the virtual environment directory.

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

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

### Enable and start netbox services

Source: https://netbox.readthedocs.io/en/stable/installation/4b-uwsgi/

Enables and starts the netbox and netbox-rq services to run at boot.

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

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

### Install git

Source: https://netbox.readthedocs.io/en/stable/installation/3-netbox/

Installs git if it is not already installed.

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

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

### Install NetBox plugin: add package and run upgrade script

Source: https://netbox.readthedocs.io/en/stable/installation/5-http-server/

Commands to add a plugin package to /opt/netbox/local_requirements.txt and run the upgrade script. The '<package>' placeholder must be replaced with the actual package name. This is a minimal setup; plugins may require additional configuration.

```bash
$ sudo sh -c "echo '<package>' >> /opt/netbox/local_requirements.txt"
$ sudo /opt/netbox/upgrade.sh
```

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

### Copy configuration_example.py to configuration.py

Source: https://netbox.readthedocs.io/en/stable/installation/3-netbox/

Move into the NetBox configuration directory and copy the example configuration file to create your local configuration file.

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

```

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

### Compare deployment examples

Source: https://netbox.readthedocs.io/en/stable/installation/upgrading/

Scaffolds examples into a temporary directory and diffs them against the local copies without modifying the instance root.

```bash
EXAMPLES_DIR=$(mktemp -d)
/opt/netbox/venv/bin/netbox setup --target "$EXAMPLES_DIR"
diff --recursive /opt/netbox/contrib "$EXAMPLES_DIR/contrib"
rm -rf "$EXAMPLES_DIR"
```

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

### Start services after migration

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Starts the NetBox services after the migration is complete. The previous installation should be retained until the new deployment is validated.

```bash
sudo systemctl start netbox netbox-rq
```

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

### Copy gunicorn configuration to new NetBox version

Source: https://netbox.readthedocs.io/en/stable/installation/upgrading/

If gunicorn was set up following the original installation guide, copy its configuration file to the new installation.

```bash
sudo cp /opt/netbox-$OLDVER/gunicorn.py /opt/netbox/
```

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

### Set BASE_PATH to 'netbox/'

Source: https://netbox.readthedocs.io/en/stable/configuration/system/

Configures the base URL path for NetBox when installed under a subdirectory. Do not include scheme or domain. Example: if installed at https://example.com/netbox/, set BASE_PATH = 'netbox/'.

```python
BASE_PATH = 'netbox/'
```

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

### Scaffold new instance root and create mutable directories

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Creates the new instance root /srv/netbox, runs 'netbox setup --target /srv/netbox', and creates the mutable directories (media, reports, scripts, static) with proper ownership.

```bash
sudo mkdir -p /srv/netbox
sudo chown root:netbox /srv/netbox
sudo chmod 755 /srv/netbox
sudo /opt/netbox-venv/bin/netbox setup --target /srv/netbox
sudo mkdir -p /srv/netbox/{media,reports,scripts,static}
sudo chown --recursive netbox:netbox \
    /srv/netbox/media \
    /srv/netbox/reports \
    /srv/netbox/scripts \
    /srv/netbox/static
```

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

### Custom DEFAULT_PERMISSIONS example

Source: https://netbox.readthedocs.io/en/stable/configuration/security/

Example of overriding DEFAULT_PERMISSIONS to allow all users to create device roles with names starting with 'temp'. Note that this replaces the default mapping, so include the default entries if needed.

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

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

### Install plugins and local requirements into new virtual environment

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Installs all plugins and local requirements into the new virtual environment before running upgrade tasks. Must be done before the upgrade step.

```bash
sudo /opt/netbox-venv/bin/python -m pip install \
    -r /srv/netbox/local_requirements.txt
```

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

### GET /api/dcim/devices/?name__ic=switch

Source: https://netbox.readthedocs.io/en/stable/reference/filtering/

Example of a string field lookup expression that returns all devices with 'switch' in the name (case-insensitive).

```APIDOC
## GET /api/dcim/devices/?name__ic=switch

### Description
Returns all devices with 'switch' in the name using the `ic` (contains, case-insensitive) lookup expression on the `name` field.

### Method
GET

### Endpoint
/api/dcim/devices/?name__ic=switch

### Parameters
#### Query Parameters
- **name__ic** (string) - Required - Filter for names containing the specified value (case-insensitive).

### Response
#### Success Response (200)
- **results** (array) - List of device objects matching the filter.

#### Response Example
{
  "results": []
}
```

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

### API_TOKEN_PEPPERS configuration example

Source: https://netbox.readthedocs.io/en/stable/configuration/required-parameters/

Defines a dictionary of cryptographic peppers for hashing v2 API tokens. The example pepper must not be used in production. Peppers must be at least 50 characters and should be random. Start with pepper ID 1.

```python
API_TOKEN_PEPPERS = {
    # DO NOT USE THIS EXAMPLE PEPPER IN PRODUCTION
    1: 'kp7ht*76fiQAhUi5dHfASLlYUE_S^gI^(7J^K5M!LfoH@vl&b_',
}
```

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

### GET /api/ipam/vlans/?vid__gt=900

Source: https://netbox.readthedocs.io/en/stable/reference/filtering/

Example of a numeric field lookup expression that returns all VLANs with a VLAN ID greater than 900.

```APIDOC
## GET /api/ipam/vlans/?vid__gt=900

### Description
Returns all VLANs with a VLAN ID greater than 900 using the `gt` lookup expression on the `vid` field.

### Method
GET

### Endpoint
/api/ipam/vlans/?vid__gt=900

### Parameters
#### Query Parameters
- **vid__gt** (integer) - Required - Filter for VLAN ID greater than the specified value.

### Response
#### Success Response (200)
- **results** (array) - List of VLAN objects matching the filter.

#### Response Example
{
  "results": []
}
```

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

### JSON response for IP address GET request

Source: https://netbox.readthedocs.io/en/stable/integrations/rest-api/

Example JSON response returned by the GET request for IP address 2954. Shows the structure of an IP address object, including nested fields like family, status, and assigned_object.

```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"
}
```

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

### Render documentation site before building

Source: https://netbox.readthedocs.io/en/stable/development/building-the-package/

Install requirements and render the documentation site with zensical, using -c to clean cache and -s for strict mode. This must be done before building the package.

```bash
python -m pip install -r requirements.txt
zensical build -c -s
```

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

### GET /api/ipam/vlans/?group_id__n=3203

Source: https://netbox.readthedocs.io/en/stable/reference/filtering/

Example of a foreign key lookup expression that returns all VLANs that don't have a VLAN Group ID of 3203.

```APIDOC
## GET /api/ipam/vlans/?group_id__n=3203

### Description
Returns all VLANs that do not have a VLAN Group ID of 3203 using the `n` (negation) lookup expression on the `group_id` field.

### Method
GET

### Endpoint
/api/ipam/vlans/?group_id__n=3203

### Parameters
#### Query Parameters
- **group_id__n** (integer) - Required - Filter for VLANs where the group ID is not equal to the specified value.

### Response
#### Success Response (200)
- **results** (array) - List of VLAN objects matching the filter.

#### Response Example
{
  "results": []
}
```

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

### Example pyproject.toml for a NetBox plugin

Source: https://netbox.readthedocs.io/en/stable/plugins/development/

Example configuration file for packaging a NetBox plugin. Defines the build system using setuptools, project metadata (name, version, authors, description, readme, classifiers), and requires Python >=3.12.0.

```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"
```

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

### GET /api/dcim/sites/?tag__any=foo&tag__any=bar

Source: https://netbox.readthedocs.io/en/stable/reference/filtering/

Example of a tag lookup expression using the `any` expression to return sites with either tag 'foo' or 'bar'.

```APIDOC
## GET /api/dcim/sites/?tag__any=foo&tag__any=bar

### Description
Returns sites that have any of the specified tags (logical OR) using the `any` lookup expression on the `tag` field.

### Method
GET

### Endpoint
/api/dcim/sites/?tag__any=foo&tag__any=bar

### Parameters
#### Query Parameters
- **tag__any** (string) - Required - Filter for sites that have any of the specified tags. Multiple values are allowed.

### Response
#### Success Response (200)
- **results** (array) - List of site objects matching the filter.

#### Response Example
{
  "results": []
}
```

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

### Copy active configuration and optional local_requirements.txt

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Copies the active configuration.py from the existing installation to /srv/netbox/conf/configuration.py. If local_requirements.txt exists, it is copied over the empty file created by 'netbox setup'.

```bash
sudo cp /opt/netbox/netbox/netbox/configuration.py \
    /srv/netbox/conf/configuration.py

if [ -f /opt/netbox/local_requirements.txt ]; then
    sudo cp /opt/netbox/local_requirements.txt \
        /srv/netbox/local_requirements.txt
fi
```

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

### Example DATABASES configuration

Source: https://netbox.readthedocs.io/en/stable/configuration/required-parameters/

Example configuration for the 'default' database using PostgreSQL backend. Includes all required parameters: ENGINE, NAME, USER, PASSWORD, HOST, PORT, and CONN_MAX_AGE. The ENGINE must be PostgreSQL-compatible; if not defined, the default 'django.db.backends.postgresql' is used.

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'netbox',               # Database name
        'USER': 'netbox',               # PostgreSQL username
        'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password
        'HOST': 'localhost',            # Database server
        'PORT': '',                     # Database port (leave blank for default)
        'CONN_MAX_AGE': 300,            # Max database connection age
    }
}
```

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

### Adapt deployment examples with sed commands

Source: https://netbox.readthedocs.io/en/stable/installation/3b-python-package/

Removes source-tree references from the deployment example files copied to /opt/netbox/contrib/ to adapt them for the package layout. The commands modify netbox.service, netbox-rq.service, uwsgi.ini, nginx.conf, and apache.conf.

```bash
sudo sed -i \
    's| --pythonpath /opt/netbox/netbox||' \
    /opt/netbox/contrib/netbox.service

sudo sed -i \
    's|/opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py|/opt/netbox/venv/bin/netbox|' \
    /opt/netbox/contrib/netbox-rq.service

sudo sed -i \
    's|chdir = netbox|chdir = /opt/netbox|' \
    /opt/netbox/contrib/uwsgi.ini

sudo sed -i \
    's|/opt/netbox/netbox/static|/opt/netbox/static|g' \
    /opt/netbox/contrib/nginx.conf \
    /opt/netbox/contrib/apache.conf
```

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

### Example session for rebasing from upstream (continued)

Source: https://netbox.readthedocs.io/en/stable/development/git-cheat-sheet/

Shows the successful rebase and push after fetching and rebasing. The output includes fetch progress, rebase application messages, and the final push result.

```bash
$ git fetch
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (1/1), done.
From https://github.com/netbox-community/netbox
   815b2d8a2..8c35ebbb7  develop    -> origin/develop
$ git rebase origin/develop
First, rewinding head to replay your work on top of it...
Applying: Further tweaks to the PR template
Applying: Changelog for #10176, #10217
$ git push
Counting objects: 9, done.
Delta compression using up to 16 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 1.02 KiB | 1.02 MiB/s, done.
Total 9 (delta 6), reused 0 (delta 0)
remote: Resolving deltas: 100% (6/6), completed with 5 local objects.
To https://github.com/netbox-community/netbox.git
   8c35ebbb7..ada745324  develop -> develop
```

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

### Constrained dependency example in base_requirements.txt

Source: https://netbox.readthedocs.io/en/stable/development/release-checklist/

Shows how to pin a dependency to a specific version to work around bugs or breaking changes. This constraint is added to base_requirements.txt to prevent newer packages from being installed when updating pinned dependencies in requirements.txt.

```text
# https://github.com/encode/django-rest-framework/issues/6053
djangorestframework==3.8.1
```

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

### Accessing request data in a NetBox script

Source: https://netbox.readthedocs.io/en/stable/customization/custom-scripts/

Use self.request to get the current HTTP request. The example retrieves the username and client IP address, then logs an info message. HTTP_X_FORWARDED_FOR is used if present, otherwise REMOTE_ADDR.

```python
username = self.request.user.username
ip_address = self.request.META.get('HTTP_X_FORWARDED_FOR') or \
    self.request.META.get('REMOTE_ADDR')
self.log_info(f"Running as user {username} (IP: {ip_address})...")
```

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

### Install wheel and run netbox check

Source: https://netbox.readthedocs.io/en/stable/development/building-the-package/

Creates a throwaway virtual environment, installs the wheel, and runs `netbox check` with environment variables pointing to the smoke-test configuration. Run from the repository root so `PYTHONPATH` can find `scripts/smoketest_configuration.py`.

```bash
python -m venv /tmp/netbox-build-test
/tmp/netbox-build-test/bin/python -m pip install --upgrade pip
/tmp/netbox-build-test/bin/python -m pip install dist/*.whl
PYTHONPATH=$PWD/scripts \
NETBOX_CONFIGURATION=smoketest_configuration \
NETBOX_ROOT=/tmp/netbox-build-test-root \
NETBOX_SMOKETEST_BASE=/tmp/netbox-build-test-root \
/tmp/netbox-build-test/bin/netbox check
```

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

### Install Redis server

Source: https://netbox.readthedocs.io/en/stable/installation/2-redis/

Installs the Redis server package using apt. Run this command as a user with sudo privileges.

```bash
sudo apt install -y redis-server
```
Tokens:
Raw