Inicio Explorar Ayuda
Iniciar sesión
LBP
/
netbox
espejo de https://github.com/netbox-community/netbox.git
2
0
Fork 0
Archivos Incidencias 0 Wiki
Rama: 23613-package-based-installation
Ramas Etiquetas
netbox
/
docs
/
installation
/
3-netbox.md

3-netbox.md 22 KB
Permalink Histórico Raw

Install NetBox

NetBox is published as a Python package on PyPI. This guide uses pip to install the NetBox application and its Python dependencies into a virtual environment. Configuration, uploaded media, custom scripts and reports, collected static files, and deployment configuration are kept outside the installed package.

This step does not configure PostgreSQL, Redis, a WSGI server, an HTTP server, or system services. These are covered by the other steps of the installation guide.

!!! info "Installing from source"

NetBox can also be run from a clone of its [Git repository](https://github.com/netbox-community/netbox) or from a release archive (tarball) downloaded from [GitHub](https://github.com/netbox-community/netbox/releases). These methods are intended for developers working on NetBox itself; see the [development guide](../development/getting-started.md) to set up a development environment. Existing deployments installed by these methods can be [migrated to the Python package](#migrate-an-existing-archive-or-git-installation).

Understand the Installation Layout

A package installation separates the application code from the files that belong to a particular NetBox instance.

Component Example Location Purpose
Application code <venv>/lib/pythonX.Y/site-packages/ Installed and replaced by pip; do not modify it directly
Python virtual environment /opt/netbox/venv/ Contains NetBox, its dependencies, and any plugins
Instance root /opt/netbox/ Holds local configuration and mutable instance data
Configuration /opt/netbox/conf/configuration.py Contains settings and credentials for this instance
Mutable data /opt/netbox/{media,reports,scripts,static}/ Persists independently of package upgrades
Deployment examples /opt/netbox/contrib/ Local copies to review and adapt before use

The instance root defaults to /opt/netbox and may be changed with the NETBOX_ROOT environment variable. The virtual environment does not need to be located below the instance root; /opt/netbox/venv is used throughout this guide only to keep the example straightforward.

!!! note "Custom instance roots"

The `--target` option for `netbox setup` selects where the local files are created. It does not permanently set the instance root. When using a location other than `/opt/netbox`, set `NETBOX_ROOT` for all NetBox commands and services.

Install System Packages

Begin by installing all system packages required by NetBox and its dependencies.

!!! warning "Python 3.12 or later required"

NetBox supports only Python 3.12 or later.

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

Before continuing, check that your installed Python version is at least 3.12:

python3 -V

Create the System User and Instance Root

Create the netbox system account and the default instance root:

sudo adduser --system --group netbox
sudo mkdir -p /opt/netbox
sudo chown root:netbox /opt/netbox
sudo chmod 755 /opt/netbox

Create the Virtual Environment

Create a Python virtual environment and update pip:

sudo python3 -m venv /opt/netbox/venv
sudo /opt/netbox/venv/bin/python -m pip install --upgrade pip

If the default python3 executable is older than Python 3.12, create the virtual environment with a supported interpreter instead (for example, sudo python3.12 -m venv /opt/netbox/venv).

Install the desired NetBox release. Replace X.Y.Z with the exact version to install. (Available releases are listed on PyPI.)

sudo /opt/netbox/venv/bin/python -m pip install "netbox==X.Y.Z"

Pinning the version makes the installed release explicit and prevents an unintended upgrade when the command is repeated later.

Scaffold the Instance Root

Run netbox setup to create the local configuration skeleton and copy the bundled deployment examples:

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

The command creates the following files when they do not already exist:

/opt/netbox/
├── conf/
│   ├── __init__.py
│   └── configuration.py
├── contrib/
│   ├── apache.conf
│   ├── gunicorn.py
│   ├── netbox-rq.service
│   ├── netbox.env
│   ├── netbox.service
│   ├── nginx.conf
│   └── uwsgi.ini
└── local_requirements.txt

netbox setup is intentionally non-destructive: existing files are left untouched. It does not install systemd units, configure an HTTP server, rewrite deployment examples for the local paths, or enable plugins.

Create the directories used for mutable instance data and grant the NetBox service account ownership of them:

sudo mkdir -p /opt/netbox/{media,reports,scripts,static}
sudo chown --recursive netbox:netbox \
    /opt/netbox/media \
    /opt/netbox/reports \
    /opt/netbox/scripts \
    /opt/netbox/static

Configure NetBox

Open the scaffolded configuration file with your preferred editor:

sudo ${EDITOR:-vi} /opt/netbox/conf/configuration.py

NetBox offers many configuration parameters, but only the following five are required for new installations:

  • ALLOWED_HOSTS
  • API_TOKEN_PEPPERS
  • DATABASES
  • REDIS
  • SECRET_KEY

ALLOWED_HOSTS

This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which NetBox may be accessed: It is merely for HTTP host header validation.)

ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']

