Hello and welcome to module 12 of the NetBox 'Zero-to-Hero' course. In Module 11: Custom Scripts, Eric used a custom script to update the status of the new Brisbane Site, and all the Locations, Racks, Devices, Clusters and VMs from Planned to Active. Eric used another Custom Script to create a site and all the required devices for a new branch office planned for Stockholm, Sweden.
Now that the new Brisbane site is active, the IT Manager has asked Susan to produce some reports from NetBox to make sure that everything has been deployed in line with company standards. These standards are:
- Every device has either an IPv4 or IPv6 Primary address assigned
- Every device meets the required naming convention standard - for example: (site_name)-RTR-1 or (site_name)-SW-2
By the end of this module you will be able to:
- Describe what NetBox reports are and what kind of things they can be used to verify
- Understand the basics of reports and also where to find documentation and examples to help you develop your own reports
- Kick start your own NetBox reports collection, with two example reports to get you up and running
If you'd like to follow along with the examples used in this course, it's super easy to do, and you have a few options:
- Run NetBox as a container with NetBox Docker - This is the quickest way to get your own dedicated NetBox instance going and it only takes a few minutes to spin up on your laptop!
- Follow the official documentation and do a full installation of all the NetBox components. These instructions have been tested on Ubuntu and CentOS Linux.
- Use the public demo instance of NetBox
- Sign up for a free trial of NetBox Cloud (hosted, managed NetBox with enterprise grade capabilities).
The NetBox version used in the video for this module is v3.3.9, and the following course materials used in the demo are available:
From the official NetBox docs
A NetBox report is a mechanism for validating the integrity of data within NetBox. Running a report allows the user to verify that the objects defined within NetBox meet certain arbitrary conditions. For example, you can write reports to check that:
- All top-of-rack switches have a console connection
- Every router has a loopback interface with an IP address assigned
- Each interface description conforms to a standard format
- Every site has a minimum set of VLANs defined
- All IP addresses have a parent prefix
...and so on. Reports are completely customizable, so there's practically no limit to what you can test for.
The official documentation for NetBox reports referenced above is the best source of information on the subject and (as with all modules in this course), this module is meant to compliment the official docs.
As ever with NetBox, you will find that the amazing NetBox Community is a great source of help with any aspect of running NetBox, and reporting is a great example of this. In the Community Reports Git repo, you will find a collection of community submitted and maintained NetBox reports and custom scripts.
There a bunch of reports under different categories (eg. IPAM, DCIM etc) that you can either use as is or tailor to your own reporting requirements. This module will use two example reports from the community reports repo to demonstrate the functionality.
To add reports to your NetBox installation, reports should be saved as files in the REPORTS_ROOT path (which defaults to netbox/reports/).
If you are running NetBox Docker then you will find in your docker-compose.yml file the local directory ./reports on the host you are running docker-compose on, is mounted as a volume in the NetBox container:
volumes:
...
- ./scripts:/etc/netbox/reports:z,ro
Simply copy your reports into ./reports and they will appear in the NetBox container.
You can run reports in one of three ways - Via the Web UI (the focus of this module) by navigating to the report, and clicking the "run report" button at top right, or via the API or the CLI. Again, refer to the official docs for more information on running reports via the API/CLI.
The first report does the following:
- loops over all devices with a status of
active - checks if each device has a primary IPv4 IP address configured
- checks if each device has a primary IPv6 IP address configured
- reports which devices are missing primary IPs
The second report does the following:
- loops over all devices with a status of
active - uses Regular Expression matching to check if the device name meets the naming standards e.g.
AUBRI01-RTR-1 - reports which device names do not match the naming standards
OK, so that's the overview of NetBox reports - let's see them in action!! This video will give you a quick walk through of the code in each report, and show you how to run them from the Web UI and see the results.
If you are following along, don't forget to use the Report Examples.
In this module you have learned what NetBox reports are and what kind of things they can be used to verify. You also learned the basics of reports and where to find documentation and examples to help you develop your own reports. You also kick started your own reports collection, with two example reports to get you up and running.
If you fancy a challenge why not write a report of your own. We'd love to see your Reports, so feel free to share them on the NetBox Zero to Hero channel on the NetDev Community Slack!
If you have any questions as you go through the course then pop on over to the NetBox Zero to Hero channel on the NetDev Community Slack! If you aren't already a member then you can sign up for free here.
- Community Reports Git repo
- Zero To Hero Git Repo
- Official NetBox Documentation
- NetBox Docker
- NetBox Cloud is a hosted solution offered by NetBox Labs