README.md

Ansible Role: Netbox

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

Contents

1. General Information
   1. Supported Platforms
2. Role variables
3. User accounts
   1. External Authentication
4. Plugins
   1. Removing Plugins
5. Version Locking
6. Dependencies
7. Example Playbook
8. Contributing

General Information

This role manages the installation and configuration of NetBox. This role 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.

Supported Platforms

Tested on the following platforms:

• Amazon Linux 2
• CentOS 8
• Debian Buster (up to v3.1.11)
• Debian Bullseye
• Rocky Linux 8 / Red Hat Enterprise Linux (RHEL) 8.2+
• Ubuntu 20.04

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

Supports NetBox versions 3+

Role variables

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.

User accounts

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

netbox_superusers:
  - username: admin
    password: admin
    email: changeme@example.com

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.

External Authentication

See the wiki for information about available external authentication methods.

Plugins

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

Removing Plugins

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.

Version locking

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

Dependencies

No Ansible dependencies. The application requires Redis and Postgres.

Example Playbook

See EXAMPLE for a complete playbook example.

Contributing

Contributions are encouraged. Please see CONTRIBUTING for details.