Site icon David Ramsden

Stop Documenting the Network via the Network

As humans, we like patterns and symmetry. Things mostly make sense when there’s a pattern or some logic and I think this is why a lot of network engineers seem to love documenting the network via the network.

There is no substitution for proper documentation.

An example – hostnames. My argument is that the hostname of switches could simply be switch1, switch2, switch3 etc. because if I want to know what the switch is, where it is, what it’s management IP is and all that good stuff, I consult my documentation. Ideally my first port of call is a DCIM. Trying to shove the make, model, location of the device in the hostname is nonsense. What happens if that device moves? Or it’s swapped for a different make or model? Now you have to rename your device, you need to update all your documentation where that device may be referenced, your monitoring platform, RADIUS, TACACS etc.

Another example – interfaces. Just use the next available hole. In theory it’s great to have some kind of pattern with interfaces. Servers will be plugged in to ports 1 – 10, PDU/UPS in to ports 11 – 20, APs in to ports 21 – 30 etc. Does it really matter? No. That’s what documentation is there for. Ultimately someone will either forget the pattern or an exception will have to be made.

And my biggest annoyance – VLAN IDs. I find it embarrassing that network engineers don’t understand the difference between a VLAN and a L3 network. Stop trying to use the VLAN ID to represent an L3 network. For example VLAN 1910 because the L3 network is 10.19.10.0/24. There’s no relationship between the VLAN ID and the L3 network. What happens if you’ve got smaller /31 or /29 transit networks? What happens if you decide to collapse or expand an existing network? VLANs and L3 networks are not a one-to-one mapping. A VLAN ID is just that. It’s a unique identifier. Pick a starting point, such as VLAN ID 10 and increment. This is why we have IPAM applications or even spreadsheets.

Documenting the network via the network is just plain lazy. As the network evolves, this becomes really messy and after several years it’ll be broken.

There is no substitution for good documentation. You don’t need to invest loads of money in tooling if you don’t want to. A spreadsheet will do the job. It may not be the most efficient tool. There are Open Source offerings, such as NetBox, OpenDCIM, phpIPAM, diagrams.net. There are paid for offerings, such as NetBrain, InfoBlox and Visio.

Now the trick is to maintain the documentation. Another story for another day.