Truth Teller

As networks grow and increase in complexity, it becomes more and more difficult to document all of the devices that you manage and their relationships. In the worst of cases, knowledge of the network may be scrawled on a series of spreadsheets or hand-drawn sketches – or maybe even stored inside the heads of a few overworked IT staffers. A number of free and proprietary solutions provide a means for visualizing and documenting the network, often combined with additional management features. Many of these tools are useful, but some may be missing a critical feature that you need or, on the other end of the spectrum, might suffer from feature bloat. Others will lock you into a specific management or monitoring environment. With all of this in mind, it would be nice to use a software package with a solid base plus add-ons, allowing you to build out the best environment for documenting your specific network.

If you're looking for a versatile solution that embraces complexity while still "keeping it simple," you might be interested in NetBox [1]. NetBox claims to be "the premiere network source of truth." It lets you model and document networks by combining traditional Data Center Infrastructure Management (DCIM) and IP Address Management (IPAM) with extensions and APIs. You can check out an always-running NetBox demo [2] if you want to try it out before taking the plunge and investing your organization's resources.

Information Hub

NetBox serves as a hub of information about your network (Figure 1). At my organization, NetBox has become much more than simply a way to manage IP addresses. Thanks to NetBox's flexibility, you can add notes (using Markdown), add product images (as well as images of the product's location), and much more. If you need to document which device is which in a rack, where that rack is located, and what it looks like, just take a photo of that specific device and upload it with your phone right then and there. Voila, everyone with NetBox access can see the exact machine in its exact location. If all of your devices are the same model and were bought at the same time, installed in the same place, and nicely and neatly aligned in endless rows of racks that go on for miles and miles, this might not be a big deal. For me, dealing with racks, offices, classrooms, libraries, boiler rooms, hallways, etc., and years upon years of undocumented changes, this ability is very useful. If I am uncertain which machine I need to work on once I get to a room or office, a quick glance at NetBox tells me without requiring me to power anything up, look for an asset tag, or see which port on a switch the device is plugged into. No need to search for product information either, because it's right there, along with links to the drivers.

Figure 1: The NetBox overview landing page provides information about your network in one place.

Speaking of racks, NetBox lets you populate racks with your devices regardless of type and builds the rack view in the web GUI. NetBox uses your provided images of the device type's front and back to populate the front and back elevation views of the rack, which I found extremely handy. Looking for a specific device isn't always as simple as looking for, say, the fifth 4U chassis from the bottom. Instead, I may be looking for a domain controller somewhere in between two NASs, three switches, and a workstation on a shelf on its side with none of the asset tags or stickers remaining. These elevation views, as well as the way that these racks are created, is a very powerful feature, even without considering all of the rest of what the software can do.

NetBox's nicest feature, in my opinion, is that it contains whatever information you choose to include, all in one place and extremely easy to find. For instance, a search for "245" gives me every room with "245" in the name, each device with those digits in its identifiers or comments, and anything with that model number. My mantra for software like this is that I ought to be able to find what I am looking for within three steps. For instance, I can type "245" and find the room, click on it to see the device in that room, and click on that to get not only the IP address but also links to the owner's manual, installation guide, generic and specific images of that device, which port on that device connects to its corresponding port on which switch, how much power it requires, and so on.

With that in mind, NetBox is certainly an example of you get out what you put into it. However, I can tell you that a well-executed NetBox installation can quickly become the one-stop shop that your employees go to when they receive a work order or need to know about a specific machine or device type. A rich set of APIs means that NetBox can be extended to serve as an information source for automated provisioning and management tools.

NetBox can even serve as a backup to your inventory management. Because new devices can be added easily by importing CSV files, big projects are also easy to incorporate into NetBox. Personally, I'll wait until new items are inventoried into the inventory management software and then pull a report of newly added items, format it as needed for NetBox, upload, and then add IPs (Figure 2). The entire process takes perhaps 15 minutes from start to finish to add what is basically an unlimited number of devices of one device type, if you know the IPs and locations where they will be installed.

Figure 2: Managing virtual machines in NetBox.

