NetBox is one of the best IP Address Management (IPAM) and data center infrastructure management (DCIM) tools available. It is an open source web-based application that will only cost you the time and resources to set up an internal server. However, while there is step-by-step upgrade documentation available, it can be ambiguous at times and also misses some important steps resulting in errors and service start failures (e.g., "Service Not Found" errors). The following guide will help you to make sure your upgrades are successful and will provide tips on how to troubleshoot problems that may arise.

Although NetBox can run on CentOS, we highly recommend Ubuntu since the CentOS Project is sadly transitioning away from their traditional solid Linux distro to their new CentOS Stream distro which tracks ahead of Red Hat Enterprise Linux (RHEL) development. Therefore, the steps in this guide will be tailored toward Ubuntu Server. However, the ideas behind this guide can be transferred to a CentOS installation of NetBox as well.

Read on for the guide...

Note: Before running most of the commands in this guide, you will need to add "sudo" before each command requiring superuser permissions. Alternatively, you can run once "sudo -s" which executes a shell using sudo.

Suggested First Steps - Upgrade Current Ubuntu Packages

1. Run: apt-get update
2. Run: apt-get upgrade
3. Optionally run: apt-get dist-upgrade

Install New Required Packages

1. Go to the NetBox Installation documentation page and find the commands to install the Ubuntu system packages required by NetBox and its dependencies.
2. Run the provided command.
   • For example run: sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev
3. You will also want to run the command to update pip (Python's package management tool): sudo pip3 install --upgrade pip

Download & Extract the Repository of the New NetBox Version

Important: Make sure you don’t skip major point versions! If necessary, upgrade 2.8.x to 2.9.x to 2.10.x. Take backups or snapshots before any upgrade so you can easily roll back your changes if necessary.

1. Review the official Upgrading to a New NetBox Release documentation page. Especially pay attention to any important adjustments needed when upgrading to new versions as outlined in the release notes.
2. Follow the upgrade instructions for downloading a release. We highly recommend following the procedures under "Option A: Download a Release" over "Option B: Clone the Git Repository." Option B is fewer steps, but Option A makes interim updates much easier to implement when you can't just go to the latest version because your installed version is too old. Skipping major point versions can cause issues so it's important to be able to upgrade to interim versions easily and not always go straight to the latest release. Once the interim release is working properly, repeat this guide for the next version.
   • Make sure your shell is open to a good download location (e.g., your login's home folder) so the wget command downloads the latest release (and any interim releases needed) where you want.
   • E.g., from your Home directory type: wget https://github.com/netbox-community/netbox/archive/v2.10.8.tar.gz
3. Extract the release as detailed in the Option A directions. In this case, the "vX.Y.Z.tar.gz" file refers to the version you are upgrading to.
   • E.g., type: sudo tar -xzf v2.10.8.tar.gz -C /opt
4. Create a symlink from /opt/netbox/ that points to the new release that you extracted.
   • E.g., type: sudo ln -sfn /opt/netbox-2.10.8/ /opt/netbox

Copy Configuration Information & Media to the New Version

1. Copy any configuration files from the previous installation to the new installation. Note that, unlike before, in this case "netbox-X.Y.Z" is the version you are upgrading from.
   • E.g., type: sudo cp /opt/netbox-2.10.4/local_requirements.txt /opt/netbox/
   • E.g., type: sudo cp /opt/netbox-2.10.4/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
   • E.g., type: sudo cp /opt/netbox-2.10.4/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
2. Replicate your uploaded media as well.
   • E.g., type: sudo cp -pr /opt/netbox-2.10.4/netbox/media/ /opt/netbox/netbox/
3. Copy or link any custom scripts and reports that you've made.
   • E.g., type: sudo cp -r /opt/netbox-2.10.4/netbox/scripts /opt/netbox/netbox/
   • E.g., type: sudo cp -r /opt/netbox-netbox-2.10.4/netbox/reports /opt/netbox/netbox/
4. Finally, copy the Gunicorn configuration.
   • E.g., type: sudo cp /opt/netbox-2.10.4/gunicorn.py /opt/netbox/

Make Sure All Package Requirements are Installed

This step is not included in the official upgrade instructions, but it will prevent most of the common upgrade issues.

1. Type: cd /opt/netbox/
2. Type: pip3 install -r requirements.txt
   • Correct any issues before proceeding.
   • If you have trouble getting a newer version of a package, uninstall it then reinstall it:
     1. Type: pip3 uninstall [PackageName]
     2. Type: pip3 install [PackageName]
3. Type: pip3 install -r local_requirements.txt
   • Correct any issues before proceeding.
4. Verify major dependency package versions match the minimum requirements and upgrade if necessary:
   • Type: python -V
   • Type: psql –version
   • Type: redis-cli --version

Run the Upgrade Script

1. Type: cd /opt/netbox/
2. Type: ./upgrade.sh
   • Look for errors in output of the script, make note of them, and correct if necessary.
   • It is OK to run this script more than once.
3. Restart the two NetBox services:
   • Type: sudo systemctl restart netbox netbox-rq
   • Alternatively, reboot the server by typing: reboot now

Verify & Troubleshoot the Upgrade

1. Go to the URL of your NetBox service (e.g., https://netbox.mydomain.com/).
2. Check service statuses:
   • Type: systemctl status netbox
   • Type: systemctl status netbox-rq
3. If either services are not running or have errors, check the logs:
   • Type: journalctl -eu netbox
   • Type: journalctl -eu netbox-rq
   • Type: vi /var/log/nginx/error.log

A common error we have seen here at The Grim Admin is: '/opt/netbox/gunicorn.py' doesn't exist

The simple fix is usually to just reinstall Gunicorn in the default manner as outlined at https://netbox.readthedocs.io/en/stable/installation/4-gunicorn/

Conclusion

We really hope that this guide will help you and save you any headaches when upgrading NetBox to the latest release. Please comment below or in our forums if you have any questions or to discuss NetBox and any other network or system administration topics.

Tag: netbox upgrade ubuntu centos linux troubleshooting