NetBox Configuration

Configuration File

NetBox's configuration file contains all the important parameters which control how NetBox functions: database settings, security controls, user preferences, and so on. While the default configuration suffices out of the box for most use cases, there are a few required parameters which must be defined during installation.

The configuration file is loaded from $INSTALL_ROOT/netbox/netbox/configuration.py by default. An example configuration is provided at configuration_example.py, which you may copy to use as your default config. Note that a configuration file must be defined; NetBox will not run without one.

!!! note "Python package installations (experimental)" An experimental Python package installation loads $NETBOX_ROOT/conf/configuration.py by default. NETBOX_ROOT defaults to /opt/netbox. Use netbox setup --target <path> to scaffold the local configuration, and keep configuration and mutable instance data outside the virtual environment and installed package. The setup target is not persisted; set NETBOX_ROOT for all commands and services when using a non-default path.

!!! info "Customizing the Configuration Module" A custom configuration module may be specified by setting the NETBOX_CONFIGURATION environment variable. This must be a dotted path to the desired Python module. For example, a file named my_config.py in the same directory as settings.py would be referenced as netbox.my_config.

To keep things simple, the NetBox documentation refers to the configuration file simply as `configuration.py`.

Some configuration parameters may alternatively be defined either in configuration.py or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI.

Dynamic Configuration Parameters

Some configuration parameters are primarily controlled via NetBox's admin interface (under Admin > System > Configuration History). These are noted where applicable in the documentation. These settings may also be overridden in configuration.py to prevent them from being modified via the UI. A complete list of supported parameters is provided below:

• ALLOWED_URL_SCHEMES
• BANNER_BOTTOM
• BANNER_LOGIN
• BANNER_TOP
• CHANGELOG_RETAIN_CREATE_LAST_UPDATE
• CHANGELOG_RETENTION
• CUSTOM_VALIDATORS
• DEFAULT_USER_PREFERENCES
• ENFORCE_GLOBAL_UNIQUE
• GRAPHQL_ENABLED
• JOB_RETENTION
• MAINTENANCE_MODE
• MAPS_URL
• MAX_PAGE_SIZE
• PAGINATE_COUNT
• POWERFEED_DEFAULT_AMPERAGE
• POWERFEED_DEFAULT_MAX_UTILIZATION
• POWERFEED_DEFAULT_VOLTAGE
• PREFER_IPV4
• PROTECTION_RULES
• RACK_ELEVATION_DEFAULT_UNIT_HEIGHT
• RACK_ELEVATION_DEFAULT_UNIT_WIDTH

Modifying the Configuration

The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before these changes will take effect:

$ sudo systemctl restart netbox

Dynamic configuration parameters (those which can be modified via the UI) take effect immediately.