Ansible Role: Netbox

This role installs, configures, and maintains NetBox on popular Linux distributions.

Contents

• General Information
  • Supported Platforms
• Role Variables
• User Accounts
  • External Authentication
• Plugins
  • Removing Plugins
• Version Locking
• Dependencies
• Example Playbook
• Contributing

General Information

This Ansible role is for managing the installation and setup of NetBox. It does not install PostgreSQL or Redis, which are necessary for NetBox to work. Users should handle these services with their own roles and playbooks. For guidance on managing these services, refer to the EXAMPLE playbook.

New releases are issued when there are changes in NetBox. This role is regularly tested with new versions of NetBox. Check the GitHub repository for the latest compatibility details.

Supported Platforms

This role has been 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

Root access (through sudo) is needed to manage system dependencies for NetBox.

Works with NetBox versions >=3.5.9.

Role Variables

The minimum required variables if using PostgreSQL and Redis on localhost are as follows:

netbox_db_username: netbox
netbox_db_password: netbox
netbox_secret_key: "lnvRn_5Bypl8hBV4mMwgsMuHxr6uZvGwJyDqB7fcKqo"

If the netbox_secret_key is not provided, a new one will be automatically created during the playbook run.

For a full list of default settings and options, check defaults/main.yml.

Note: Starting from version 3.1, there are Dynamic Configuration Settings. These settings could block modifications through the user interface. By default, this role does not include these parameters unless netbox_override_dynamic_config is set to True. See defaults/main.yml#L82 for more information.

User Accounts

The following variables can define user creation during the initial setup:

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

Each user must have a username, password, and email. Users will only be created during the first installation. If netbox_superusers is not defined, no users will be created, and you can follow the manual user creation process outlined in the Netbox documentation here.

External Authentication

For details about outside authentication options, please refer to the wiki.

Plugins

You can install and configure NetBox plugins that are pip modules by setting the netbox_plugins variable. Here’s 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

Removing Plugins

To remove a plugin, set its state to absent in the netbox_plugins variable:

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

Note: You might need to remove database tables created by a plugin manually. This role does not manage database tables from plugins. See the documentation here for table management information.

Version Locking

You can set a specific version of NetBox with the following variable:

netbox_version_tag: v3.0.9

This should match the GitHub release tag name. It ensures that a specific version is maintained. If not set, the role will try to install the latest release each time.

Note: It's advisable to set a version tag in most environments to maintain a known installation.

You can also deploy from a specific branch or commit:

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

Dependencies

No extra Ansible dependencies needed. The application relies on Redis and PostgreSQL.

Example Playbook

For a complete example of a playbook, please check the EXAMPLE.

Contributing

Contributions are welcome! For details, see CONTRIBUTING.