Your network spreadsheet lies: how we build a source of truth with NetBox

There is one question that stops almost any company dead: what is plugged into port 23 of the ground-floor switch? The honest answer is usually silence, followed by "so-and-so will know" and a spreadsheet somebody last updated when the thing was installed. It is not sloppiness. It is that hardly anyone has ever decided where the truth about their own network lives.

We run our own network and maintain client infrastructure, so we have this conversation often. And we almost always have it at the worst possible moment: mid-outage, with somebody staring into a comms cabinet reading labels that no longer match. This article is about the tool we use to stop that happening, NetBox, but mostly it is about the criteria, which is the part you cannot install.

Documenting is not scanning

When somebody finally decides to sort it out, the first instinct is always the same: run a discovery, sweep the network and dump the result into the tool. It looks sensible and it is the exact opposite of what the project itself recommends. The NetBox documentation puts it plainly: "NetBox intends to represent the desired state of a network versus its operational state. As such, automated import of live network state is strongly discouraged."

That sentence reads like a manual footnote and it actually decides the outcome of the whole project. If you dump in whatever is there, you turn every mistake into policy: the VLAN somebody created at three in the morning to get out of trouble becomes design, the temporary patch cable gets documented as permanent, and the box that was left plugged in "until Monday" enters the inventory with full honours. From then on you cannot use the inventory to detect anything, because it matches reality by construction — including the parts of reality that are wrong.

The short version of our criteria: the inventory holds intent; monitoring looks at reality; and the interesting work lives in the gap between them. An IP that shows up on the network but not in the inventory is a question somebody has to answer. An IP that sits in the inventory and appears nowhere is another one. If your documentation generates itself from the network, neither question exists and you have thrown away the useful part.

What NetBox is, and what it is not

NetBox is an open source project under the Apache 2.0 licence, with a public repository since February 2016 and very active development: as we write this, the latest published release is 4.6.7, from 30 July 2026, with releases every few weeks. It combines two things that live apart in many companies: IP address management (IPAM) and physical infrastructure modelling (DCIM) — sites, cabinets, rack units, devices, ports and cables. On top of that it brings automatic change logging, custom fields, an API and event triggers for automation.

Just as important is the list of what the project declares it is not, because it saves arguments: it is not network monitoring, not a DNS server, not a RADIUS server, not configuration management and not facilities management. If you adopt it expecting it to replace Zabbix or configure your switches, you are in for a disappointment. We run it alongside our Zabbix and SmokePing monitoring, not instead of it: one says how the thing is supposed to be built, the other says how it is running right now.

As for what it takes to keep it running: PostgreSQL 14 or later (the documentation already warns that 14 support disappears in version 4.7, which will require 15), Redis, Python 3.12 to 3.14, and an application server such as Gunicorn or uWSGI behind a reverse proxy. Translated: it is a real application, with its own database and lifecycle, not a file sitting in a shared folder. That is an advantage, and also a decision to take with your eyes open.

The three-question test

Before building anything, this is the test we run to find out whether the existing documentation is worth anything. Three questions, stopwatch running, without phoning anyone:

1. What is at this IP address and who uses it? "I think it is the accounts printer" does not count.
2. If I switch this box off, what stops working? This is the question that separates an inventory from a shopping list.
3. Who changed this last, and when? Without change logging, any argument about an outage ends up resting on memory and opinion.

And a fourth one that is really the one that matters: can a machine answer them? A source of truth differs from a document in that you query it through an API rather than read it. As long as the answer lives in a PDF, a Visio diagram or somebody's head, you do not have documentation: you have memory spread across several people and a nice drawing. Memory goes on holiday, changes jobs and, given time, gets things wrong in perfectly good faith.

What we document and what we deliberately leave out

The most expensive mistake in a documentation project is not documenting too little: it is trying to document everything. A huge, out-of-date model does more harm than four accurate tables, because it earns trust it does not deserve. Our rule is simple: only what somebody is going to maintain gets in, and for everything that gets in you must be able to say at which point in the work it gets updated.

And what we leave out, with equal conviction: the exact position of every patch lead in installations that change weekly, the desktop inventories another tool already keeps, and any data whose only purpose is to make the model look complete in a demo. Documenting something nobody will update is not order: it is debt dressed up as order.

The part you cannot install: the process

A source of truth does not rot all at once. It rots on a Tuesday, when somebody fixes an urgent problem and does not write it down because "I will add it later". The second time, skipping it costs even less. By the tenth, the tool has become a museum and everyone goes back to asking so-and-so, who is now right, because the application lies.

What prevents that is not a feature, it is three boring decisions: that updating the inventory is part of the task rather than a follow-up formality, that there is a periodic review comparing inventory against reality — with a named person who has that review in their calendar — and that decommissioning has a procedure as clear as commissioning. Decommissioning is the universal blind spot: everybody records what they install and almost nobody records what they remove.

We have applied the same reasoning elsewhere and it always ends the same way. When we wrote about why "latest" is not a version in our own deployments, the substance was identical: knowing exactly what is running is not fussiness, it is the only way to roll back on purpose. And when we went through what NIS2 supplier questionnaires actually ask for, the inventory as a source of truth turned up again, this time as a question from a large customer.

When you do not need any of this

If you have one site, two switches and a firewall, do not stand up a database-backed application to document it. A text file in a repository, with change history and genuinely reviewed, solves exactly the same problem and does not add another service to maintain, patch and back up. The question is not how many devices you have, it is how many different people touch the network and how much changes in a month. Once the answer to both stops being "one" and "not much", the file stops holding up.

Nor should you build it if you are not going to put the process in place. It is the recommendation we make most often and the one people like least, because it means admitting the problem was never the tool. A source of truth with no commissioning and decommissioning process lasts about six months, and after that it is one more thing to argue about mid-outage.

At everyWAN we use NetBox as the source of truth for our own network, and the same criteria apply when we design, document and operate somebody else's: almost always inside a wider consulting engagement, alongside designing and running networks and communications. We are not resellers of any particular platform and we recommend based on the case, not on the commission, so sometimes the honest conclusion is that a repository and some discipline will do. And if your network has outgrown that, we close with the usual question: if the person who knows your network best were not there tomorrow, how long would it take the next one to know the same? If the answer is measured in weeks, you do not have a documentation problem: you have an operational risk with a name attached.

Sources (verified): the quote about desired versus operational state and the warning against automated import of live network state, along with the feature list (IPAM with full IPv4/IPv6 parity, DCIM with rack elevations and cabling, automatic change logging, custom fields, event-driven scripts and webhooks) and the explicit list of what NetBox is not (network monitoring, DNS server, RADIUS server, configuration management and facilities management), come from the introduction in the official NetBox documentation. The installation requirements (PostgreSQL 14 or later, with the warning that 14 is deprecated and version 4.7 will require 15; Redis; Python 3.12, 3.13 and 3.14; Gunicorn or uWSGI behind a reverse proxy) come from the installation guide. The Apache 2.0 licence, the repository creation date (February 2016) and release 4.6.7 published on 30 July 2026 come from the project's public repository and its release history, consulted on 6 August 2026. Ours, not our sources': that dumping discovered state turns mistakes into policy, the split between intent and reality, the three-question test and its fourth question, the table of what to document and what not to, the three process decisions, and the entire section on when not to build any of it.