Documenting a network of several locations

A network with one router fits on a single sheet. A network with six locations, twenty devices and four tunnels goes in a folder, or it does not get documented at all. The tool does a good part of that work, and it is worth knowing exactly which part.

What the tool gives you

• A handover sheet per device. Name, model, role, time zone, management address, which services are open and from which addresses, the VLAN table with subnet, router address, DHCP, internet and isolation per VLAN, and a port table with the use, the VLAN and the comment for every port. Passwords are not printed by default; there is a tick box to include them.
• A cover sheet for the whole site. The site name, the time zone, a list of every device with model, role and management address, a cabling table from port to port, the VLAN table and the SSIDs.
• Blank lines to fill in. Every device sheet has lines for the serial number and the physical location, and at the bottom for who installed it, on what date and for which customer. They are deliberately empty: the tool does not know those.
• Port comments in the script itself. Every cabled port gets a comment such as to sw-01 ether24 or internet, and with several lines the name of the connection with (backup) after it. Those live on the device, so they survive the folder going missing.
• A rollback script per device, which removes what the first script added, plus a list of the things it cannot undo because they changed an existing value rather than creating something.
• The configuration itself, to save and share. See Saving and sharing. The tool keeps nothing on a server: what you do not save is gone.

What is not on it

This is the part you add yourself, and it is exactly the part a successor needs.

• The locations and their address ranges. The cover sheet names the devices and the cables, but not the rectangles on the board and the range you gave each location. Add that table by hand.
• The tunnels between locations. Each device sheet lists its WireGuard interfaces and their peers, but there is no overview saying: these are the four tunnels, these are the tunnel addresses, and this is what crosses each one.
• Everything you added by hand. A route to a second branch, a bond you turned into a trunk after all, a route distance you changed: none of that is in the generated script, and it disappears when somebody generates and pastes again.
• The physical world. Rack, height unit, patch panel number, which fibre pair, where the UPS is, which power group.
• The provider. Account number, line number, contact details, notice period, and the number you reach at night.
• Where the passwords are, not the passwords themselves. A pointer to the password vault is documentation; a password in a shared folder is an incident.

One document that comes first

Do not start the folder with devices but with half a page answering the questions somebody asks at three in the morning: where does the internet arrive, which location hangs off which, what happens when the head office fails, and who do you call. The rest of the folder is reference; this one sheet is the understanding.

Put at least this on it: a sketch of the locations with their address ranges, which tunnel goes where, which services live centrally and which locally, and what keeps working locally when the tunnel drops. That last one is often the only thing people really want to know.

Record per device

Record per location

Practical habits

• Names that follow a system. The identity has to be unique, the tool reports duplicate names as an error, and a name like zwl-sw-01 says straight away where the thing stands. See Choosing names.
• Keep the board, not only the scripts. The drawing with the locations, the cables and the tunnels is the first thing a successor opens. Save the configuration as soon as it is right, and again after every change.
• Print the cover sheet and the device sheets once, without passwords, and leave them in the cupboard at the location itself. The folder at the office does not help when you are standing in Breda in front of a dead switch.
• Write down what is not set up. No monitoring, no backup schedule, no central logging: that is information, not an embarrassment. See Knowing before your customer calls.
• Walk through the checks and note what you deliberately left standing. A warning you ignore for good reasons is a mystery in a year if nothing says why.

Further reading: Documenting and handing over, Saving and sharing and Rolling out twenty branches.