Network Documentation: How to Maintain Topology, IPAM and Port Maps

Which documents does a network need, and how are they kept current? We cover the minimum document set, topology diagrams, address and inventory records with NetBox, and verification methods.
Technical summary
Technology
NetBox, IPAM, DCIM, LLDP, CDP, ARP, MAC table, REST API
Topic
The enterprise network documentation set and how to keep it current
Level
Beginner–intermediate
Prerequisites
  • Read-only access to network devices
  • Existing IP and VLAN lists
In this article8 sections

Network documentation is complete on the day of the initial installation; it starts to age with the first change. A few years later, what remains is a Visio drawing nobody trusts and institutional memory of the “the old sysadmin knew that port” kind. Below we explain what a living document set for an enterprise network should contain, where this information should be kept, and how it stays current by being verified against the devices.

The operational cost of missing documentation

The cost is paid most in a crisis. When an uplink breaks, finding out which buildings are affected, which device on which port an address belongs to during an IP conflict, or the circuit number when opening a fault ticket with the carrier can take longer than the outage itself. There are less visible costs too:

  • Engineering time spent rediscovering the current state before every change
  • Unexpected outages from deleting a VLAN or IP block thought to be unused
  • Longer time for new team members or an external support company to learn the network
  • Being unable to prove network segments and security boundaries in an audit

The goal isn’t to document everything. The minimum information needed for operations and change decisions is kept reliably. Untrustworthy documentation is more dangerous than no documentation, because it lends confidence to the wrong decision. A wrong record misleads silently.

The minimum document set: topology, IPAM, VLANs, port map

The minimum set for a medium-sized enterprise network and the operational question each part answers are below:

Document Content Question it answers
Physical topology (L1) Cabinets, devices, fiber and copper links Where does this cable go?
Logical topology (L2/L3) VLANs, trunks, STP root, subnets, routing Which path does traffic take?
IP address plan (IPAM) Prefix, gateway, DHCP range, purpose, owner Is this address free, and who owns it?
VLAN list VLAN ID, name, subnet, switches it spans Where is this VLAN used?
Port map Switch port, patch panel, wall outlet, connected device What is connected to this port?
Circuit and line information Carrier, circuit no., speed, support contact Whom do I report the fault to?

Two complementary records are added to this set: device inventory (model, serial number, software version, support contract) and management access information (management IP, out-of-band path, console server port). Passwords and shared keys are kept not in the document set but in the password vault; the documentation contains only the name of the vault entry. A sight you may come across is a plain-text enable password in a spreadsheet in a shared folder. That isn’t documentation; it’s a vulnerability. Make ownership and criticality information traceable by linking the devices in the network topology to the organization’s IT asset inventory and data classification records.

Designing the VLAN and address plan is a separate topic; here we focus on keeping a record of the existing plan. For the design side, see the VLAN design in enterprise networks article.

Physical and logical topology diagrams

The number one reason diagrams become unreadable is trying to fit everything onto one page. Separate diagrams by layer:

  • Campus/location view: Buildings, server rooms and the backbone links between them; WAN and internet exits.
  • Physical view: Devices per cabinet, uplink port numbers, fiber/copper type, port-channel members.
  • L2 view: Trunks and the VLANs they carry, the STP root bridge and backup root, MLAG/stack relationships.
  • L3 view: Subnets, gateways (SVI, HSRP/VRRP virtual IP), routing protocol areas, VRFs and firewall crossings.

Every diagram should have a version date, an owner and source data. Taking frequently changing details such as port numbers and IP addresses from the source-of-truth system instead of writing them on the diagram by hand slows down how fast the diagram ages. On the physical side, if cable and port labels don’t follow a standard scheme, the port map will never match the field; for a workable method, see the cable and port labeling with TIA-606 article.

IPAM and DCIM: the source-of-truth approach with NetBox

Spreadsheet- and drawing-based documentation works in small networks, but it can’t hold relationships. You can’t see in a single record which interface an IP address is on and which cable that interface goes to which patch panel through. Open-source IPAM/DCIM tools such as NetBox keep these relationships as a data model: site, cabinet, device, interface, cable, prefix, IP address, VLAN and circuit are linked objects. This approach is called the “source of truth.” The intended state of the network is defined here, and devices and diagrams are compared against it.

Criterion Spreadsheet + drawing NetBox-like SoT
Setup and learning You start right away Requires setup and learning the data model
Object relationships Manual, disconnected In the data model, queryable
Conflict checking None or manual Built in for prefixes and IPs
Automation Limited Read and write via REST API
Visual topology Strong Limited; plugin or separate tool

In practice the two approaches live together: data (IPs, VLANs, ports, cables) in NetBox, high-level architecture diagrams in a drawing tool. Data entry into NetBox usually starts with a bulk import from existing spreadsheets; after that, every new change is recorded in NetBox first. The REST API lets monitoring or configuration backup tools pull the device list from here:

curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Accept: application/json" \
  "https://netbox.corp.local/api/dcim/interfaces/?device=sw-b1-k2-01&limit=100"

The Token header in the example is NetBox’s classic API token format; newer versions also offer a different token format and a Bearer header, so check the REST API documentation for the version you use. Once this link is in place, adding a device to configuration backup with Oxidized or to the monitoring system stops being a separate job. A device not in the inventory isn’t backed up or monitored. That is the strongest incentive to keep the inventory.

Verifying documentation from the device: LLDP/CDP and ARP/MAC tables

The most reliable way to find the gap between documentation and the actual state is to take the information directly from the device. On Cisco IOS/IOS XE, the first commands to check on the console are:

show cdp neighbors detail          ! Cisco neighbors, port and IP
show lldp neighbors detail         ! all LLDP-capable neighbors
show interfaces status             ! port status, VLAN, speed, description
show interfaces trunk              ! trunks and allowed VLANs
show vlan brief                    ! VLANs and access ports
show mac address-table interface GigabitEthernet1/0/12
show ip arp 10.20.30.45            ! IP–MAC mapping on the L3 device

Links between switches are verified with LLDP/CDP: the neighbor table should match the uplink port numbers in the documentation exactly. For end devices, mapping has two stages: the ARP table on the L3 device ties the IP address to the MAC address, and the MAC table on the access switch ties the MAC address to the port. If the MAC appears on a trunk port, the device isn’t on that switch. The chain continues on the downstream switch.

Done by hand, this comparison is laborious. A simple Python script that takes the device output and compares it with the cabling and interface records in the NetBox API reports the differences. Writing port descriptions (description) in a standard format makes mapping much easier; “test,” “new” or an empty description is the first sign in the field that documentation has collapsed.

The process for keeping it current, and ownership

What keeps documentation current isn’t a tool but a process. A working model has four components:

  1. Ownership: Each documentation component (IPAM, port map, diagrams) has a named owner. The owner doesn’t enter everything themselves; they’re responsible for its accuracy.
  2. Link to changes: A change record isn’t closed until the documentation update is complete. The change plan has a “documentation to be updated” line; for the execution side, the template in the network change window planning article includes this line.
  3. Automatic collection: Information that can be taken automatically from the device (serial number, version, interface status, LLDP neighbors) isn’t entered by hand; it’s collected regularly and compared with the SoT.
  4. Periodic audit: At set intervals, field verification is done on a sample: randomly selected ports, cables and IPs are checked against the documentation.

The main source of drift is small emergency changes made in the field: changing a port’s VLAN at night, adding a temporary static route. If a lightweight recording path (a short form or ticket template) isn’t defined for these, drift accumulates. The “temporary” change becomes permanent.

Documentation audit checklist

  • Does every component of the minimum document set exist, and does it have a defined owner?
  • Do diagrams state a version date and source data; is the last update after the last change?
  • Do the prefixes in IPAM match the routing tables and SVIs on the L3 devices?
  • Is every VLAN in the VLAN list defined on the devices; are there VLANs defined on devices but missing from the list?
  • Are the LLDP/CDP adjacencies exactly the same as the switch-to-switch links in the documentation?
  • Does the connected device on a randomly selected sample of ports match the port map?
  • Are the circuit number, carrier support contact and contract information current for every WAN and internet line?
  • Are all devices in the inventory covered by monitoring and configuration backup?
  • Are passwords kept in the password vault rather than in the documentation?

For discovering the existing network, producing the document set and planning the move to a source-of-truth model, our enterprise network consulting service is the starting point; for tying periodic verification of the documentation into the maintenance cycle, our network maintenance, monitoring and periodic checks service is.

Frequently asked questions

Is it mandatory to use NetBox for network documentation?

No. In small networks, well-kept tables and diagrams can be enough. As the number of devices, ports and IPs grows, a source-of-truth tool that holds the relationships between objects and offers an API noticeably reduces the manual synchronization burden.

How often should documentation be updated?

With every change. A change record isn’t closed without updating the documentation. In addition, regular comparison with data collected automatically from devices and periodic field verification on a sample are done.

How do I find which port an IP address is connected to?

Find the IP address’s MAC address in the ARP table on the L3 device, then look for the port where that MAC was learned in the access switches’ MAC address table. If the MAC appears on a trunk port, the chain continues on a downstream switch.

Can passwords be kept in network documentation?

No. Passwords and shared keys are stored in a password vault with audited access; the documentation contains only the name or reference of the relevant entry in the vault.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Network

We build switching, routing, cabling and wireless networks with VLAN segmentation and redundant uplinks, and provide regular maintenance and fault support.

Knowledge Center

Other articles