I have also found advantages to using NetBox that I didn't expect or even imagine. My team recently needed to answer approximately a half zillion questions pertaining to our fleet as a cybersecurity exercise. NetBox put the answer to nearly all of those questions at our fingertips – no guessing and no estimates. How many desktops are in the high school library? Three steps needed to find out. Where is our domain controller located? Three steps. How many endpoints do we have that are no longer supported by a manufacturer's warranty? Click, click, click. NetBox has been a godsend in terms of information management. NetBox doesn't require someone to have intimate knowledge of the systems or even be in the IT department. Searching and navigating NetBox is intuitive and simple for all levels of users.

Installation

While you can find the commands for installing NetBox in the NetBox documentation, I will walk you through them here and add some of the caveats, quirks, and counsel that I pieced together when deploying and configuring my particular installation.

I am running NetBox on a bare metal Ubuntu install [3] with a single solid-state drive (SSD) with the database being backed up daily to a network server using a cron job and a script lifted from the Level1Techs forum [4]. In addition, I recommend having at a minimum a backup machine on-site and another off-site, or, better yet, a virtual machine (VM) running in the cloud for failover (setting up these backups is outside the scope of this article). I'll assume that you have one machine to install NetBox and another for a backup (based on your organization's typical operating procedures and standards).

PostgreSQL

First, you need to install PostgreSQL [5] with the following commands:

$ sudo apt update
$ sudo apt install -y postgresql
$ psql -V
$ sudo -u

The third command above verifies that you have at least version 11 of PostgreSQL installed. Once you are in the PostgreSQL shell (the last command), run the following commands:

$ CREATE DATABASE netbox;
$ CREATE USER netbox WITH PASSWORD 'PutYourSuperSecurePasswordHereDONTCOPYPASTETHIS';
$ ALTER DATABASE netbox OWNER TO netbox;

To leave the PostgreSQL shell, enter:

$ \q

To double-check that the installation was successful, enter:

$ psql --username netbox --password --host localhost netbox

You will then enter your SuperSecurePassword for the NetBox user password. Please do not use SuperSecurePassword for your password; it is neither super nor secure. Follow your own organization's guidelines keeping in mind that, if implemented to its fullest extent, NetBox may well be the keys to your kingdom.

Once you enter your password, you should see the following output:

