Installs, configures and maintains NetBox on a variety of popular Linux distributions.

• Ansible Role: Netbox
  • Contents
  • General Information
    • Supported Platforms
  • Role variables
  • User accounts
    • External Authentication
  • Plugins
    • Removing Plugins
  • Version locking
  • Dependencies
  • Example Playbook
  • Contributing

This role manages the installation and configuration of NetBox. It does not provide PostgreSQL or Redis services that are required dependencies of the application. Those tasks are intentionally left to allow the user to manage those services within their own roles and playbooks. Please see the EXAMPLE playbook for details about how to manage those services.

Releases are only issued when necessary to support changes in NetBox. This role is continuously tested on new versions of NetBox. Please see the GitHub repo for the latest compatability information.

Tested on the following platforms:

• Amazon Linux 2
• CentOS 8
• Debian Bookworm
• Debian Bullseye
• Fedora Linux 37
• Rocky Linux 8 / Red Hat Enterprise Linux (RHEL) 8.2+
• Rocky Linux 9 / Red Hat Enterprise Linux (RHEL) 9.3+
• Ubuntu 20.04
• Ubuntu 22.04

This role will require root access (via sudo) to manage system dependencies and actions on behalf of netbox.

Supports NetBox versions >=3.5.9

Minimum required variables assuming localhost PostgreSQL and Redis services are available:

netbox_db_username: netbox
netbox_db_password: netbox
netbox_secret_key: "lnvRn_5Bypl8hBV4mMwgsMuHxr6uZvGwJyDqB7fcKqo"

If the netbox_secret_key is omitted a new one will be automatically generated on each playbook run.

See defaults/main.yml for a complete list of defaults and configurable options.

Note: Version 3.1+ introduced Dynamic Configuration Settings. These configuration options may still be written to configuration.py preventing modification via the UI. However, by default, this role always omits these parameters unless netbox_override_dynamic_config is set to True. See defaults/main.yml#L82 for details.

The following variables can be defined to create users during initial installation only:

netbox_superusers:
  - username: admin
    password: admin
    email: [email protected]

Each user requires a username, password and email address defined. The role will attempt to create the defined users only once during initial installation. If netbox_superusers is not defined, no users are created and the manual user creation process documented by Netbox can be used instead.

See the wiki for information about available external authentication methods.

Netbox plugins that are pip modules can be installed and configured by setting the netbox_plugins list variable. Below is an example for the Netbox BGP plugin.

netbox_plugins:
  - name: netbox_bgp    # Plugin name
    pip: netbox-bgp     # Pip module name
    config:             # Plugin configuration
      device_ext_page: left
      asdot: True

To remove a plugin, an absent state can be assigned to the netbox_plugins entry:

netbox_plugins:
  - name: netbox_bgp    # Plugin name
    pip: netbox-bgp     # Pip module name
    state: absent

Note that it may be necessary to remove database tables that were installed as part of a plugin. This role does not manage database tables that may have been created as part of a plugin. Please see the documentation for more information on table management.

A specific version of netbox can be configured using the variable:

netbox_version_tag: v3.0.9

This tag should match the Github tag name for the release to be installed. It will ensure that a specific target is maintained. If not set, each run will attempt to find the latest release version to install.

NOTE: A version tag should be set for most environments to ensure a known installation is maintained.

Another option is to deploy from a specifc branch and optionally a specific commit SHA

netbox_install_method: git
netbox_git_branch: master
netbox_git_sha: 8f1acb700d72467ffe7ae5c8502422a1eac0693d # optional

No Ansible dependencies. The application requires Redis and Postgres.

See EXAMPLE for a complete playbook example.

Contributions are encouraged. Please see CONTRIBUTING for details.