Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

netbox

Installs and configures Netbox and optionally its dependencies, lik PostgreSQL and redis
Project URLRSS FeedReport issues

6,930 downloads

1,831 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.2.0 (latest)
  • 2.1.0
  • 2.0.1
  • 2.0.0
  • 1.1.1
  • 1.1.0
  • 1.0.1
  • 1.0.0
  • 0.2.1
  • 0.2.0
  • 0.1.0
released Mar 25th 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 7.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'ash-netbox', '0.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add ash-netbox
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install ash-netbox --version 0.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

ash/netbox — version 0.1.0 Mar 25th 2020

netbox

Table of Contents

  1. Description
  2. Setup - The basics of getting started with netbox
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.
  5. Development - Guide for contributing to the module

Description

Puppet module for installing and configuring Netbox, an IPAM (IP Adress Management) tool initially conceived by the network engineering team at DigitalOcean. The documentation for Netbox can be found here

Setup

What netbox affects

This module installs and configures Netbox. Netbox needs PostgreSQL and Redis to work, and this module can optionally handle that too. Netbox is a Python web applications built on the Django framework and uses the Gunicorn webserver. Usually you place a webserver (like Nginx og Apache) in front of it. This is not part of this module, but a configuration using Apache is provided. Everything in this module is made according to the Netbox documentation. As such, if something is not properly explained here, you can probably find answers to your questions there.

Setup Requirements

You need to have epel configured. The easiest way to do that is by running:

yum install -y epel-release

This module has been tested with Apache HTTPD using the puppetlabs-apache module. There are a couple of gotchas, see example with Apache on Centos/RHEL8.

Beginning with Netbox

Add dependency modules to your puppet environment:

  • camptocamp/systemd
  • puppet/archive
  • puppetlabs/inifile
  • puppetlabs/stdlib

If you are going to use this module to install PostgreSQL and Redis, then you need these as well:

  • puppetlabs/postgresql
  • puppetlabs/concat
  • puppet/redis

If you are following along the Apache example you also need to handle Selinux:

  • puppet/selinux

Usage

In its simplest configuration, the module needs only one parameter set. This is the secret_key. This is something Netbox will not run without, and is recomended to be an at least 50 character long string of letters, symbols and numbers. This is to be treated as a secret.

By default, PostgreSQL and Redis is set up as part of the installation. If you have your own PostgreSQL or Redis installation you want to use, you simply set $handle_database and $handle_redis to false. Some configuration is offered, but if you need to tweek any of those two softwares, I would recommend handling them outside of this module.

The following code shows an example where you have a profile::netbox (because of course you are using the "roles and profiles" design pattern) which takes in the secret key. This could for example be stored in Hiera eyaml.

class profile::netbox (
  String $netbox_secret_key,
) {

  class { 'netbox':
    secret_key    => $netbox_secret_key,
  }
}

You also need to set up a django superuser manually after installing. This is the admin account to your Netbox application. To do this, use the virtual Python environment created by the installation and the manage.py command:

# cd /opt/netbox
# source venv/bin/activate
(venv) # cd netbox
(venv) # python3 manage.py createsuperuser
Username: admin
Email address: admin@example.com
Password:
Password (again):
Superuser created successfully.

If you have installed Netbox in an non-default location, then you have adapt the above description accordingly.

A more interesting example

You probably want to adjust your parameters a little more than the minimal example. Here is a more realistic one:


  class { 'netbox':
    secret_key        => $netbox_secret_key,
    allowed_hosts     => [$trusted[certname], 'localhost'],
    banner_top        => 'TOP BANNER TEXT',
    banner_login      => 'WELCOME TO THE NETBOX LOGIN',
    banner_bottom     => 'BOTTOM BANNER TEXT',
    database_password => $netbox_database_password,
    $email_from_email => "netbox@${trusted[domain]},
  }

The $netbox_database_password is expected to be defined in wherever you include the Netbox module from. Should probably be stored in Hiera Eyaml.

Example with Apache on Centos/RHEL8

Here is a full working example with a Netbox profile which includes Netbox module and Apache with settings as recommended in the Netbox documentation. Note that for this setup to work you need:

  • The boolean httpd_can_network_connect set to true:
    • Done in the example, requires the puppet/selinux module
  • The apache user must be part of the netboxgroup:
    • usermod apache -G netbox 

# Netbox
#
# Profile for running Netbox through the ahs/netbox-module
#
class profile::netbox (
  String $netbox_secret_key,
) {

selinux::boolean { 'httpd_can_network_connect': }
# usermod apache -G netbox

  class { 'netbox':
    secret_key    => $netbox_secret_key,
    allowed_hosts => [$trusted[certname]],
    banner_top    =>  'TOP BANNER TEXT',
    banner_bottom =>  'BOTTOM BANNER TEXT',
  }
  class { 'apache':
    default_vhost => false,
  }

  class { 'apache::mod::wsgi':
    mod_path     => '/usr/lib64/httpd/modules/mod_wsgi_python3.so',
    package_name => 'python3-mod_wsgi',
  }

  apache::vhost { $trusted[certname]:
    servername              => $trusted[certname],
    port                    => '80',
    proxy_preserve_host     => true,
    docroot                 => '/opt/netbox/netbox/',
    request_headers         => [
      'set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}',
    ],
    proxy_pass              => [
      { path        => '/',
        url         => 'http://127.0.0.1:8001/',
        reverse_url => 'http://127.0.0.1:8001/'
      },
    ],
    aliases                 => [
      { alias => '/static',
        path  => '/opt/netbox/netbox/static',
      },
    ],
    wsgi_pass_authorization => 'On',
    directories             => [
    { path            => '/opt/netbox/netbox/static',
      provider        => 'directory',
      custom_fragment => 'Options Indexes FollowSymLinks MultiViews'
    },
    { path            => '/static',
      provider        => 'location',
      custom_fragment => 'ProxyPass !'
    },
  ],
  }
}

Limitations

This module is only tested on RHEL/Centos8 at the moment, and will not work for Ubuntu family or older versions of EL just yet.

There are several optional integrations and configuration options found in the Netbox documentation that is not supported by this module yet. Including but not limited to:

  • Napalm
  • Remote File Storage
  • LDAP Authentication

Development

I would be more than happy if you wanted to improve this module. Use the Github issue tracker to submit issues og fork it and issue Pull Requests.