psql (14.8 (Ubuntu 14.8-0ubuntu0.22.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

Now complete a connection info check with:

netbox=> \conninfo

Success: You are connected to database netbox as user netbox on host localhost (address 127.0.0.1) at port 5432 with the SSL connection described above. You can now quit by entering:

netbox=> \q

Redis

Your next installation step is to install Redis [6] using:

$ sudo apt install -y redis-server

You need to verify that you are now running at least version 4.0 of Redis with:

$ redis-server -v

The output you see should be something like this:

Redis server v=6.0.16 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=a3fdef44459b3ad6

Lastly, you need to verify that the Redis service is working properly. Enter the following command:

$ redis-cli ping

which should result in PONG as the response.

NetBox and Dependencies

You will need to also install the NetBox dependencies (as shown in Figure 3) using:

$ sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential libxml2-devlibxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev git

Figure 3: You can install the NetBox dependencies using Cockpit's terminal.

Double-check that you have at least version 3.8 of Python [7] installed by running:

$ python3 -V

Now you need to create the installation directory and cd (change directory) into it and download NetBox with:

$ cd ~
$ sudo mkdir -p /opt/netbox/
$ cd /opt/netbox/
$ sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .

Note: The period (.) at the end of the last command is required for the command to work properly.

Next you need to create the NetBox user and change ownership of the installation directory to that user with:

$ sudo adduser --system --group netbox
$ sudo chown --recursive netbox /opt/netbox/netbox/media/

Configuration

If you read the NetBox documentation, you will notice that my configuration instructions vary somewhat from the documentation. The documentation does mention doing what I recommend, but it doesn't make it obvious, so I will try to make these steps a bit easier to understand.

First, I'll edit the NetBox configuration file using Cockpit [8] on Ubuntu Server (see the "Config Editors" box) as follows:

$ cd /opt/netbox/netbox/netbox/
$ sudo cp configuration_example.py configuration.py
$ sudo nano configuration.py

If you are also installing this on Ubuntu Desktop, use:

$ sudo gedit configuration.py

For versions of Ubuntu newer than 20.04, use:

$ sudo gnome-text-editor configuration.py

You will then be able to edit the file directly in a text editor. This might be easier if you are less familiar with using Vim or nano from the terminal.

You will need to modify four keys in the config file (Figure 4). First, you will change the ALLOWED_HOSTS parameter:

ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']

Figure 4: You can edit configuration.py with Navigator from 45Drives in Cockpit to set up NetBox if you prefer a graphical editor.

If you unsure about what to enter here, use your server's IP address, which you can get by typing $ ip address into the terminal. You can also type $ hostname into the terminal and put your server's hostname here as well, or you can use both if that makes sense. My installation has four entries here, separated by commas. You will enter this in a web browser later to get to the NetBox web GUI.

Warning: Do not type this in the example ALLOWED_HOSTS comment directly above the ALLOWED_HOSTS parameter. If you get a 400 bad request error, I suggest checking the ALLOWED_HOSTS comment to see if you accidentally entered your IP address or hostname there.

Next you need to modify the database parameters as shown in Listing 1.

01 DATABASE = {
02   'ENGINE': 'django.db.backends.postgresql', # Database engine
03   'NAME': 'netbox',                          # Database name
04   'USER': 'netbox',                          # PostgreSQL username
05   'PASSWORD': 'SuperSecurePassword',         # PostgreSQL password
06   'HOST': 'localhost',                       # Database server
07   'PORT': '',                                # Database port (leave blank for default)
08   'CONN_MAX_AGE': 300,                       # Max database connection age (seconds)
09 }

You then need to modify the Redis parameters as shown in Listing 2.

01 REDIS = {
02   'tasks': {
03     'HOST': 'localhost',  # Redis server
04     'PORT': 6379,         # Redis port
05     'PASSWORD': '',       # Redis password (optional)
06     'DATABASE': 0,        # Database ID
07     'SSL': False,         # Use SSL (optional)
08   },
09   'caching': {
10     'HOST': 'localhost',
11     'PORT': 6379,
12     'PASSWORD': '',
13     'DATABASE': 1,        # Unique ID for second database
14     'SSL': False,
15   }
16 }

Finally, you will need to modify the secret key parameter. First, you need to generate your secret key with:

$ python3 /opt/netbox/netbox/generate_secret_key.py

Copy and paste the generated key into the SECRET_KEY parameter space below the REDIS parameter. You will use this key if you decide to set up a second NetBox server for backup, so jot it down for future reference. If you forget to do this, you can always get back into configuration.py to retrieve the secret key if needed later.

Now you need to create and edit the local_requirements.txt file with:

$ cd /opt/netbox/
$ sudo nano local_requirements.txt

If you intend to use a remote database as mentioned in the online documentation, you will want to enter django-storages [12] here. What is not clear in the documentation is that you also need to enter any other plugins that you intend to use in the local_requirements.txt file in /opt/netbox. (For a list of NetBox plugins, see the NetBox Community Plugins GitHub page [13].) In addition, the plugins need to be listed in the previously modified configuration.py file in /opt/netbox/netbox/netbox.

In local_requirements.txt, simply enter each desired plugin (Figure 5), one per line, as follows:

django-storages
netbox-topology-views
netbox-inventory
netbox-qrcode

Figure 5: Entering plugins to local_requirements.txt with nano.

In local_requirements.txt, note that the plugins use dashes (-). When you edit the configuration.py file, you will change some of the dashes to underscores (_). I found this super frustrating and inconsistent because it is not always dashes in one place and underscores in the another, but it is often different between the two. (If you build plugins for NetBox and can avoid this, please consider making your plugin names one word to avoid this issue.)

Now that you have edited and saved the local_requirements.txt file to include your desired plugins, you also need to enable them by once again modifying the configuration.py file. You can open configuration.py with:

$ cd /opt/netbox/netbox/netbox/
$ sudo nano configuration.py

Look for the PLUGINS parameter and, depending on the plugin, you may also need to change PLUGINS_CONFIG as well. Based on the plugins I added to my local_requirements.txt file, my PLUGINS section should look like this:

PLUGINS = [
  'netbox_inventory',
  'netbox_qrcode',
  'netbox_topology_views'
]

I will use a configuration that is similar to the default suggested plugin configuration as shown in Listing 3.

01 PLUGINS_CONFIG = {
02   "netbox_inventory": {},
03   "netbox-qrcode": {
04     'with_text': True,
05     'text_fields': ['name', 'serial'],
06     'font': 'ArialMT',
07     'text_location': 'up',
08     'qr_version': 1,
09     'qr_error_correction': 0,
10     'qr_box_size': 4,
11     'qr_border': 4,
12     'cable': None,
13     'rack': {
14     'device': {
15       'qr_box_size': 6,
16       'custom_text': None,
17     }
18     }
19   },
20   "netbox_topology_views": {
21     'static_image_directory': 'netbox_topology_views/img',
22     'allow_coordinates_saving': True,
23     'always_save_coordinates': True
24   }
25 }

I tend to switch things up between using nano in the terminal and using Navigator from 45Drives to modify files, but you can also use gedit [14] (or Gnome Text Editor [15]) if using Ubuntu Desktop to modify the configuration.py file and to create and populate the local_requirements.txt file. I prefer troubleshooting configs with a graphical editor to remembering the quit and save commands in a terminal text editor. It is all the same to NetBox in the end, so use whichever is easiest for you.

I strongly recommend setting the allow_coordinates_saving and always_save_coordinates to False because they ended up causing me quite a bit of grief. It appears that what happens is that they will set a custom field for each device. The problem with that is that you will actually need to create that custom field, and failure to do so will stop you from being able to edit the devices in any way after using the topology view. In short, I would set those parameters to false and read the plugin page carefully. If you get errors when trying to make changes to your devices after using the topology view plugin, create a custom field called Coordinates that is data type text and is hidden. Then follow the instructions on the plugin page to do the needed conversion. After that you will again be able to edit devices without getting an error message each time.

Having said that, the topology views plugin looks downright awesome, and I highly recommend it for creating topology maps. Just be aware that this error could occur and that there is a fix, even if it is a bit convoluted. I was able to tweet at the NetBox team, and the wonderful folks there helped me to find the GitHub issue on the plugin page that I needed to get it all sorted out. (Unfortunately, prior to that, I had given up the night before and tried recreating all of my devices – only to find myself in the same exact situation after looking at the topology view. Luckily for me, it wasn't too many devices and it was a great learning experience.)

With the plugins sorted, you are ready to run upgrade.sh to install the plugins:

$ sudo /opt/netbox/upgrade.sh

Note, the syntax needs to be exact for the configuration.py file. I have found that even copying and pasting often results in errors. If you make an error, carefully read the output from the terminal and then go back and edit the configuration.py file until you get it right. The terminal output will tell you which line the issue is on and give a best guess as to the source of the problem. Remember, you can always add plugins and their configurations later by putting them into local_requirements.txt and configuration.py and running the upgrade.sh command in the future. I ended up using the configuration above, but that was not without some frustration. Bear in mind that the sample configurations in the NetBox documentation are just that and might need to have something added, removed, or otherwise changed in order to work properly.

NetBox now will tell you to restart the NetBox services (Figure 6). If you restart at this time, you will get the failure to restart message shown in Listing 4. You get the failure message because you have not yet created those services.

$ sudo systemctl restart netbox netbox-rq
Failed to restart netbox.service: Unit netbox.service not found.
Failed to restart netbox-rq.service: Unit netbox-rq.service not found.

Figure 6: This is what you should see at the end of a successful upgrade.sh run during the initial installation.

If you decide for whatever reason that you no longer want a plugin, then you can simply remove it from both files. If you are unsure, or if you would like to temporarily disable a plugin for some reason, then you can do so by removing it from configuration.py but leaving it in local_requirements.txt. In order to enable or disable a plugin, you will need to restart the NetBox service, which I will explain shortly.

You now need to create the NetBox superuser by entering:

$ source /opt/netbox/venv/bin/activate

The (venv) added to the command prompt is normal. Now, add the superuser:

(venv) $ cd /opt/netbox/netbox
(venv) $ python3 manage.py createsuperuser

You can use a deactivate command to leave the virtual environment and get back to a normal terminal window, but I usually found myself closing and opening a new terminal (or rather refreshing the page because I was connected using Cockpit).

With the superuser added, you will want to add the housekeeping script as a cron job to occasionally do some cleanup. To do this, add a link to the script in the cron.daily folder as follows:

$ sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

At this point, you should have a running NetBox instance that you can connect to by entering the IP address or hostname that you defined earlier in configuration.py. You will need to have the Uncomplicated Firewall (UFW), which might require running:

$ sudo ufw allow 9090
$ sudo ufw allow OpenSSH
$ sudo ufw allow https
$ sudo ufw allow http
$ sudo ufw enable
$ sudo ufw status

I added ports 9090 and 22 because I was using Cockpit and also wanted the ability to connect to this server using SSH, but that is beyond the scope of this article. If you don't know how to SSH into a server or haven't installed and used Cockpit or a similar server admin web GUI such as Webmin, I suggest you do those things first, because it will help to familiarize you with running servers without a GUI from the terminal. You can connect to your machine with SSH or Cockpit even if you are running the desktop version of Ubuntu.

Creating Services

You will now want to copy the default Gunicorn [16] configuration and create the services to turn NetBox on and off using the code in Listing 5.

01 $ sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
02 $ sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
03 $ sudo systemctl daemon-reload
04 $ sudo systemctl start netbox netbox-rq
05 $ sudo systemctl enable netbox netbox-rq
06 $ systemctl status netbox.service

The code in Listing 5 copies the default Gunicorn config file and then creates the NetBox system service, starts it, enables it to run each time the system starts up, and checks to make sure that it is running properly and enabled to run on startup. After you complete this step, if you run the upgrade.sh command and it prompts you to restart the NetBox services, you now will be successful.

Web Server Setup

To set up the web server, you will want to create an SSL certificate to allow HTTPS encrypted traffic (Figure 7):

$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/netbox.key -out /etc/ssl/certs/netbox.crt

Figure 7: Making a self-signed SSL certificate for HTTPS in NGINX.

This certificate is self-signed, which is fine for our purposes here. For production use, you most likely will not want to use a self-signed certificate.

Next, you will be prompted for some optional details that you might want to include in the certificate. I suggest making a little game out of it to see if anyone actually reads your certificate details!

Now you will install the NGINX web server [17]:

$ sudo apt install -y nginx

The next step is critical: You must add your hostname and IP address from earlier to the server's configuration file:

$ sudo nano /opt/netbox/contrib/nginx.conf

Change netbox.example.com to the hostname or IP address that you entered previously in configuration.py. Note that you can have more than one entry here, such as the installation's IP address and hostname. Simply separate them with a space. You can use the $ ip address and $ hostname commands in the terminal to find out this information if you've forgotten.

Now you will copy the NetBox HTTPS config file to the NGINX directory, delete the default enabled site, replace it with a link to this one, and restart the HTTPS service by entering the commands in Listing 6 in order.

01 $ sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
02 $ sudo rm /etc/nginx/sites-enabled/default
03 $ sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
04 $ sudo systemctl restart nginx

If you make any future changes to the config file, you need to recopy that file to the sites-available directory using the command in line 1 of Listing 6 and then by restarting NGINX using line 4. Failure to do so will result in your configuration not actually changing.

(There is an optional LDAP service installation section in the online NetBox documentation as well, but that is beyond the scope of this article.)

You should now be up and running (Figure 8). You can access your NetBox installation by going to your web browser and entering the hostname or IP address that you used in the NGINX configuration file and in configuration.py in the addressbar. You will log in with the username and password that you previously created. Upon login, I suggest creating a new user for yourself and whoever else needs access to NetBox.

Figure 8: If you made it here, congratulate yourself!

When you connect to your new NetBox instance using this SSL certificate, you will get a warning about connecting to an insecure server (Figure 9). For my installation that isn't a concern, but it might be for you. If that is the case, you can look into a certificate that is not self-signed. It is probably safe in this case to ignore that warning altogether for the purposes of this article.

Figure 9: When you first connect to your NetBox installation you may get a privacy warning if you use a self-signed SSL certificate.

Assigning User Rights

You can give users rights to view only or to edit. These rights are based on each individual subsection of each aspect of the network. This is quite granular, which is fantastic but also a bit confusing. I strongly suggest using groups smartly – think first about the best way to set permissions for your organization.

There is also an add-on for single sign-on (SSO), which might make sense for your installation. You may want one person to add all of the new devices and another person to add IP addresses to those devices. In that case, you would give the first person access to change device types and devices, but only to view IP addresses, and vice versa.

Some users may not need to see a particular section, so you can simply not give them that access. This is also useful if you have users from different sites or locations all connecting to your NetBox instance. In this instance, users may have the ability to only change items within their location or site as needed.

Permissions are a big deal and need to be well thought out. Remember, these are the keys to the kingdom. Even if that isn't really the case for your organization, it is probably a safe approach to NetBox.

Conclusion

When I first started reading about NetBox, I found their aim of being "the premiere network source of truth" kind of cheesy. It's just a web GUI for a network map with some stuff from a database after all. Since installing and using it, however, I'm a true believer. I think every single network should be mapped-out using NetBox. I have installed the community edition at work as well as on my home network. It really is your network's "truth" – or at least it becomes that once you put in the work.

I am still in the process of documenting the network in my organization. It is an enormous task and one that never ends, because updates will need to be made as the network expands, contracts, and changes. My intent is to build NetBox out thoroughly enough that I can give a new employee a login to NetBox so they can find their way around the entire organization, even if they aren't able to access everything that they see in there. I also needed to add maps for each building in the NetBox's location section, which I could do by simply uploading PNG images of our physical maps. I might not give a new employee the credentials for our building's switches, but they will know where the switches are located, what devices connect to them and through which ports, and the IP addresses those devices have, as well as be able to very quickly and easily find product information. NetBox will give new employees all that they need to know about the devices that they will work on to be able to effectively and efficiently do their jobs. With dozens of printers and hundreds of PCs on our network, the ability to pinpoint one device and its connection to a specific switch by searching for a room or a building, and to have a link to the user's guide and installation manual, drivers download page, specifications, asset tag number and corresponding serial number, and so on, will greatly improve team efficiency in the long run, though it will absolutely take time to implement. None of that time is wasted, however, because anyone who is mapping out the network in NetBox is also learning all of the ins and outs of it simultaneously.

Something incredibly important that I didn't focus on in this article: Knowing what is on your network and where that gear is located is critical to network security and is connected directly to CIS Safeguards numbers 1.1, 1.2, 3.2, 4.6, and many others in the CIS Risk Assessment Methodology (RAM)[18].

Initially, I found a ton of overlap between tools that we were already using and NetBox. However, as I added more devices to the database and put in more details about each device, I realized that I had been looking at it all wrong. While alternatives exist to basically all of NetBox's functions, the disconnect between the individual programs and services creates inefficiency. NetBox offers a fantastic opportunity for long-term improvement in network management. NetBox, if well-implemented, will act as a central knowledge hub for your network, with each of those other programs and services functioning as spokes off of that hub. NetBox doesn't lay over the top of your existing management stack, but instead coalesces with it in a way that empowers your IT team. While NetBox may initially look like a lot of work, you will wonder what you ever did without it once you get it up and running.

The Author

Adam Dix, a former teacher and product line manager, is a mechanical engineer and Linux enthusiast working as a LAN technician. You can check out some of his related work at EdUBudgie Linux (https://www.edubudgie.com).