If you are not yet sure what the domain name and/or IP address of the NetBox installation will be, you can set this to a wildcard (asterisk) to allow all host values:

ALLOWED_HOSTS = ['*']

API_TOKEN_PEPPERS

Define at least one random cryptographic pepper, identified by a numeric ID starting at 1. This will be used to generate SHA256 checksums for API tokens.

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

!!! tip

As with [`SECRET_KEY`](#secret_key) below, you can use the `netbox secret-key` command to generate a random pepper. Run it separately for each value so that the pepper and `SECRET_KEY` are independent:
```no-highlight
sudo /opt/netbox/venv/bin/netbox secret-key
```

DATABASES

This parameter holds the PostgreSQL database configuration details. The default database must be defined; additional databases may be defined as needed e.g. by plugins.

A username and password must be defined for the default database. If the service is running on a remote host, update the HOST and PORT parameters accordingly. See the configuration documentation for more detail on individual parameters.

DATABASES = {
    'default': {
        '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 (seconds)
    }
}

REDIS

Redis is an in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the configuration documentation for more detail on individual parameters.

Note that NetBox requires the specification of two separate Redis databases: tasks and caching. These may both be provided by the same Redis service, however each should have a unique numeric database ID.

REDIS = {
    'tasks': {
        'HOST': 'localhost',      # Redis server
        'PORT': 6379,             # Redis port
        'PASSWORD': '',           # Redis password (optional)
        'DATABASE': 0,            # Database ID
        'SSL': False,             # Use SSL (optional)
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,            # Unique ID for second database
        'SSL': False,
    }
}

SECRET_KEY

This parameter must be assigned a randomly-generated key employed as a salt for hashing and related cryptographic functions. (Note, however, that it is never directly used in the encryption of secret data.) This key must be unique to this installation and is recommended to be at least 50 characters long. It should not be shared outside the local system.

Generate a suitable key with the installed netbox secret-key command:

sudo /opt/netbox/venv/bin/netbox secret-key

!!! warning "SECRET_KEY values must match"

In the case of a highly available installation with multiple web servers, `SECRET_KEY` must be identical among all servers in order to maintain a persistent user session state.

Restrict Access to the Configuration

After saving the configuration, restrict access while allowing the NetBox service account to read it:

sudo chown --recursive root:netbox /opt/netbox/conf
sudo chmod 750 /opt/netbox/conf
sudo chmod 640 /opt/netbox/conf/configuration.py

!!! note "Environment-based configuration"

Ensure that any environment variables referenced by `configuration.py` are present when running `netbox upgrade`, `netbox createsuperuser`, and other management commands, and provide the same variables to both NetBox services. The copied `contrib/netbox.env` file is an example only and is not loaded automatically.

Install Optional Packages and Plugins

Package Extras

NetBox provides optional package extras for several common integrations. Each extra installs the additional Python libraries required by an integration:

Extra Installs Purpose
ldap django-auth-ldap LDAP authentication
saml2 python3-saml SAML single sign-on
remote-auth django-auth-ldap, python3-saml LDAP authentication and SAML single sign-on
s3 boto3 Amazon S3 remote data sources and file storage
git dulwich Git remote data sources
swift django-storage-swift OpenStack Swift file storage
sentry sentry-sdk Sentry error reporting

To install one or more extras, install NetBox again with the same pinned version, listing the extras in brackets. For example, to install the LDAP and Amazon S3 dependencies:

sudo /opt/netbox/venv/bin/python -m pip install "netbox[ldap,s3]==X.Y.Z"

Remember which extras are in use and specify them again when upgrading. For LDAP authentication, create ldap_config.py beside the active configuration file at /opt/netbox/conf/ldap_config.py when following the LDAP configuration guide. Give it the same ownership and permissions as configuration.py:

sudo chown root:netbox /opt/netbox/conf/ldap_config.py
sudo chmod 640 /opt/netbox/conf/ldap_config.py

Plugins and Other Python Packages

Plugins and any other local Python requirements must be installed into the same virtual environment as NetBox before running the installation or upgrade tasks. Add each package to /opt/netbox/local_requirements.txt, then install the file:

sudo ${EDITOR:-vi} /opt/netbox/local_requirements.txt
sudo /opt/netbox/venv/bin/python -m pip install \
    -r /opt/netbox/local_requirements.txt

Installing a plugin does not enable it. Add the plugin to the PLUGINS list in /opt/netbox/conf/configuration.py and complete any plugin-specific configuration separately.

Run the Installation Tasks

Run the netbox upgrade command to perform the application installation tasks:

sudo -u netbox /opt/netbox/venv/bin/netbox upgrade --no-input

The same command is used for both a fresh installation and future upgrades. It performs the following actions:

  • Applies database schema migrations
  • Traces any missing cable paths
  • Collects static files to be served by the HTTP server
  • Removes stale content types from the database
  • Rebuilds the search index
  • Clears expired user sessions from the database

For a custom instance root, pass NETBOX_ROOT explicitly. The virtual environment may remain elsewhere:

sudo -u netbox env NETBOX_ROOT=/srv/netbox \
    /opt/netbox-venv/bin/netbox upgrade --no-input

!!! note

To run the command on a node connected to a database in read-only mode, include the `--readonly` option. This skips all tasks that modify the database or filesystem.

Create a Superuser

NetBox does not come with any predefined user accounts. Create a superuser (administrative account) to be able to log into NetBox. Specifying an email address for the user is not required, but be sure to use a very strong password.

sudo -u netbox /opt/netbox/venv/bin/netbox createsuperuser

Test the Application

Start Django's development server temporarily to confirm that NetBox can load its configuration and connect to its dependencies:

sudo -u netbox /opt/netbox/venv/bin/netbox \
    runserver 0.0.0.0:8000 --insecure

If successful, you should see output similar to the following:

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.

Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8000; for example, http://127.0.0.1:8000/. You should be greeted with the NetBox home page. Try logging in using the username and password specified when creating a superuser.

!!! danger "Not for production use"

The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. **Do not use it in production.**

!!! warning

If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected.

Type Ctrl+c to stop the development server.

Adapt the Deployment Examples

The files copied to /opt/netbox/contrib/ reference a source-tree layout and are not rewritten for the package layout. Adapt them before following the Gunicorn, uWSGI, and HTTP server instructions.

For the default paths used in this guide, the following commands remove the source-tree references:

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

These changes have the following effect:

File Package Installation Change
netbox.service Imports netbox.wsgi from the virtual environment without a source-tree --pythonpath
netbox-rq.service Runs the RQ worker through the installed netbox command instead of manage.py
uwsgi.ini Uses the instance root rather than the absent /opt/netbox/netbox/ source directory
nginx.conf and apache.conf Serve collected static files from /opt/netbox/static/

Review every file before installing it. When using a different instance root or virtual environment, update all WorkingDirectory, ExecStart, chdir, virtual environment, and static-file paths accordingly. Also add the following line to the [Service] section of both systemd units, replacing the path as needed:

Environment=NETBOX_ROOT=/srv/netbox

When using environment-based configuration, reference an appropriate environment file from both systemd units or define the required variables directly in each unit.

Continue the Installation

With the deployment examples adapted, continue with either Gunicorn or uWSGI. Then configure an HTTP server and, if needed, LDAP authentication.

The following pages copy files from /opt/netbox/contrib/, so make the package-specific changes above before copying those files into their final locations.

Migrate an Existing Archive or Git Installation

!!! warning "Back up before migrating"

Migrating an existing deployment to the Python package changes its filesystem layout and upgrade procedure. Take a complete backup, document the current configuration, and verify a rollback procedure before proceeding.

Deployments installed from a release archive or Git checkout can be migrated to the Python package. This is not an in-place conversion: the procedure below builds a new package-based deployment alongside the existing one, which is retained until the new deployment has been validated.

Python package releases begin with NetBox v4.7. Before migrating an older deployment, first upgrade the existing archive or Git installation to a version that is available as a Python package.

Migrate the layout separately from a NetBox version upgrade. Install the same NetBox version that is currently running, validate the package-based deployment, and only then upgrade to a newer release.

The following example keeps the existing /opt/netbox installation in place during migration. It uses /srv/netbox as the new instance root and /opt/netbox-venv for the new virtual environment.

  1. Stop the existing NetBox services after completing a backup:

    sudo systemctl stop netbox netbox-rq

  2. Create the new virtual environment and install the same NetBox version as the existing deployment:

    sudo python3 -m venv /opt/netbox-venv
sudo /opt/netbox-venv/bin/python -m pip install --upgrade pip
sudo /opt/netbox-venv/bin/python -m pip install "netbox==X.Y.Z"

  3. Scaffold the new instance root and create its mutable directories:

    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

  4. Copy the active configuration from the existing installation. If local_requirements.txt exists, copy it over the empty file created by netbox setup:

    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

    When the existing deployment uses NETBOX_CONFIGURATION, copy the active configuration module instead, together with any sibling modules or local files it imports. Review the copied configuration and update any filesystem paths that still reference the old source tree.

    If LDAP is configured, also copy the active ldap_config.py to /srv/netbox/conf/ldap_config.py.

  5. Copy locally stored media, reports, and scripts. Do not copy collected static files; netbox upgrade will create them again.

    sudo cp -a /opt/netbox/netbox/media/. /srv/netbox/media/
sudo cp -a /opt/netbox/netbox/reports/. /srv/netbox/reports/
sudo cp -a /opt/netbox/netbox/scripts/. /srv/netbox/scripts/
sudo chown --recursive netbox:netbox \
    /srv/netbox/media \
    /srv/netbox/reports \
    /srv/netbox/scripts

    Use the paths configured by MEDIA_ROOT, REPORTS_ROOT, and SCRIPTS_ROOT instead when the existing deployment stores these files elsewhere.

  6. Install all plugins and local requirements into the new virtual environment before running the upgrade tasks:

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

    Repeat any package extras needed by the deployment, and verify that each plugin supports the installed NetBox version.

  7. Secure the configuration and run the package installation tasks against the existing database:

    sudo chown --recursive root:netbox /srv/netbox/conf
sudo chmod 750 /srv/netbox/conf
sudo chmod 640 /srv/netbox/conf/configuration.py

sudo -u netbox env NETBOX_ROOT=/srv/netbox \
    /opt/netbox-venv/bin/netbox upgrade --no-input

    If ldap_config.py was copied, also run sudo chmod 640 /srv/netbox/conf/ldap_config.py.

  8. Follow Adapt the Deployment Examples, substituting /srv/netbox and /opt/netbox-venv for the example paths. Install the updated systemd and HTTP server configuration, switch the services to the package deployment, and ensure that both systemd units define NETBOX_ROOT=/srv/netbox.

  9. Start the services, test the web interface and background processing, and retain the previous installation until the new deployment has been validated:

    sudo systemctl start netbox netbox-rq

After the migration is complete, use the standard upgrade procedure for future releases.